tdln-brain

Deterministic Cognitive Layer for LogLine OS

Render a narrative frame → call an LLM → extract only JSON → validate into tdln_ast::SemanticUnit.

Why

• Prevent tool-call hallucinations: strict JSON-only outputs
• Enforce determinism: temperature 0, JSON mode when available
• Separate reasoning: optional thinking goes before JSON, not mixed
• Machine-legible failures: invalid output → BrainError::Hallucination

Quickstart

use tdln_brain::{Brain, CognitiveContext, GenerationConfig};
use tdln_brain::providers::local::LocalEcho;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let brain = Brain::new(LocalEcho);
    let ctx = CognitiveContext {
        system_directive: "You are a planner".into(),
        ..Default::default()
    };
    let decision = brain.reason(&ctx, &GenerationConfig::default()).await?;
    println!("{:?}", decision.intent);
    Ok(())
}

Features

Providers

OpenAI

use tdln_brain::providers::openai::OpenAiDriver;

let driver = OpenAiDriver::new(api_key, "gpt-4o-mini");
let brain = Brain::new(driver);

Anthropic

use tdln_brain::providers::anthropic::AnthropicDriver;

let driver = AnthropicDriver::new(api_key, "claude-3-sonnet-20240229");
let brain = Brain::new(driver);

Local/Mock

use tdln_brain::providers::local::{LocalEcho, MockBackend};

// Fixed noop response
let brain = Brain::new(LocalEcho);

// Custom response
let mock = MockBackend::with_intent("grant", serde_json::json!({"to": "alice"}));
let brain = Brain::new(mock);

CognitiveContext

The context controls what the model sees:

let ctx = CognitiveContext {
    // Identity + role + boundaries
    system_directive: "You are a finance agent.".into(),
    
    // Long-term memory (RAG results, user facts)
    recall: vec!["User balance: 420".into()],
    
    // Recent conversation
    history: vec![Message::user("Plan a budget")],
    
    // Kernel constraints (violations → gate rejection)
    constraints: vec!["No transfers > 500".into()],
};

Error Model

Guarantees

• ✅ #![forbid(unsafe_code)]
• ✅ Strict parse: invalid JSON → BrainError::Hallucination
• ✅ Optional reasoning: model can think, but JSON wins
• ✅ Usage metadata: token counts for budgeting

OS Integration

• With ubl-mcp: feed Decision.intent into tool selection; preflight via Gate; audit via Ledger
• With ubl-office: run Brain::reason in the OODA loop; persist to ledger; schedule Dreaming separately
• Token budget: use util::clamp_budget to manage context windows

License

MIT — See LICENSE