mantr-sdk 1.0.0

# Mantr Rust SDK

> **High-Performance Deterministic Memory for Rust**

[![Crates.io](https://img.shields.io/crates/v/mantr-sdk.svg)](https://crates.io/crates/mantr-sdk)
[![Documentation](https://docs.rs/mantr-sdk/badge.svg)](https://docs.rs/mantr-sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## Installation

```toml
[dependencies]
mantr-sdk = "1.0"
tokio = { version = "1", features = ["full"] }
```

## Quick Start

```rust
use mantr_sdk::{MantrClient, WalkRequest};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = MantrClient::new("vak_live_...")?;
    
    let result = client.walk(WalkRequest {
        phonemes: vec!["dharma".into(), "karma".into()],
        pod: None,
        depth: Some(3),
        limit: Some(100),
    }).await?;
    
    println!("Found {} paths", result.paths.len());
    Ok(())
}
```

---

## AI & Agentic Patterns

### 1. Axum RAG Server

```rust
use axum::{Router, extract::State, Json};
use mantr_sdk::MantrClient;
use serde::{Deserialize, Serialize};
use std::sync::Arc;

#[derive(Clone)]
struct AppState {
    mantr: Arc<MantrClient>,
}

#[derive(Deserialize)]
struct QueryRequest {
    question: String,
}

#[derive(Serialize)]
struct QueryResponse {
    answer: String,
    context: Vec<String>,
}

async fn rag_handler(
    State(state): State<AppState>,
    Json(req): Json<QueryRequest>,
) -> Json<QueryResponse> {
    // Get context from Mantr
    let context = state.mantr.walk(WalkRequest {
        phonemes: extract_concepts(&req.question),
        depth: Some(4),
        limit: Some(20),
        ..Default::default()
    }).await.unwrap();
    
    // Format paths
    let paths: Vec<String> = context.paths
        .iter()
        .map(|p| p.nodes.join(" → "))
        .collect();
    
    // Generate answer with LLM (using context)
    let answer = generate_with_llm(&req.question, &paths).await;
    
    Json(QueryResponse { answer, context: paths })
}

#[tokio::main]
async fn main() {
    let state = AppState {
        mantr: Arc::new(MantrClient::new("vak_live_...").unwrap()),
    };
    
    let app = Router::new()
        .route("/query", post(rag_handler))
        .with_state(state);
    
    axum::Server::bind(&"0.0.0.0:3000".parse().unwrap())
        .serve(app.into_make_service())
        .await
        .unwrap();
}
```

### 2. Parallel Processing with Rayon

```rust
use mantr_sdk::MantrClient;
use rayon::prelude::*;

async fn batch_walk(concepts: Vec<Vec<String>>) -> Vec<WalkResponse> {
    let client = Arc::new(MantrClient::new("vak_live_...").unwrap());
    
    let handles: Vec<_> = concepts
        .into_par_iter()
        .map(|phonemes| {
            let client = client.clone();
            tokio::spawn(async move {
                client.walk(WalkRequest {
                    phonemes,
                    ..Default::default()
                }).await
            })
        })
        .collect();
    
    // Wait for all
    let mut results = vec![];
    for handle in handles {
        if let Ok(Ok(result)) = handle.await {
            results.push(result);
        }
    }
    
    results
}
```

### 3. Actor Model with Actix

```rust
use actix::prelude::*;
use mantr_sdk::{MantrClient, WalkRequest};

struct MantrActor {
    client: MantrClient,
}

impl Actor for MantrActor {
    type Context = Context<Self>;
}

#[derive(Message)]
#[rtype(result = "Result<WalkResponse, MantrError>")]
struct WalkMessage {
    phonemes: Vec<String>,
}

impl Handler<WalkMessage> for MantrActor {
    type Result = ResponseFuture<Result<WalkResponse, MantrError>>;
    
    fn handle(&mut self, msg: WalkMessage, _: &mut Self::Context) -> Self::Result {
        let client = self.client.clone();
        
        Box::pin(async move {
            client.walk(WalkRequest {
                phonemes: msg.phonemes,
                ..Default::default()
            }).await
        })
    }
}

// Usage
let actor = MantrActor {
    client: MantrClient::new("vak_live_...").unwrap()
}.start();

let result = actor.send(WalkMessage {
    phonemes: vec!["test".into()]
}).await;
```

### 4. Streaming with Tower

```rust
use tower::{Service, ServiceBuilder};
use futures::stream::{Stream, StreamExt};

struct MantrService {
    client: MantrClient,
}

impl Service<Vec<String>> for MantrService {
    type Response = WalkResponse;
    type Error = MantrError;
    type Future = Pin<Box<dyn Future<Output = Result<Self::Response, Self::Error>>>>;
    
    fn call(&mut self, phonemes: Vec<String>) -> Self::Future {
        let client = self.client.clone();
        
        Box::pin(async move {
            client.walk(WalkRequest {
                phonemes,
                ..Default::default()
            }).await
        })
    }
}
```

---

## API Reference

```rust
use mantr_sdk::{MantrClient, WalkRequest, WalkResponse};

// Initialize
let client = MantrClient::new("vak_live_...")?;

// Walk
let result = client.walk(WalkRequest {
    phonemes: vec!["concept".into()],
    pod: None,
    depth: Some(3),
    limit: Some(100),
}).await?;

// Response
pub struct WalkResponse {
    pub paths: Vec<PathResult>,
    pub latency_us: u64,
    pub credits_used: u32,
}

pub struct PathResult {
    pub nodes: Vec<String>,
    pub score: f64,
    pub depth: u32,
}
```

---

## License

MIT