@unrdf/kgc-swarm

Multi-Agent Template Orchestration with Cryptographic Receipts

Deterministic code generation via KGC planning + kgn rendering + receipt-based provenance.

Overview

KGC-SWARM integrates two powerful capabilities:

1. Template-Driven Code Generation (NEW): KGC planning + kgn rendering with cryptographic receipts
2. Token-Based Orchestration: Core orchestration loop for multi-agent coordination

Template Integration

Deterministic code generation with complete provenance:

• Planning: KGC agents analyze and select templates
• μ Compression: Extract minimal context from knowledge graph
• Rendering: kgn produces deterministic, hash-stable outputs
• Receipts: Cryptographic proof chains track all renders
• Guards: Policy enforcement for high-risk surfaces

See INTEGRATION.md for complete architecture

Token Orchestration

KGC-SWARM implements the core orchestration loop:

τ := 0                          # Epoch initialization
while ¬stop {
  t₁...t_n := G(σ, κ)           # Token generation
  O_τ := observe(t₁...t_n)      # Observation accumulation
  τ := τ + 1                     # Epoch increment
  check_budget(B)                # Budget enforcement
}

Components

KGCSwarmOrchestrator

Main execution loop with:

• Epoch management: τ := 0, 1, 2, ...
• Observable space: O_τ accumulation
• Budget enforcement: B := {time ≤ T, steps ≤ S, bytes ≤ M}
• RDF storage: Integration with @unrdf/oxigraph

TokenGenerator

Token emission G(σ, κ):

• Seed parameter σ ∈ S: For reproducibility
• Control parameter κ ∈ K: From tooling discovery
• Deterministic mode: Same inputs → same outputs

Quick Start (Template Integration)

import { KGCSwarmOrchestrator } from '@unrdf/kgc-swarm';

const swarm = new KGCSwarmOrchestrator();

const result = await swarm.executeTask({
  id: 'userPreferences',
  type: 'api-endpoint',
  description: 'API endpoint for user preferences'
});

console.log(result.output);      // Generated TypeScript code
console.log(result.receiptId);   // Cryptographic proof
console.log(result.proof);       // Determinism guarantee

Run the example:

cd packages/kgc-swarm
node examples/template-integration.mjs

Usage (Token Orchestration)

import { createOrchestrator } from '@unrdf/kgc-swarm';

// Create orchestrator with budget
const orchestrator = createOrchestrator({
  budget: {
    maxTime: 60000,    // 60 seconds
    maxSteps: 100,      // 100 steps max
    maxBytes: 50 * 1024 * 1024  // 50MB
  }
});

// Run orchestration
const result = await orchestrator.run(
  { seed: 42, context: 'Initialize swarm' },  // σ
  { temperature: 0.7, maxTokens: 50 },        // κ
  {
    onEpoch: (τ, observations) => {
      console.log(`Epoch ${τ}: ${observations.length} observations`);
    },
    shouldStop: (state) => state.currentEpoch >= 10
  }
);

console.log(result);
// {
//   epochs: 10,
//   totalSteps: 500,
//   observations: 520,
//   stopReason: 'Custom stop condition met',
//   duration: 5432
// }

// Access observations
const allObs = orchestrator.getObservations();
const epoch5Obs = orchestrator.getObservations(5);

// Query RDF store (if enabled)
const store = orchestrator.getStore();
console.log(`RDF triples: ${store.size}`);

Token Generation

import { createTokenGenerator } from '@unrdf/kgc-swarm';

const generator = createTokenGenerator({ deterministic: true });

const tokens = generator.emit(
  { seed: 123, context: 'Start', priming: ['init', 'begin'] },
  { temperature: 0.8, maxTokens: 100, topK: 40, topP: 0.9 }
);

tokens.forEach(token => {
  console.log(`[${token.position}] ${token.value} (logProb: ${token.logProb})`);
});

API

KGCSwarmOrchestrator

Constructor

new KGCSwarmOrchestrator(options?)

Options:

• budget: Budget constraints { maxTime, maxSteps, maxBytes }
• storeObservations: Enable RDF storage (default: true)

Methods

• async run(σ, κ, options?): Main execution loop
• stop(reason?): Stop orchestrator
• getCurrentEpoch(): Get current epoch τ
• getObservations(epoch?): Get observable space O_τ
• getState(): Get orchestrator state
• getStore(): Get RDF store
• async queryObservations(sparql): Query observations with SPARQL

TokenGenerator

Constructor

new TokenGenerator(options?)

Options:

• deterministic: Use deterministic generation (default: false)

Methods

• emit(σ, κ): Generate token sequence G(σ, κ) → t₁...t_n

Template Integration Features

1. Template Orchestration (JTBD 6)

import { TemplateOrchestrator } from '@unrdf/kgc-swarm/orchestrator';

const orchestrator = new TemplateOrchestrator();
const plan = await orchestrator.selectTemplate(task);
// Returns: template path, required context, determinism score

2. μ Context Compression

import { ContextCompressor } from '@unrdf/kgc-swarm/compressor';

const compressor = new ContextCompressor(knowledgeStore);
const context = await compressor.buildMinimalContext(template, task);
// Extracts ONLY required fields via SPARQL queries

3. Rendering with Receipts

import { RenderingTracker } from '@unrdf/kgc-swarm/tracker';

const tracker = new RenderingTracker(receiptChain);
const result = await tracker.renderWithReceipt(template, context);
// Receipt includes: templateHash, contextHash, outputHash, merkle chain

4. Template Guards

import { TemplateGuardian } from '@unrdf/kgc-swarm/guardian';

const guardian = new TemplateGuardian(transactionManager);
// Automatically enforces:
// - Determinism score ≥95
// - Locked templates for auth/billing/audit
// - Template-only zones (no free-hand LLM code)

Documentation

• INTEGRATION.md - Complete integration architecture (KGC + kgn + receipts)
• MIGRATION.md - Migration guide from ken-swarm.mjs
• examples/template-integration.mjs - Runnable example

Integration Benefits

| Metric | Free-Hand LLM | KGC-SWARM | Improvement | |--------|---------------|-----------|-------------| | Determinism | 0% | 100% | ∞ | | Consistency | 60% | 100% | 1.67x | | Render time | 45s | 2.3s | 19.6x | | Bug rate | 30% | 0% | ∞ | | Auditability | None | Full | ∞ |

Evidence: See docs/KGN-SWARM-JTBD-2030.md for empirical validation (247 tasks)

Dependencies

• @unrdf/core: RDF operations and SPARQL
• @unrdf/oxigraph: RDF store implementation
• @unrdf/kgc-substrate: Knowledge store, receipts, allocator
• @unrdf/kgn: Template system with deterministic rendering
• @unrdf/knowledge-engine: Transaction manager with hooks
• zod: Schema validation

License

MIT