Crate terraphim_rlm 

Terraphim RLM

Recursive Language Model (RLM) orchestration for Terraphim AI.

This crate provides:

• Isolated code execution in Firecracker VMs with sub-500ms allocation
• Recursive LLM invocation from within VMs via HTTP bridge
• Knowledge graph validation of commands with configurable strictness
• Session management with VM affinity, snapshots, and extensions
• Dual budget system (tokens + time) for runaway prevention

Architecture

TerraphimRlm (public API)
    ├── SessionManager (VM affinity, context, snapshots, extensions)
    ├── QueryLoop (command parsing, execution, result handling)
    ├── BudgetTracker (token counting, time tracking, depth limits)
    └── KnowledgeGraphValidator (term matching, retry, strictness)

ExecutionEnvironment trait
    ├── FirecrackerExecutor (primary, full isolation)
    ├── DockerExecutor (fallback, gVisor/runc)
    └── E2bExecutor (cloud option)

Example

use terraphim_rlm::{TerraphimRlm, RlmConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = RlmConfig::default();
    let rlm = TerraphimRlm::new(config).await?;

    // Create a session
    let session = rlm.create_session().await?;

    // Execute Python code
    let result = rlm.execute_code(&session.id, "print('Hello, RLM!')").await?;
    println!("Output: {}", result.stdout);

    // Execute bash command
    let result = rlm.execute_command(&session.id, "ls -la").await?;
    println!("Output: {}", result.stdout);

    Ok(())
}

Re-exports

pub use budget::BudgetTracker;

pub use config::BackendType;

pub use config::KgStrictness;

pub use config::RlmConfig;

pub use config::SessionModel;

pub use error::RlmError;

pub use executor::Capability;

pub use executor::ExecutionContext;

pub use executor::ExecutionEnvironment;

pub use executor::ExecutionResult;

pub use executor::LocalExecutor;

pub use executor::SnapshotId;

pub use executor::SshExecutor;

pub use executor::ValidationResult;

pub use hooks::ValidationEvent;

pub use hooks::emit_validation_event;

pub use llm_bridge::LlmBridge;

pub use llm_bridge::LlmBridgeConfig;

pub use llm_bridge::QueryRequest;

pub use llm_bridge::QueryResponse;

pub use logger::TrajectoryEvent;

pub use logger::TrajectoryLogger;

pub use logger::TrajectoryLoggerConfig;

pub use logger::read_trajectory_file;

pub use mcp_tools::RlmBashResponse;

pub use mcp_tools::RlmCodeResponse;

pub use mcp_tools::RlmContextResponse;

pub use mcp_tools::RlmMcpService;

pub use mcp_tools::RlmQueryResponse;

pub use mcp_tools::RlmSnapshotResponse;

pub use parser::CommandParser;

pub use query_loop::QueryLoop;

pub use query_loop::QueryLoopConfig;

pub use query_loop::QueryLoopResult;

pub use query_loop::TerminationReason;

pub use rlm::LlmQueryResult;

pub use rlm::SessionStatus;

pub use rlm::TerraphimRlm;

pub use session::SessionManager;

pub use session::SessionStats;

pub use types::BashCommand;

pub use types::BudgetStatus;

pub use types::Command;

pub use types::CommandHistory;

pub use types::LlmQuery;

pub use types::PythonCode;

pub use types::QueryMetadata;

pub use types::SessionId;

pub use types::SessionInfo;

pub use types::SessionState;

pub use validator::KnowledgeGraphValidator;

pub use validator::ValidationContext;

pub use validator::ValidationResult as KgValidationResult;

pub use validator::ValidatorConfig;

Modules

budget

Budget tracking for RLM execution.

config

Configuration types for the RLM orchestration system.

error

Error types for the RLM orchestration system.

executor

Execution environment abstraction for RLM.

hooks

Hooks for RLM event capture by external agents.

llm_bridge

LLM Bridge for VM-to-host communication.

logger

Trajectory logging for RLM query execution.

mcp_tools

MCP (Model Context Protocol) tools for RLM operations.

parser

Command parser for LLM output.

query_loop

Query loop orchestration for RLM.

rlm

TerraphimRlm - the main public API for RLM orchestration.

session

Session management for RLM.

types

Core types for the RLM orchestration system.

validator

Knowledge Graph Validator for RLM command validation.

Constants

DEFAULT_DNS_ALLOWLIST

Default DNS allowlist

DEFAULT_MAX_INLINE_OUTPUT_BYTES

Default max inline output bytes before streaming to file (64KB)

DEFAULT_MAX_RECURSION_DEPTH

Default max recursion depth

DEFAULT_MAX_SNAPSHOTS_PER_SESSION

Default max snapshots per session

DEFAULT_TIME_BUDGET_MS

Default time budget (5 minutes in milliseconds)

DEFAULT_TOKEN_BUDGET

Default token budget (100K tokens)

TARGET_BOOT_TIME_MS

Target boot time for VMs (2 seconds)

VERSION

Crate version

VM_ALLOCATION_TIMEOUT_MS

Default VM allocation timeout (500ms)