Skip to main content

Crate proserpina

Crate proserpina 

Source
Expand description

§Proserpina

Multi-agent critique and cross-examination pipeline for documents that require intellectual rigor — pre-prints, roadmaps, plans, and specs.

Proserpina runs a configurable ensemble of critic personas over a document via a provider-agnostic interaction-graph engine. LLM backends are pluggable behind an Agent trait; an EchoAgent backend makes the entire engine deterministic and testable with zero LLM dependencies.

§Architecture

  • A Subject is the document under critique.
  • A Topology describes how critic agents exchange messages: parallel (fan-out), rounds (adversarial cross-examination), or moderated (Socratic dialectic). All three are instances of a general InteractionGraph — topologies are templates, not special cases.
  • A Runner executes the graph against a backend agent, producing a Transcript and a synthesized Report of Findings.

Status: scaffold. Modules land incrementally via test-driven development (see docs/plans/2026-06-19-proserpina-design.md). This file ships the crate-level documentation and the feature surface; individual modules are added in subsequent PRs.

§Features

  • std (default): standard library support
  • cli: the proserpina binary and clap command line interface
  • serde: Serialize/Deserialize impls for core types
  • json: machine-readable JSON report output (implies serde)
  • backend-http: OpenAI-compatible HTTP agent, multi-provider roster, credentials config, summarizer (implies serde)
  • keyring: OS keychain credential tier (implies backend-http); macOS Keychain + Windows Credential Manager supported, Linux gnome-keyring has a known limitation

§Usage

Once built out, the CLI runs the configured critic personas over a document and renders a markdown critique report:

proserpina critique path/to/roadmap.md -o critique.md

Re-exports§

pub use backend::EchoAgent;
pub use persona::Persona;

Modules§

backend
Backends: concrete implementations of crate::agent::Agent.
persona
Critic personas — the lens an agent applies when critiquing.

Structs§

AgentId
A stable identifier for an agent within a single Proserpina run.
Finding
A single synthesized critique finding: one distinct issue raised (and possibly corroborated) across the critic panel.
Message
A single message routed along an edge of the interaction graph.
Report
A synthesized critique report: the findings folded from a transcript.
Runner
Executes an InteractionGraph against a registry of agents.
Subject
A Subject is whatever a Proserpina run is cross-examining.
Transcript
An ordered record of the Messages produced during a Proserpina run.

Enums§

InteractionGraph
A realized interaction graph: the executable form of a Topology.
MessageKind
The role a Message plays in a critique.
ProserpinaError
The single error type for all of Proserpina.
Severity
How serious a Finding is.
Topology
A topology template: a declarative description of how critics exchange messages, before it is lowered into an InteractionGraph.

Traits§

Agent
The provider boundary.