Converge Core

A correctness-first, context-driven multi-agent runtime library.

Website: converge.zone | Docs: docs.rs | Crates.io: converge-core

Installation

[dependencies]
converge-core = "0.6"

Overview

converge-core is the foundational semantic engine for the Converge ecosystem. It provides:

• Context — Shared, append-only state for agent collaboration
• Engine — Convergence loop with parallel execution and deterministic commit
• Agent Trait — Interface for implementing capabilities
• Invariants — Runtime constraint enforcement (Gherkin-style)
• Capability Abstractions — Traits for Embedding, Reranking, VectorRecall, GraphRecall

Related Crates

Core Principles

• Context is the API — Agents collaborate through shared data, not direct calls
• Convergence is mandatory — Execution proceeds until a fixed point is reached
• Correctness over availability — Wrong answers are worse than no answers

Quick Start

use converge_core::{Engine, Context, ContextKey, Fact, Agent, AgentEffect};

// Define a simple agent
struct GreetingAgent;

impl Agent for GreetingAgent {
    fn name(&self) -> &str { "greeting" }
    fn dependencies(&self) -> &[ContextKey] { &[ContextKey::Seeds, ContextKey::Signals] }

    fn accepts(&self, ctx: &Context) -> bool {
        ctx.has(ContextKey::Seeds) &&
        !ctx.get(ContextKey::Signals).iter().any(|f| f.id.starts_with("greeting-"))
    }

    fn execute(&self, _ctx: &Context) -> AgentEffect {
        AgentEffect::with_fact(Fact::new(
            ContextKey::Signals,
            "greeting-response",
            "Hello from Converge!",
        ))
    }
}

fn main() {
    let mut engine = Engine::new();
    engine.register(GreetingAgent);

    let mut ctx = Context::new();
    ctx.add_fact(Fact::new(ContextKey::Seeds, "input", "Start")).unwrap();

    let result = engine.run(ctx).expect("should converge");
    println!("Converged in {} cycles", result.cycles);
}

Agent Idempotency Contract

All agents must follow this rule:

An agent has contributed if any artifact it emitted exists in the context — regardless of acceptance or validation.

impl Agent for MyAgent {
    fn dependencies(&self) -> &[ContextKey] {
        // Include BOTH input AND output keys
        &[ContextKey::Seeds, ContextKey::Hypotheses]
    }

    fn accepts(&self, ctx: &Context) -> bool {
        // 1. Check precondition
        if !ctx.has(ContextKey::Seeds) { return false; }

        // 2. Check idempotency (context-based, not hidden state)
        let my_prefix = format!("{}-", self.name());
        !ctx.get(ContextKey::Hypotheses)
            .iter()
            .any(|f| f.id.starts_with(&my_prefix))
    }

    fn execute(&self, _ctx: &Context) -> AgentEffect {
        AgentEffect::with_fact(Fact::new(
            ContextKey::Hypotheses,
            "myagent-result-1",
            "derived content",
        ))
    }
}

Capability Abstractions (v0.6+)

use converge_core::capability::{Embedding, Reranking, VectorRecall, GraphRecall};

// Traits for provider implementations:
// - Embedding: text/image embeddings
// - Reranking: re-rank search results
// - VectorRecall: vector similarity search
// - GraphRecall: graph pattern matching

Public API

Core Types

• Engine — The convergence runtime
• Context — Shared job state
• Agent — Agent trait for capabilities
• AgentEffect — Buffered output from agents
• Fact — Trusted facts in context
• ProposedFact — LLM suggestions requiring validation

Invariants

• Invariant — Runtime constraint trait
• InvariantClass — Structural, Semantic, Acceptance

Capabilities

• Embedding — Embedding generation trait
• Reranking — Re-ranking trait
• VectorRecall — Vector store trait
• GraphRecall — Graph store trait

Guarantees

• Determinism: Same input → same output
• Termination: Budgets prevent infinite loops
• Isolation: Agents never call each other
• Auditability: All changes are traceable

Testing

# Run convergence axiom tests
cargo test -p converge-core --test engine_convergence_axioms -- --nocapture

# Run all tests
cargo test -p converge-core

Repository

This crate is part of the Converge project.

Standalone repo: github.com/kpernyer/converge-core

License

Proprietary (Aprio One AB)