Perspt

v0.6.2 "Hózhó" - Hózhó (Navajo) — A state of perfect balance, harmony, and continuous self-improvement. Your Terminal's Window to the AI World

"The keyboard hums, the screen aglow,\ AI's wisdom, a steady flow.\ Will robots take over, it's quite the fright,\ Or just provide insights, day and night?\ We ponder and chat, with code as our guide,\ Is AI our helper or our human pride?"

Perspt (pronounced "perspect," short for Personal Spectrum Pertaining Thoughts) is a terminal-based interface to Large Language Models, built in Rust. It does two things:

1. Chat with any LLM from your terminal. Set an API key, run perspt, and start talking. Supports OpenAI, Anthropic, Google Gemini, Groq, Cohere, xAI, DeepSeek, AWS Bedrock, Google Agent Platform (Vertex AI), and Ollama out of the box.

2. Run an experimental autonomous coding agent. The SRBN (Stabilized Recursive Barrier Network) engine decomposes coding tasks into a DAG of nodes, generates code, verifies each node with real LSP diagnostics and tests, and commits only when Lyapunov energy converges. SRBN is based on the three-paper Stability is All You Need series. Agent mode is under active development; the theoretical framework is mature, but the implementation has not yet been benchmarked.

Quickstart

# Clone the repository
git clone https://github.com/eonseed/perspt.git
cd perspt

# Build the release binary
cargo build --release

# Set an API key and launch the TUI chat
export GEMINI_API_KEY="your-api-key"
./target/release/perspt

# Or use simple CLI mode for scripting
./target/release/perspt simple-chat

Perspt auto-detects whichever provider key you have set. No config file required.

What You Get

Interactive TUI -- A Ratatui-powered chat interface with markdown rendering, streaming responses, smooth scrolling, and conversation export (/save).

Simple CLI Mode -- A minimal prompt for direct Q&A, piping, and session logging. Ideal for scripting and accessibility.

Agent Mode (SRBN) [Experimental] -- An autonomous coding assistant that plans multi-file projects as directed acyclic graphs, verifies correctness through LSP diagnostics and test runners, and self-corrects until energy converges below a configurable threshold. Based on the SRBN paper series; under active development.

Web Dashboard -- A browser-based monitoring interface for observing agent execution in real time. Shows DAG topology, energy convergence, LLM telemetry with token usage and latency, sandbox branches, and decision traces. Built with Axum, Askama, HTMX, and DaisyUI 5. Can be launched standalone (perspt dashboard) or embedded in the agent process (perspt agent --dashboard) for live monitoring during execution. The embedded mode opens a read-only DuckDB connection alongside the agent's writer, so it never interferes with the running session.

Zero-Config Startup -- Automatic provider detection from environment variables. Set a key and go.

Local Models via Ollama -- Full privacy, no API fees, works offline.

Why SRBN is Different

Most coding agents work by trial and error: generate code, check if it compiles, and retry if it fails. This is fine for small tasks, but it breaks down as projects grow. Each step has a chance of going wrong, and those chances multiply. A ten-file project might need dozens of retries; a fifty-file project might never finish.

Two problems make this worse:

• Errors compound. Each generation step builds on the previous one. A small mistake early on gets baked into everything that follows. By the time the agent notices, the fix requires re-doing most of the work.

• Retries don't help when the agent is lost. If the agent conditions on its own broken output, it tends to repeat the same class of mistake. Blind re-prompting circles around the problem instead of converging on a solution.

SRBN takes a different approach. Instead of hoping each step is correct, it measures how wrong the current state is and steers corrections based on that measurement. Think of it like a thermostat, not a dice roll:

1. Break the task into pieces. The Architect decomposes your request into a graph of subtasks, each owning specific files.

2. Generate code for each piece. The Actuator writes code for one node at a time.

3. Measure the damage. Real tools -- your actual LSP server, your actual test runner, your actual compiler -- score the output. Zero means perfect. Higher means more broken.

4. Fix what's broken, specifically. The error details (which diagnostic, which test, which file) go back to the model as targeted context. This is not "try again"; it is "here is exactly what is wrong."

5. Only commit when stable. The score must drop below a threshold before the node is accepted. Then adjacent nodes are checked for consistency -- do imports resolve, do types match across files?

The theoretical result: instead of reliability decaying exponentially with project size, the paper predicts that retry cost grows logarithmically. A hundred-node project should cost only modestly more than a ten-node one.

This approach is based on the three-paper Stability is All You Need series. Paper I gives the Lyapunov-guided SRBN stability certificate; Paper II turns it into an observed harness with descent-gated acceptance; Paper III lifts it into a capability-constrained platform contract. Perspt's agent mode is an experimental implementation of this theory -- the mathematical framework is mature, but repository-level benchmarks have not yet been published. The next section covers the theory for those interested.

PSP-7 hardening. The correction loop uses a fail-closed typed parse pipeline (five layers from raw capture to semantic validation) so malformed LLM output is classified rather than silently dropped. A prompt compiler with provenance tracking replaces ad-hoc template constants. Every correction attempt is recorded with its parse state, retry classification, and energy snapshot for full observability via perspt status and the web dashboard.

Theoretical Foundation

The SRBN engine is grounded in the theoretical framework from the Stability is All You Need paper series. This section presents the mathematical machinery for researchers and developers who want to understand the theoretical guarantees.

Note: The theorems below are results from the SRBN papers. They describe properties of the formal system under stated assumptions. Perspt implements this framework as an experimental agent, but these theoretical results have not yet been empirically validated through published benchmarks on this implementation.

The Problem, Formally

Over $N$ generation steps with per-step error rate $\delta$, the probability of a fully correct output decays as $(1 - \delta)^N$ -- exponential degradation. When the agent conditions on its own erroneous output, errors correlate rather than cancel (correlated entropy collapse), making naive retry ineffective.

Core Idea: Sheaf-Theoretic Control

SRBN reformulates LLM agency as a sheaf over a task DAG. Each node in the DAG owns a set of output files. A sheaf assigns local data (code, tests, configs) to each node, subject to a consistency condition: overlapping data between adjacent nodes must agree.

The system defines a Lyapunov energy function that measures how far the current state is from this consistent, correct target:

$$ V(x) = \sum_{V \supseteq U} | \rho_{VU}(x_U) - x_V |^2 $$

where $\rho_{VU}$ is the restriction map from node $U$ to node $V$. When $V(x) = 0$, every node agrees with its neighbors and all verification checks pass.

Perspt implements this as a weighted sum of five measurable verification barriers:

$$ V(x) = \alpha \cdot V_{\text{syn}} + \beta \cdot V_{\text{str}} + \gamma \cdot V_{\text{log}} + V_{\text{boot}} + V_{\text{sheaf}} $$

Default weights: $\alpha = 1.0$, $\beta = 0.5$, $\gamma = 2.0$.

Key Theorems (from the Paper)

The paper proves three results that underpin SRBN's theoretical reliability model:

Theorem 1 (Global Exponential Decay). If the control law $u(x) = -K \nabla V(x)$ is applied at each retry step, then:

$$ V(x_t) \leq V(x_0) \cdot e^{-2\mu K t} $$

where $\mu$ is the Polyak-Lojasiewicz constant of the energy landscape. Energy decays exponentially toward zero -- the system converges.

Theorem 2 (Input-to-State Stability). Under persistent bounded noise $| w_t | \leq \bar{w}$ (imperfect LLM outputs), the energy remains bounded:

$$ V(x_t) \leq V(x_0) \cdot e^{-\lambda t} + \frac{\bar{w}^2}{\lambda} $$

The system does not need perfect LLM responses to converge. Bounded errors yield bounded deviation -- the hallmark of robust control.

Corollary (Role of Topology). Convergence rate depends on the Fiedler value $\lambda_2$ of the task DAG's Laplacian. Well-connected graphs (higher $\lambda_2$) converge faster; long chains converge slowly. This guides how the Architect should decompose tasks.

How This Changes Reliability Scaling (Theoretical)

Traditional agents: reliability $\sim (1 - \delta)^N$ (exponential decay).

SRBN with Lyapunov control (paper prediction): retry cost $\sim O(\log N)$ for an $N$-node project.

The barrier mechanism is designed to transform the problem from "hope each step is correct" to "measure deviation, correct, and steer toward convergence." Whether Perspt's implementation fully realizes this theoretical scaling is an open empirical question.

SRBN Control Loop

The following diagram illustrates how a coding task flows through the SRBN engine:

flowchart TD
    A["Task Description"] --> B["Architect: Decompose into DAG"]
    B --> C["Actuator: Generate Code per Node"]
    C --> D{"Compute V(x)"}
    D -->|"V(x) > epsilon"| E["Flow Matching: Correct with Error Feedback"]
    E --> C
    D -->|"V(x) <= epsilon"| F["Sheaf Validation: Cross-Node Consistency"]
    F -->|"V_sheaf > 0"| G["Repair Inconsistencies"]
    G --> D
    F -->|"V_sheaf = 0"| H["Commit to Merkle Ledger"]

    subgraph Verification Barriers
        D1["V_syn: LSP Diagnostics"]
        D2["V_str: Structural Contracts"]
        D3["V_log: Test Runner"]
        D4["V_boot: Build Check"]
    end

    C --> D1 & D2 & D3 & D4
    D1 & D2 & D3 & D4 --> D

Each retry is not blind re-prompting. The flow matching barrier is designed to project the LLM's output back toward the feasible manifold using the gradient of $V(x)$, providing targeted error context that directs the next generation.

For the complete theoretical treatment, proofs, and design rationale, see the Perspt Book.

Commands

Perspt uses subcommands. Running perspt with no arguments defaults to chat.

Global options: -v (verbose), -c <FILE> (config path), -h (help), -V (version).

Agent Mode

Agent mode uses the experimental SRBN engine to autonomously write, test, and commit code.

Quick Start

# Create a Python project from scratch
perspt agent "Create a Python calculator with add, subtract, multiply, divide"

# Work in an existing project
perspt agent -w /path/to/project "Add unit tests for the existing API"

# Fully autonomous (no prompts)
perspt agent -y "Refactor the parser for better error handling"

How SRBN Works

See [Theoretical Fo