Architecture

Perspt is built as a modern, modular Rust application using a 7-crate workspace architecture. This design enables clean separation of concerns, independent testing, and easy extensibility.

Workspace Overview

Perspt Workspace Structure

Crate Dependency Graph

Crate Dependencies

SRBN Control Flow

Stabilized Recursive Barrier Network

Crate Details

perspt-cli

The command-line interface providing 10 subcommands:

CLI Subcommands

Command	Purpose	Key Options
chat	Interactive TUI	--model <MODEL>
agent	SRBN autonomous coding	--architect-model, --actuator-model --energy-weights, --mode
init	Project setup	--memory, --rules
config	Configuration	--show, --set, --edit
ledger	Merkle ledger	--recent, --rollback, --stats
status	Agent status	(none)
abort	Cancel session	--force
resume	Resume session	[SESSION_ID]
logs	View LLM logs	--tui, --last, --stats
simple-chat	CLI chat mode	--model, --log-file

Source: crates/perspt-cli/src/

perspt-core

Thread-safe LLM provider and configuration:

GenAIProvider - Thread-safe LLM abstraction

/// Thread-safe LLM provider using Arc<RwLock>.
/// Can be safely cloned and shared across async tasks.
#[derive(Clone)]
pub struct GenAIProvider {
    client: Arc<Client>,
    shared: Arc<RwLock<SharedState>>,
}

impl GenAIProvider {
    pub fn new() -> Result<Self>
    pub fn new_with_config(provider: Option<&str>, api_key: Option<&str>) -> Result<Self>
    pub async fn generate_response_stream_to_channel(...) -> Result<()>
    pub async fn get_total_tokens_used(&self) -> usize
}

Modules:

config.rs:

Simple Config struct (provider, model, api_key)

llm_provider.rs:

GenAIProvider with streaming support

memory.rs:

Conversation memory management

Source: crates/perspt-core/src/

perspt-agent

The Stabilized Recursive Barrier Network implementation.

Energy Computation

\[V(x) = \alpha \cdot V_{syn} + \beta \cdot V_{str} + \gamma \cdot V_{log}\]

Default weights: α=1.0, β=0.5, γ=2.0

Key Modules:

Module	Size	Description
orchestrator.rs	34KB	SRBN control loop, model tiers, retry policy
lsp.rs	28KB	LSP client for Python (ty server)
tools.rs	12KB	Agent tools (search, read, write, shell)
types.rs	24KB	TaskPlan, Node, Energy, ToolCall types
ledger.rs	6KB	Merkle ledger for change tracking
test_runner.rs	15KB	pytest integration, V_log calculation
context_retriever.rs	10KB	Code context extraction

Source: crates/perspt-agent/src/

perspt-tui

Ratatui-based terminal interface components:

agent_app.rs:

Main agent mode TUI application

dashboard.rs:

Status dashboard with metrics

diff_viewer.rs:

Side-by-side file diff display

review_modal.rs:

Change approval/rejection UI

task_tree.rs:

Hierarchical task visualization

Source: crates/perspt-tui/src/

perspt-policy

Starlark-based policy engine for command approval:

Security policy engine

pub struct PolicyEngine {
    // Evaluates Starlark rules for command safety
}

pub struct Sanitizer {
    // Cleans and validates shell commands
    // Prevents path traversal, injection attacks
}

Source: crates/perspt-policy/src/

perspt-sandbox

Safe command execution with process isolation.

Source: crates/perspt-sandbox/src/

perspt-store

DuckDB-based persistence layer for session management and LLM logging:

Session storage

pub struct SessionStore {
    conn: Connection,
}

impl SessionStore {
    pub fn new(db_path: &Path) -> Result<Self>
    pub fn create_session(task: &str, workspace: &str) -> Result<String>
    pub fn record_llm_request(...) -> Result<()>
    pub fn get_llm_requests(session_id: &str) -> Result<Vec<LlmRequestRecord>>
}

Key Types:

• SessionRecord — Session metadata (id, task, status, timestamps)

• LlmRequestRecord — LLM request/response with latency and tokens

• EnergyRecord — Energy history for stability tracking

• NodeStateRecord — SRBN node state snapshots

Source: crates/perspt-store/src/

Design Principles

🧩 Modularity

Each crate has a single responsibility:

• perspt-cli knows CLI, not LLM internals

• perspt-core provides LLM abstraction, not UI

• perspt-agent implements SRBN, delegates UI

🔒 Thread Safety

GenAIProvider uses Arc<RwLock<SharedState>> for:

• Safe cloning across async tasks

• Shared token counting and rate limiting

• Concurrent access from orchestrator and UI

⚠️ Error Handling

All crates use anyhow::Result for:

• Contextual error messages

• Error propagation with backtrace

• User-friendly error display

⚡ Async Architecture

Built on Tokio runtime with:

• Streaming LLM responses via channels

• Non-blocking UI updates

• Concurrent tool execution

Configuration Sources

Configuration Priority (highest first)

Priority	Source	Example
1	CLI Arguments	perspt agent --model gpt-5.2
2	Environment Variables	OPENAI_API_KEY=sk-...
3	Config File	~/.perspt/config.toml
4	Built-in Defaults	provider: openai, model: gpt-4

Supported Providers

Provider	Environment Variable	Models
OpenAI	OPENAI_API_KEY	GPT-5.2, o3-mini, o1-preview
Anthropic	ANTHROPIC_API_KEY	Claude Opus 4.5
Google	GEMINI_API_KEY	Gemini 3 Flash/Pro
Groq	GROQ_API_KEY	Llama 3.x
Ollama	(none)	Local models

Extension Points

Adding a New Command

1. Create crates/perspt-cli/src/commands/mycommand.rs

2. Add variant to Commands enum in main.rs

3. Add match arm in main()

Adding a New Tool

1. Add tool definition to crates/perspt-agent/src/tools.rs

2. Register in AgentTools::available_tools()

3. Implement execution in execute_tool()

Adding a Provider

The genai crate handles providers. To customize:

1. Set appropriate environment variable

2. Use provider-specific model names

See also

• API Reference - Per-crate API reference

• Contributing - How to contribute

• Testing - Testing guide