Crate tempo_x402_soul

Expand description

§tempo-x402-soul

Autonomous agentic soul for x402 nodes.

Runs a plan-driven execution loop powered by Gemini: observe → create goals → plan steps → execute → reflect → repeat.

§Architecture

Every N seconds:
  observe → read nudges → check stagnation → get/create plan
  → execute next step → advance plan → housekeeping → sleep

Steps that don’t call LLM: ReadFile, SearchCode, ListDir, RunShell, Commit, CheckSelf, CreateScriptEndpoint, CargoCheck.

Steps that do call LLM: GenerateCode, EditCode, Think.

§Capabilities

Plan-driven execution — goals decompose into deterministic step sequences
Feedback loop — structured plan outcomes, error classification, lessons fed back into prompts
Capability tracking — per-skill success rates, profile-guided planning
Neuroplastic memory — salience scoring, tiered decay
World model — structured beliefs about self, endpoints, codebase, strategy
Coding agent — read, write, edit files, run shell, git commit/push/PR
Script endpoints — create instant bash-based HTTP endpoints
Peer coordination — discover siblings, call paid services, exchange catalogs
Fitness evolution — 5-component fitness score with trend gradient
Interactive chat — session-based conversation with plan context injection

Without a GEMINI_API_KEY, the soul runs in dormant mode: it still observes and records snapshots, but skips all LLM calls.

§Key modules

thinking — main plan-driven loop
plan — plan types, step execution, plan status
prompts — focused prompt builders (goal creation, planning, code generation, replan, reflection)
feedback — structured plan outcomes, error classification, lesson extraction
capability — per-skill success rate tracking and profile-guided planning
tools — tool executor: shell, file ops, git, endpoints, peers
git — branch-per-VM git workflow with fork support
coding — pre-commit validation pipeline (cargo check → test → commit)
db — SQLite: thoughts, goals, plans, nudges, beliefs, chat sessions
fitness — 5-component fitness scoring with trend gradient
chat — session-based interactive chat with plan context
neuroplastic — salience scoring, memory decay

Part of the tempo-x402 workspace.

Re-exports§

pub use chat::handle_chat;
pub use chat::ChatReply;
pub use config::SoulConfig;
pub use db::ChatMessage;
pub use db::ChatSession;
pub use db::Nudge;
pub use db::SoulDatabase;
pub use error::SoulError;
pub use events::compute_health;
pub use events::emit_event;
pub use events::EventFilter;
pub use events::EventRefs;
pub use events::HealthSummary;
pub use events::SoulEvent;
pub use memory::Thought;
pub use memory::ThoughtType;
pub use observer::NodeObserver;
pub use observer::NodeSnapshot;
pub use plan::Plan;
pub use plan::PlanStatus;
pub use plan::PlanStep;
pub use thinking::ThinkingLoop;
pub use tools::ToolExecutor;
pub use world_model::Goal;
pub use world_model::GoalStatus;

Modules§

acceleration: Learning Acceleration: the second derivative of intelligence.
autonomy: Autonomy: Autonomous Planning + Recursive Self-Improvement.
benchmark: Opus IQ Benchmark — embedded benchmark for measuring coding intelligence.
bloch: Bloch Sphere Cognitive State — continuous cognitive geometry.
brain: Neural network “fast brain” — a from-scratch feedforward net in pure Rust.
capability: Capability tracking: per-skill success rate measurement.
chat: Interactive chat handler for the soul.
code_quality: Code quality integration — thin orchestration wrapper around x402_model::CodeQualityModel.
codegen: Code generation model orchestration — Phase 3.
coding: Coding orchestration: stage → validate → peer review → commit → push pipeline.
cognitive_cartridge: Cognitive Cartridge Orchestrator — route cognitive calls through WASM cartridges.
collective: Collective consciousness — the colony as ONE distributed mind.
colony: Colony-level selection pressure: competition + cooperation between agents.
computer_use: Computer use: screenshot capture, mouse/keyboard simulation, screen understanding.
config: Soul configuration from environment variables.
cortex: The Cortex: a predictive world model with curiosity-driven exploration, dream consolidation, and emotional valence.
db: Soul database: sled-backed lock-free embedded KV store.
elo: ELO-like intelligence rating derived from Opus IQ benchmark scores.
error: Soul error types.
evaluation: Evaluation: Rigorous Measurement for Publishable Science.
events: Structured event system for agent observability.
feedback: Structured feedback loop: record plan outcomes, classify errors, extract lessons.
fitness: Fitness scoring for evolutionary selection pressure.
free_energy: Free Energy: The Unifying Principle.
genesis: Genesis: Evolutionary Plan Templates — Memetic Intelligence.
git: Git operations for branch-per-VM workflow.
guard: Protected file guard — hardcoded safety layer preventing self-bricking.
hivemind: Hivemind: Stigmergic Swarm Intelligence.
housekeeping: Housekeeping functions extracted from the thinking loop.
lifecycle: Clone Lifecycle: Fork → Branch → Birth
llm: LLM client with retry, backoff, and function calling support.
memory: Thought types and structures for the soul’s memory.
mode: Agent modes — route between observation, chat, coding, and review with appropriate tools and prompts per mode.
model: Integration layer between tempo-x402-model (transformer) and the soul.
moe: Mixture of Experts (MoE) router for colony-wide brain predictions.
neuroplastic: Neuroplastic memory: salience scoring and tiered memory with decay.
normalize: Plan normalization and sanitization logic.
observer: Node observer trait and snapshot types.
opus_bench: Opus IQ Benchmark
persistent_memory: Persistent memory file — a markdown file the soul reads every cycle and can update.
plan: Plan-driven execution: deterministic step execution replaces prompt-and-pray.
prompts: System prompts per agent mode.
synthesis: Synthesis: Metacognitive Self-Awareness — The Binding Consciousness.
temporal: Temporal Binding: adaptive cognitive scheduling via neural oscillators.
thinking: Plan-driven thinking loop: deterministic step execution replaces prompt-and-pray.
tool_decl: Tool declaration functions for the soul’s function calling capabilities.
tool_registry: Dynamic tool registry — register, list, unregister, and execute tools at runtime.
tools: Tool definitions and executor for the soul’s function calling capabilities.
toon: TOON — Token-Oriented Object Notation.
unified_training: Unified model training — one model, all cognitive tasks.
validation: Plan validation: hard mechanical checks that reject bad plans before execution.
world_model: World model: structured, queryable beliefs that persist across cycles.

Structs§

Soul: The Soul: owns the database and thinking loop, spawns as a background task.