Rust SDK

cargo add hyphae-client

[dependencies]
hyphae-client = "0.1"
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
tokio-stream = "0.1"

use hyphae_client::{HyphaeClient, ClientConfig, ClientError, CellInput, CellType, RecallQuery};

let client = HyphaeClient::connect(
    "localhost:50051",
    "hyk_your_key_here",
    ClientConfig::default(),
)
.await?;
client.start_session("my-agent").await?;

use hyphae_client::{HyphaeClient, ClientConfig, ClientError, CellInput, CellType, RecallQuery};
use tokio_stream::StreamExt;

#[tokio::main]
async fn main() -> Result<(), ClientError> {
    // auth is the whole hyk_... key; it rides every RPC as x-hyphae-key and is never parsed.
    let client =
        HyphaeClient::connect("localhost:50051", "hyk_your_key_here", ClientConfig::default())
            .await?;
    client.start_session("my-agent").await?; // opens the live inbox stream

    let node_id = client
        .store(CellInput::new(CellType::Decision, "We ship on Friday"))
        .await?;
    println!("stored {node_id}");

    let hits = client.recall(RecallQuery::new("ship")).await?; // cache-first, server on miss
    for hit in &hits {
        println!("{} {} {}", hit.score, hit.from_cache, hit.content);
    }

    // The inbox is a single-consumer Stream; pin it, then drain it.
    let mut inbox = Box::pin(client.inbox());
    if let Some(item) = inbox.next().await {
        let delivery = item?; // an Err is the terminal fatal error, surfaced exactly once
        println!("delivered {:?}", delivery.delivery.map(|d| d.diff_id));
    }

    client.close().await; // or just drop the client — Drop aborts the receive task
    Ok(())
}

HyphaeClient::connect(
    endpoint: &str,
    auth: &str,
    config: ClientConfig,
) -> Result<HyphaeClient, ClientError>

client.store(cell: CellInput) -> Result<String, ClientError>

client.recall(q: RecallQuery) -> Result<Vec<RecallHit>, ClientError>

client.start_session(agent_id: &str) -> Result<Session, ClientError>

client.place_beacon(interest: String) -> Result<String, ClientError>

client.inbox() -> impl Stream<Item = Result<InboxItem, ClientError>>

client.close() -> ()

pub struct CellInput {
    pub cell_type: CellType,
    pub content: String,
    pub scene_id: Option<String>,
    pub salience: f32, // CellInput::new defaults this to 0.5
}

pub struct RecallQuery {
    pub text: String,
    pub k: usize, // 0 ⇒ use ClientConfig::recall_default_k
    pub cell_types: Option<Vec<CellType>>,
    pub scene_id: Option<String>,
    pub include_inbox: bool,
}

pub struct RecallHit {
    pub node_id: String,
    pub content: String,
    pub cell_type: CellType,
    pub score: f32,
    pub from_cache: bool,
}