Getting Started

This guide outlines the protocol for setting up the environment, compiling the binaries, executing an interactive chat session, and running an autonomous agent task.

System Requirements

Before installation, verify that the host environment conforms to the following operational parameters:

Component

Specification Requirement

Operating System

Linux, macOS, or Windows. Native Windows coding requires the explicit reduced-isolation option; use Windows Subsystem for Linux when OS sandbox isolation is required.

Rust Compiler

Version 1.97.1 or later (required for building from source)

Terminal Emulator

Modern console supporting UTF-8 encoding and 256-color escape sequences

Network Link

Required for cloud LLM API communication (unnecessary for local Ollama deployments)

Provider Access Configuration

Perspt requires access to an external model oracle. You must define and export the appropriate API key as an environment variable. The system inspects the environment and maps the configuration according to a deterministic detection priority:

Vertex AI > Gemini > OpenAI > Anthropic > Groq > Cohere > XAI > DeepSeek > Ollama

Set the key for your selected provider:

# Example configurations
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GEMINI_API_KEY="..."

For offline execution using local models, start the Ollama service:

ollama serve
ollama pull llama3.2

Quick Installation

To compile the release binary directly from the source repository:

git clone https://github.com/eonseed/perspt.git
cd perspt
cargo build --release
./target/release/perspt --version

To install the package into your Cargo binary path:

cargo install perspt
perspt --version

To download and deploy the precompiled release archive:

curl -L https://github.com/eonseed/perspt/releases/latest/download/perspt-linux-x86_64.tar.gz | tar xz
chmod +x perspt && sudo mv perspt /usr/local/bin/

Interactive Dialogue Session

The terminal user interface (TUI) is the default interactive environment. To launch the TUI:

perspt

Upon initiation, the system establishes a session using the detected API key.

  • Input Entry: Enter your dialogue prompt and press Enter to stream the response.

  • Scrollback: Navigate the conversation scrollback window using Up/Down or Page Up/Page Down.

  • Exit: Press Esc to terminate the TUI session.

For non-interactive pipelines or shell-script piping, use the simple chat command:

perspt simple-chat
# Optionally record the session output
perspt simple-chat --log-file session.txt

Type exit or enter Ctrl+D to terminate the simple chat process.

Autonomous Agent Execution

Agent mode compiles a task charter into a state graph of modules and executes them under a closed-loop stabilizer.

To execute an autonomous coding task:

perspt agent -w ./demo-calculator \
  "Create a Python calculator package with add, subtract, multiply, divide. Include type hints and pytest tests."

Operational Execution Steps

During execution, the SRBN engine performs the following operations:

  1. System Detection: The program identifies Python as the target workspace language, and registers the corresponding LSP verifier and pytest environments.

  2. Graph Planning: Planning is a governed architect turn that revises the work graph through the update_graph tool. Each node lists its declared file footprint, and the dispatcher schedules ready nodes by footprint conflict (no two concurrent nodes may touch the same files).

  3. Stabilization Loop: For each dispatched node, the Actuator issues typed tool calls against a reversible candidate overlay; the deterministic kernel admits each call before it is applied. The system then computes the Lyapunov energy on the realized candidate:

    • Syntactic energy (\(V_{\text{syn}}\)): Diagnostics from the LSP.

    • Logical energy (\(V_{\text{log}}\)): Test failures from the test runner.

    • Build energy (\(V_{\text{boot}}\)): Exit codes of environment setups.

    If \(V(x) > \varepsilon\), the engine compiles the error diagnostics into a correction prompt and retries. This loops until the node converges (\(V(x) \leq \varepsilon\)) or the retry cap is reached.

  4. Interactive Review: In interactive mode, the TUI displays the proposed file changes (unified diffs) and verifier states for approval before commit.

  5. Merkle Commit: Stable nodes are written to the Merkle ledger and committed to the active workspace.

Verifying Output Structures

Upon task completion, inspect the workspace directory to verify the generated files:

ls demo-calculator/
# Expected structure:
# pyproject.toml  src/  tests/  uv.lock

To run the verification suite locally:

cd demo-calculator && uv run pytest -v

Headless Mode

For non-interactive environments, such as automated build pipelines, use the --yes flag to bypass the interactive review gate:

perspt agent --yes -w ./rust-csv-converter "Build a Rust CLI tool that converts CSV to JSON"

Exploration-Only Mode

To survey a repository under a strictly read-only capability, run only the exploration phase. Every call passes the kernel, mutation attempts are recorded denials, and nothing is mutated or promoted:

perspt agent --exploration-only -w ./rust-csv-converter "Summarize how CSV parsing is structured"

Perspt also accepts --allow-experimental-prompts to substitute validated [prompts] bundle sections live; such overrides remain experimental until a change record passes paired evaluation.

Parameterizing Models per Role

The agent runtime routes model calls by role. You can allocate different models to these roles depending on the complexity of the work:

  • Actuator (--model / --actuator-model): Proposes the governed coding tool calls.

  • Explorer (--explorer-model): Optional cheaper read-only repository exploration.

  • Adjudicator (--adjudicator-model): Optional no-tool conjunctive diff veto.

To run the agent with customized model selections:

perspt agent \
  --actuator-model gemini-2.5-flash \
  --explorer-model gemini-2.5-flash \
  --adjudicator-model gemini-2.5-pro \
  -w ./project "Task description"

The [models] table in config.toml additionally routes architect, actuator, verifier, speculator, and adjudicator turns as fully qualified provider::model values; when present it takes precedence over the flat *_model configuration fields.

The actuator route also supports ordered fallback models in case the primary oracle returns a rate limit or API error. The flag is repeatable, and failover is sticky:

perspt agent \
  --actuator-model gemini-2.5-pro \
  --fallback-model gemini-2.5-flash \
  --fallback-model gemini-2.5-flash-lite \
  -w ./project "Task description"

Next Steps

Tutorials

Step-by-step learning guides.

Tutorials
Configuration

Providers, models, and preferences.

Configuration Guide
Agent Deep Dive

Master autonomous coding.

Agent Mode Tutorial
Architecture

Understand the fourteen-crate design.

Architecture