Source-Grounded Reviews

Why retrieval matters

Source-grounded codebase review does not work by pasting an entire repository into a prompt. The runtime needs a retrieval layer that can index files, rank evidence, surface omissions, and return bounded excerpts with traceable citations.

Librarian is that retrieval engine for Syntropy. It is a local-first Java CLI with an embedded Lucene index. Syntropy handles agent selection, routing, synthesis, replay, and trust evidence; Librarian handles read-only retrieval and evidence shaping.

Two review paths

Public GitHub repositories

The platform can fetch a public GitHub tree, filter obvious junk, select bounded files, and build a source-grounded prompt. This path is useful when you do not have a local clone and do not need deep dependency or symbol context.

Local or private repositories

When you point the platform composer at a readable local path, Syntropy calls Librarian through a subprocess adapter. Librarian indexes the repository (or refreshes incrementally), ranks high-signal files, and returns a deterministic librarian.retrieve.v1 evidence packet.

During a run, the Elixir runtime can also call librarian evidence to expand follow-up context under librarian.evidence.v1.

Install Librarian

1. Download a release from github.com/syntropy-os/librarian/releases.
2. Put the librarian binary on your PATH, or set SYNTROPY_LIBRARIAN_BIN to its absolute path.
3. Optional: set LIBRARIAN_HOME when you want isolated index state per workspace.

Librarian is Fair Source (BUSL 1.1) under the same production grant as Syntropy.

CLI contracts

librarian retrieve → librarian.retrieve.v1

Used by the platform for local-path reviews:

librarian retrieve \
  --repo ~/projects/my-app \
  --goal "Find the highest-leverage next engineering move." \
  --focus architecture,security,operations \
  --budget 60000 \
  --json

The JSON packet includes source metadata, file inventory, selected files, bounded evidence snippets with line ranges, omissions, retrieval trace, and agent briefs. Syntropy validates the schema before grounding multi-agent recommendations.

librarian evidence → librarian.evidence.v1

Used by the Syntropy runtime for agent-driven follow-up expansion during a run:

librarian evidence \
  --repo ~/projects/my-app \
  --request-file /tmp/evidence-request.json \
  --budget 18000 \
  --json

The request file describes the bounded follow-up action (search, open file, related files, dependency context). The response is validated before it enters the run pipeline.

Platform posture

In the platform workspace settings, Source review tooling shows whether GITHUB_TOKEN, the Librarian binary, and the gateway source tool are configured. Local filesystem review is enabled in development; production requires SYNTROPY_ENABLE_LOCAL_REPO_REVIEW=true when you intentionally expose that path.

What Librarian does not do

Librarian is read-only retrieval. It does not mutate repositories, run tests, install dependencies, call models, or host a remote service. Those boundaries keep private code local by default and let Syntropy own execution semantics.