zorp

A research agent for scientific discovery.

Answers are cheap. Evidence is not.

Investigation is scattered, and the AI version of it is neither grounded nor validated. zorp turns a question into a pre-registered investigation, an evidence record, and a report where every claim traces back to it.

zorp.dev · Aviskaar · Report an issue

---

zorp turns an uncertain question into a defensible answer, using evidence: question, investigation, sources, evidence, conflicting evidence, reasoning, validation, answer or artifact. That covers a lot more than academic research: a technical decision (should we migrate off Kafka), a competitive teardown, an investment thesis, a due-diligence package, a market question, an engineering tradeoff, or an academic hypothesis are all the same shape of problem to zorp. It's built by Aviskaar, an applied AI research lab.

Status: early / pre-alpha. The base execution harness and the shared research foundation (tracks, evidence records, checkpoints) are in place and fully tested. All four capabilities built on top, validate, investigate, co-write, and deliver, are built and tested. See Status & roadmap below.

Why zorp

A confident answer is not a defensible one. An LLM will produce a fluent answer to a hard question in seconds. What it will not do is tell you whether to believe it, what evidence it weighed, or what it found that pointed the other way. zorp treats that gap as the actual problem. A question becomes an investigation, the investigation produces an evidence record, and the record is what the answer is accountable to.

The core primitive is the Kill Threshold: a number a human supplies that says, in advance, what would prove the investigation wrong. Before zorp gathers anything, the hypothesis, the metric, and the threshold are written to a file, hashed, and committed to git, so a run cannot quietly rewrite what it set out to test. The agent never proposes the threshold, and only a human can move it. Every attempt is recorded, not just the one that worked, and when a run crosses the line the record says why it was killed.

Most "AI scientist" projects wire a large agent framework directly to experiment code, which makes the harness and the research logic hard to separate, test, or reason about independently, and most assume the deliverable is a finished document an AI wrote end to end. zorp starts from the opposite end on both counts: a minimal, dependency-light execution core extended deliberately with the primitives evidence-based investigation needs, and a human always in the loop as the author of record for whatever gets produced, a decision memo, a competitive landscape, a due-diligence package, or a paper. Long-running task loops, verification gates, session persistence, tool/MCP integration, and the research foundation (multi-track evidence records with git-backed, tamper-evident pre-registration) are already built and tested. All four capabilities on top, each a clearly bounded layer, validate, investigate, co-write, and deliver, are built and tested; co-write drafts the artifact from the track's recorded evidence, with a human as author of record, and deliver matches the finished draft against real venues.

Architecture

.
├── src/                 # zorp core crate: model transport, raw primitives (binary: zorp)
├── zorp-agent/          # the agent: tools, reasoning, verification, sessions, MCP, telemetry
├── zorp-mcp/            # MCP client/server integration
├── zorp-track/          # research foundation: tracks, evidence records, pre-registration, checkpoints
├── zorp-eval/           # deterministic evaluation harness
├── erbga/               # standalone genetic algorithm for graph community detection (no zorp deps)
├── evals/               # eval suites (smoke tests, Terminal-Bench, Harbor adapter)
├── examples/            # usage examples (e.g. OpenTelemetry tracing)
├── docs/
│   ├── paper/           # arXiv writeup (WIP)
│   ├── superpowers/     # zorp's own design specs and plans
│   └── upstream-quecto/ # preserved history of the upstream harness (see Origins)
└── reference/            # gitignored, local-only research material, not distributed

Getting started

Requires a recent stable Rust toolchain (rustup.rs).

git clone https://github.com/aviskaar/zorp.git
cd zorp
cargo build --workspace --exclude zorp-track

zorp-track (the research foundation) bundles DuckDB, which compiles from source and takes a while on a cold cache. The command above skips it, which is enough for the core zorp and zorp-agent binaries below. Drop --exclude zorp-track (plain cargo build --workspace, or cargo build --workspace --features research for zorp-agent) once you need the validate/investigate/co-write/deliver capabilities, and budget time for that first build. The LanceDB vector library is behind a non-default library feature, so the Arrow and DataFusion tree is not built unless you ask for it.

Run the core transport directly:

export ZORP_BASE_URL="https://api.openai.com/v1"   # or a local endpoint (Ollama, LM Studio, vLLM)
export ZORP_API_KEY="sk-..."
export ZORP_MODEL="gpt-4o-mini"
cargo run -- "Summarize the second law of thermodynamics in one sentence."

Or the full agent:

cargo run -p zorp-agent -- "<task>"

Install without a toolchain

curl -fsSL https://raw.githubusercontent.com/aviskaar/zorp/main/install.sh | bash

This downloads prebuilt zorp and zorp-agent binaries for your platform from the latest release, verifies the published checksum, and installs them to ~/.local/bin. No Rust needed. Linux and macOS, x86_64 and arm64.

If no prebuilt binary fits your platform, the same script falls back to building from source, which does need a toolchain. ZORP_INSTALL_FROM_SOURCE=1 forces that path, and ZORP_INSTALL_DIR changes where the binaries land.

Prebuilt binaries carry the default feature set. The four research capabilities are behind the research feature and still need a source build, because zorp-track bundles DuckDB.

Or try it without installing anything:

docker run --rm -v "$PWD":/work \
  -e ZORP_BASE_URL -e ZORP_MODEL -e ZORP_API_KEY \
  ghcr.io/aviskaar/zorp "<your task>"

The image is about 150MB, runs as a non-root user, and mounts your project at /work. linux/amd64 and linux/arm64.

Using validate, investigate, co-write, deliver

Two of the four need an MCP tool connected first (behind zorp-agent's research feature): validate needs a search-capable tool, one whose name carries a search verb (search, fetch, query, browse, find, lookup, retrieve), to search for evidence before scoring a question; deliver specifically needs a huiban-prefixed tool, to match a draft against real venues (see docs/ARCHITECTURE.md). Connect one with --mcp, or configure it once in .zorp/mcp.toml:

# a search server satisfies validate; its tools are named mcp__brave-search__*
cargo run -p zorp-agent --features research -- --yes \
  --mcp "stdio:brave-search:npx:-y:@modelcontextprotocol/server-brave-search" \
  validate "Should we migrate off Kafka to Redpanda?"

# .zorp/mcp.toml
[[server]]
name = "brave-search"
transport = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-brave-search"]
trust = "sandbox"

Tools show up prefixed mcp__<server>__<tool>, and both checks read that name: a server named huiban satisfies deliver, and any tool whose name carries one of the verbs above satisfies validate. Without a matching tool connected, validate fails fast with "no search-capable tool is available" and deliver with "no huiban-prefixed tool is available", rather than running with no evidence.

Development

cargo build --workspace --exclude zorp-track   # fast path, see note above
cargo test --workspace --exclude zorp-track    # matches CI; see CONTRIBUTING.md for full coverage
cargo run -p zorp-eval -- --help               # evaluation harness

Working in this repo? Read CLAUDE.md and AGENTS.md first. They cover the inherited vs. zorp-specific code boundary, where design specs live, and repo conventions.

Status & roadmap

• Base execution harness (forked from quecto, renamed, fully tested)
• Research foundation (zorp-track: multi-track evidence records, git-backed pre-registration, checkpoints, DuckDB + LanceDB)
• validate: is this question worth investigating (novelty and feasibility check)
• investigate: gather evidence through staged, pre-registered attempts, every attempt recorded
• co-write: zorp drafts the artifact, a human is always the author of record
• deliver: match a finished draft against real academic venues (conferences and journals, via live huiban search), writing a ranked shortlist for a human to review
• A published investigation trace, start to finish
• A grounded-vs-baseline evaluation
• A systems paper about zorp itself, submitted to arXiv

Origins

zorp's execution layer started as a fork of quecto, a minimal, vendor-neutral harness for LLM agents (MIT licensed). See NOTICE.md for full attribution. We modify and extend it directly rather than depending on it as an external crate, since zorp's needs (long-running research loops, experiment tracking, paper synthesis) diverge substantially from a general agent harness. Crates and binaries have been renamed from quecto-* to zorp-*. docs/UPSTREAM_QUECTO_README.md and docs/upstream-quecto/ preserve the original project's documentation and design history for reference.

Contributing

Contributions are welcome. zorp is early and still moving fast, so it's worth opening an issue to discuss larger changes before sending a PR. See CONTRIBUTING.md for setup, testing, and PR guidelines, and CODE_OF_CONDUCT.md for community expectations.

License

MIT. See LICENSE and NOTICE.md for third-party attribution.