# API Reference - ruv-FANN Ecosystem

## Core Libraries

### ruv-FANN Core Neural Network API

#### NeuralNetwork
```rust
use ruv_fann::prelude::*;

// Create network
let mut net = NeuralNetwork::builder()
    .input_size(3)
    .hidden_layers(&[4, 2])
    .output_size(1)
    .activation(Activation::Sigmoid)
    .build()?;

// Training
net.train(&training_data, epochs, learning_rate)?;

// Inference
let output = net.run(&input_data)?;
```

#### TrainingData
```rust
// XOR training example
let training_data = vec![
    ([0.0, 0.0, 1.0], [0.0]),
    ([0.0, 1.0, 1.0], [1.0]),
    ([1.0, 0.0, 1.0], [1.0]),
    ([1.0, 1.0, 1.0], [0.0]),
];
```

### Semantic Cartan Matrix API

#### RootVector Operations
```rust
use semantic_cartan_matrix::micro_core::*;

// Create SIMD-aligned vector
let mut vector = RootVector::new();
vector.set_component(0, 1.0)?;

// Mathematical operations
let norm = vector.norm();
let dot_product = vector.dot(&other_vector);

// Validation
assert!(vector.is_valid());
```

#### CartanMatrix
```rust
use semantic_cartan_matrix::micro_core::*;

// Create Cartan matrix
let mut matrix = CartanMatrix::new(rank)?;
matrix.set_entry(0, 1, -1.0)?; // Off-diagonal entries
matrix.set_entry(1, 0, -1.0)?;

// Validate mathematical properties
assert!(matrix.is_cartan_matrix());
```

#### Attention Mechanisms
```rust
use semantic_cartan_matrix::micro_cartan_attn::*;

// Single-head attention
let attention = CartanAttention::new(
    input_dim: 256,
    output_dim: 256,
)?;

let output = attention.forward(&query, &key, &value)?;

// Multi-head attention
let multi_head = MultiHeadAttention::new(
    num_heads: 8,
    input_dim: 512,
    head_dim: 64,
)?;

let attended = multi_head.forward(&input)?;
```

### Swarm Orchestration API

#### SwarmOrchestrator
```rust
use semantic_cartan_matrix::micro_swarm::*;

// Create orchestrator
let mut orchestrator = SwarmOrchestrator::new(
    SwarmConfig {
        max_agents: 10,
        strategy: CoordinationStrategy::Hierarchical,
        consensus_threshold: 0.66,
    }
)?;

// Register agent
let agent = Box::new(MyMicroNet::new(config));
orchestrator.register_agent(agent)?;

// Orchestrate task
let task = Task::new("process_data", priority::HIGH);
let result = orchestrator.orchestrate(task).await?;
```

## REST API Endpoints

### Swarm Management

#### Create Swarm
```http
POST /api/v1/swarms
Content-Type: application/json

{
  "name": "research-swarm",
  "strategy": "balanced", 
  "maxAgents": 10
}
```

#### Get Swarm Status
```http
GET /api/v1/swarms/{swarmId}/status

Response:
{
  "id": "swarm-123",
  "status": "active",
  "agents": 5,
  "tasks": {
    "pending": 2,
    "running": 3,
    "completed": 45
  }
}
```

### Agent Management

#### Spawn Agent
```http
POST /api/v1/swarms/{swarmId}/agents
Content-Type: application/json

{
  "name": "research-agent",
  "type": "researcher",
  "capabilities": ["analysis", "search"],
  "neuralConfig": {
    "architecture": {
      "input_size": 256,
      "hidden_layers": [128, 64],
      "output_size": 32
    }
  }
}
```

## JavaScript/TypeScript SDK

### RuvSwarm Client
```typescript
import { RuvSwarm, SwarmConfig } from 'ruv-swarm';

// Initialize
const ruvSwarm = await RuvSwarm.initialize({
  wasmPath: './node_modules/ruv-swarm/wasm',
  useSIMD: true
});

// Create swarm
const swarm = await ruvSwarm.createSwarm({
  name: 'analysis-swarm',
  strategy: 'adaptive',
  maxAgents: 8
});

// Spawn agents
const agents = await Promise.all([
  swarm.spawn({ type: 'researcher', name: 'r1' }),
  swarm.spawn({ type: 'analyst', name: 'a1' }),
  swarm.spawn({ type: 'coder', name: 'c1' })
]);

// Execute task
const result = await swarm.orchestrate({
  description: 'Analyze dataset',
  priority: 'high',
  parameters: { 
    dataset: 'data.csv',
    method: 'statistical'
  }
});
```

### Neural Network Integration
```typescript
import { NeuralNetwork } from 'ruv-swarm/neural';

// Create network with WASM acceleration
const network = new NeuralNetwork({
  architecture: [784, 128, 64, 10],
  activation: 'relu',
  optimizer: 'adam',
  useSIMD: true
});

// Train
await network.train(trainingData, {
  epochs: 100,
  batchSize: 32,
  learningRate: 0.001
});

// Predict
const predictions = await network.predict(testData);
```

## Python Integration (PyO3)

```python
import ruv_swarm

# Initialize with WASM
swarm = ruv_swarm.RuvSwarm()
await swarm.initialize(use_simd=True)

# Create swarm
swarm_config = {
    'name': 'python-swarm',
    'strategy': 'hierarchical',
    'max_agents': 6
}

instance = await swarm.create_swarm(swarm_config)

# Spawn specialized agents
researcher = await instance.spawn({
    'name': 'researcher-1',
    'type': 'researcher',
    'capabilities': ['data_analysis', 'web_search']
})

# Execute coordinated task
task = {
    'description': 'Market analysis',
    'priority': 'high',
    'parameters': {
        'timeframe': '30d',
        'sectors': ['tech', 'finance']
    }
}

result = await instance.orchestrate(task)
print(f"Analysis complete: {result}")
```

## Error Handling

### Rust Error Types
```rust
use semantic_cartan_matrix::prelude::*;

match result {
    Ok(value) => println!("Success: {:?}", value),
    Err(CartanError::InvalidDimension(msg)) => {
        eprintln!("Dimension error: {}", msg);
    },
    Err(CartanError::MathematicalConstraint(msg)) => {
        eprintln!("Mathematical constraint violation: {}", msg);
    },
    Err(CartanError::SwarmCoordination(msg)) => {
        eprintln!("Swarm coordination failed: {}", msg);
    }
}
```

### JavaScript Error Handling
```typescript
try {
    const result = await swarm.orchestrate(task);
    console.log('Success:', result);
} catch (error) {
    if (error.code === 'SWARM_001') {
        console.error('Swarm initialization failed:', error.message);
    } else if (error.code === 'AGENT_002') {
        console.error('Agent spawn timeout:', error.message);
    } else {
        console.error('Unknown error:', error);
    }
}
```

## Configuration

### Rust Configuration
```rust
use semantic_cartan_matrix::config::*;

let config = SwarmConfig {
    max_agents: 10,
    strategy: CoordinationStrategy::Adaptive,
    neural_config: NeuralConfig {
        precision: Precision::F32,
        simd_enabled: true,
        memory_pool_size: 1024 * 1024, // 1MB
    },
    persistence: PersistenceConfig::SQLite {
        path: "./swarm.db".into(),
        connection_pool_size: 10,
    },
};
```

### Environment Variables
```bash
# Performance
RUV_SWARM_MAX_AGENTS=10
RUV_SWARM_USE_SIMD=true
RUV_SWARM_MEMORY_POOL=2GB

# Networking
RUV_SWARM_HOST=0.0.0.0
RUV_SWARM_PORT=3001
RUV_SWARM_WEBSOCKET_PORT=3002

# Database
RUV_SWARM_DB_URL=sqlite://swarm.db
RUV_SWARM_DB_POOL_SIZE=10

# Logging
RUST_LOG=info
RUV_SWARM_LOG_LEVEL=debug
```

This API reference provides comprehensive coverage of all public interfaces available in the ruv-FANN ecosystem, from low-level mathematical operations to high-level swarm orchestration.