API Reference¶

uniko is a Rust library, so its API is the set of crates you link and the methods you call — there is no service to wire up. The public surface is the Uniko facade: one owning handle from which you mint agents, open sessions, observe turns, and read memory back. Every signature below is reproduced from the source.

One crate matters for callers:

• uniko-api — the public facade. It contains no logic; its tools module re-exports the curated surface (Uniko, Agent, Session, the view/result types). Depend on this crate and you get the whole reachable surface. The same types are re-exported from uniko-memory, which is where they're defined.

The lower-level engine (KnowledgeBase, PipelineSystem, the recall/answer_query free functions) is still available for embedded/advanced use — see Engine internals.

Uniko — the instance¶

Uniko owns the store, the model runtime, and the ingest pipeline. Build one, mint agents from it, and shutdown when done.

use uniko_memory::Uniko;

let memory = Uniko::in_memory().await?;        // ephemeral
let memory = Uniko::open("./data/kb").await?;  // persistent

use uniko_memory::{EmbeddingConfig, LlmSpec, Uniko};

let memory = Uniko::builder()
    .path("./data/kb")
    .embedding(EmbeddingConfig::bge_small_en_v15())
    .llm(LlmSpec::openai("llm/default", "gpt-4o-mini", None))
    .streaming(true)
    .scope_to_agent()
    .build()
    .await?;

UnikoBuilder (chainable): .path(p) / .in_memory() (location) · .embedding(EmbeddingConfig) · .llm(LlmSpec) (enables answer()) · .raw_config(UnikoConfig) (full override) · .streaming(bool) (enables submit/flush) · .scope_to_agent() / .scope(RecallScope) (read visibility) · .extractor(Arc<dyn ModalityExtractor>) (pluggable modality) · .build().

LlmSpec constructors: openai(alias, model_id, base_url: Option<&str>) (reads OPENAI_API_KEY) · openai_with_key_env(alias, model_id, base_url, key_env) · mistralrs(alias, model_id) (local model).

Agent¶

An Agent binds an identity to the store. Reads can be scoped to what that agent may see.

let agent = memory.agent("assistant");
let bundle = agent.recall("what does the user prefer?").await?;
let answer = agent.answer("when is the deadline?").await?;   // needs .llm(...)

Logic surface: define_rule(name, source) → NodeId · run_rule(name, &cols, params) → Vec<Record> · assume(block) -> AssumeBuilder (what-if, rolled back) · abduce(program, params) -> AbductionResult. See Reasoning with Locy.

Session & Turn¶

A Session is a conversation thread. observe is durable (commits before returning); the streaming verbs need .streaming(true).

let mut session = agent.session("chat-42");
let result = session
    .observe(Turn::new("alice", "here's the spec").attach(IngestSource::path("spec.pdf")))
    .await?;
session.ingest(IngestSource::path("handbook.md")).await?;   // standalone document

Turn (builder): Turn::new(sender, content) · .id(message_id) (idempotency) · .content_type(s) · .at(DateTime<Utc>) · .addressed_to(Vec<String>) · .metadata(k, serde_json::Value) · .attach(IngestSource) · .attachments(iter).

ObserveResult { message: AtomicIngestResult, attachments: Vec<IngestOutcome> } — each attachment's IngestOutcome::Artifact(_).artifact_id is the handle for later retrieval.

Recall results¶

recall/recall_in return a ContextBundle of ranked items, each carrying what it is (kind) and where it came from (sources).

for item in &bundle.items {
    println!("[{:?}] {}", item.kind, item.content);
    for src in &item.sources { /* RecallSource::Message | Attachment | Document */ }
}

Scoping (Scope) — chainable, passed to the _in variants: .sessions([...]) · .participants([...]) · .since(DateTime) · .until(DateTime) · .categories([...]) · .sources([...]) · .as_viewer(Viewer). Dimensions holds the resolved filters; ViewerScope is Unrestricted | As(Viewer).

Typed provenance. Turn::category(..) / Turn::source(..) and IngestSource::with_category(..) / .with_source(..) record a record class and a stable logical source without putting either in searchable prose. A :Source node carries the logical identity (FROM_SOURCE from the Message/Artifact); category and source_id are denormalised onto Message, Artifact, Chunk, Observation and Fact so .categories(..) / .sources(..) filter with a property predicate. Every RecallItem reports its own category and source_id, with None meaning "no category" / "no traceable single source" rather than "filtered out".

Revisions and retirement. IngestSource::with_revision(..) / Turn::revision(..) declare which revision of a source the bytes are. A new revision stamps superseded_at on the previous one and records SUPERSEDES from new to old; Agent::retire_source(..) stamps Source.retired_at (restore_source reverses it). Ordinary recall excludes superseded revisions and retired sources, so replaced or retired evidence cannot ground a current answer; Scope::include_superseded() reaches it, which is how a past result stays attributable to the revision behind it. Nothing is deleted, and retirement lives on the source rather than the content — retiring one source never affects another that merely shares identical bytes.

Re-ingesting the same revision with identical bytes is a no-op; the same revision with changed bytes raises IdConflict, since a revision id is a promise about the content.

Answer¶

agent.answer(...) returns an Answer — the generated text plus the grounding context, citable.

let ans = agent.answer("when is the deadline?").await?;
println!("{}", ans.text);
for src in ans.citations() { /* deduped grounding sources */ }

Data — retrieval¶

agent.data() dereferences the ids that recall hands back.

let view = agent.data().artifact("spec.pdf").await?;        // Option<ArtifactView>
let bytes = agent.data().artifact_bytes("spec.pdf").await?; // Option<Vec<u8>>
let msg = agent.data().message("m-12").await?;              // Option<MessageView>

MessageView { message_id, sender_id, content, timestamp, session_id, addressed_to: Vec<String>, attachments: Vec<String> } · ArtifactView { artifact_id, kind, mime: Option<String>, path: Option<String>, text: String, attached_to_message: Option<String> }.

Goals & tasks¶

agent.goals() is the goal/task lifecycle surface — create, transition, read sliced by phase, and expand a goal's working context.

let g = agent.goals().create(CreateGoalParams { title: "Ship the release".into(), ..Default::default() }).await?;
agent.goals().complete("goal-1", Some(serde_json::json!({ "shipped": true }))).await?;
let active = agent.goals().active().await?;              // Vec<GoalView>
let ctx = agent.goals().context("goal-1").await?;        // Option<GoalContext>

GoalView { goal_id, title, description?, status, phase: GoalPhase, created_at?, deadline?, completed_at?, metrics: Option<Json> } · TaskView { task_id, title, description?, status, phase: TaskPhase, priority?, goal_id?, created_at?, completed_at? } · GoalContext { goal: GoalView, tasks: Vec<TaskView>, sessions, recent_messages, facts, entities }.

GoalPhase Planned · Active · Completed · Abandoned · TaskPhase Planned · Active · Completed · Blocked — derived from the free-form status (+ completed_at); the raw status stays exposed.

Ingest sources¶

A single blob type drives both Turn::attach and Session::ingest.

IngestOutcome is Artifact(ArtifactIngestResult) · Pdf(PdfIngestResult); the result types carry artifact_id + node ids. Unsupported modalities return Err(UnikoError::Unsupported(...)). MIME is resolved explicit → magic-bytes → extension → text, then routed (text/markdown/code/json → artifact, PDF → tiered extractor, image/audio/video → a registered ModalityExtractor).

Recording primitives (low-level)¶

Beyond agent.goals(), the subjective-state free functions are available at the uniko_memory crate root for fine-grained recording. Each takes (&kb, agent_id, params) (except assert_fact / invalidate_fact, which take no agent_id) and the Participant must already exist.

See Agent Tools for the parameter structs and edge wiring.

Access-control policy¶

Facts/Observations carry a visibility (public / private:{id} / team:{id} / org:{id}). Scoped reads filter automatically; you can also apply it directly.

Errors & ids¶

Engine internals¶

Uniko wraps the low-level engine, which remains public for embedded/advanced use. These are the mechanisms the facade exists to hide — reach for them only when you need to.

See Pipelines for the engine's ingest/consolidation/recall internals.

See also¶

• Recall & Retrieval — recall/answer, provenance, and data().
• Agent Tools — goals/tasks and the recording primitives.
• Architecture — how the layers fit together.
• Schema — the node and edge catalog.