ai3-lib 0.2.0

AI3 support library for PoT-O validator and miner components
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

# ai3-lib

[![crates.io](https://img.shields.io/crates/v/ai3-lib.svg)](https://crates.io/crates/ai3-lib)
[![docs.rs](https://img.shields.io/docsrs/ai3-lib)](https://docs.rs/ai3-lib)
[![CI](https://img.shields.io/github/actions/workflow/status/TribeWarez/ai3-lib/ci.yml?branch=main)](https://github.com/TribeWarez/ai3-lib/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

AI3 support library for PoT-O validator and miner components.

**Current Version**: v0.1.6-alpha | **Planned**: v0.2.0 with Tensor Types

- **Crate:** [crates.io/crates/ai3-lib](https://crates.io/crates/ai3-lib)
- **Docs:** [docs.rs/ai3-lib](https://docs.rs/ai3-lib)
- **Repository:** [github.com/TribeWarez/ai3-lib](https://github.com/TribeWarez/ai3-lib)

## Usage

```toml
[dependencies]
ai3-lib = "0.2"
```

Depends on `pot-o-core`. When used inside the pot-o-validator workspace, the workspace member is used automatically.

## Core Components

### Tensor Engine
- Quantum-inspired tensor calculations
- Fixed-point arithmetic (1e6 scale)
- Entropy and mutual information computation
- Entanglement state tracking

### ESP Compatibility Layer
- Support for ESP32/ESP8266 microcontrollers
- Embedded mining firmware compatibility
- Low-power operation modes
- WASM compilation support

### Mining Operations
- Challenge-response protocol
- MML (Minimal Memory Loss) computation
- Neural path signature generation
- Proof assembly and formatting

### AI3 Protocol Support
- Protocol message parsing and validation
- State machine implementation
- Message serialization/deserialization

## Tensor Types (v0.2.0)

```rust
use ai3_lib::tensor::{EntropyValue, CoherenceFactor, TensorState};

// Fixed-point entropy at 1e6 scale
let entropy = EntropyValue::from_u64(500_000); // 0.5

// Device coherence factor
let coherence: CoherenceFactor = 1.0; // ASIC baseline

// Quantum state
let state = TensorState::new(bond_dimension);
```

## Example: Entropy Calculation

```rust
use ai3_lib::tensor::{TensorEngine, EntropyValue};

let engine = TensorEngine::new();
let entropy = engine.calculate_entropy(&pool_state)?;
println!("Pool entropy: {}", entropy.to_f64());

// Fixed-point scale: 1e6 = 1.0
let normalized = entropy.as_u64() as f64 / 1_000_000.0;
```

## ESP32 Usage

```rust
use ai3_lib::esp::EspMiner;

let mut miner = EspMiner::new();
let challenge = miner.receive_challenge()?;
let proof = miner.solve_challenge(&challenge)?;
miner.submit_proof(&proof)?;
```

## Error Handling

```rust
use ai3_lib::error::{Ai3Error, Ai3Result};

fn compute_path() -> Ai3Result<Vec<u64>> {
    // Returns Err(Ai3Error::...) on failure
    Ok(vec![...])
}
```

## Testing

Run tests:
```bash
cargo test --lib ai3_lib --no-default-features  # No ESP
cargo test --lib ai3_lib --features wasm        # WASM support
```

## Documentation

Full API documentation at [docs.rs/ai3-lib](https://docs.rs/ai3-lib)

## Versioning

Releases follow semantic versioning. To publish:

1. Bump `version` in `Cargo.toml`.
2. Create a tag: `git tag v0.1.1 && git push origin v0.1.1`.
3. CI will publish to crates.io and create a GitHub Release.

## License

[MIT](LICENSE)