Compare a baseline to a side-by-side proposed variant (read-only).

For normal edit-in-place loops, use topos_assess_worktree_change or snapshot first with topos_begin_refactor then topos_assess_snapshot. This tool is for variants supplied as proposed_code or proposed_filepath. Read-only; returns an AssessmentResult with status and score/metric deltas.

Assess an in-place edit against a git revision — the common refactor loop.

Stateless: the baseline is read from git (git show <baseline_ref>:<path>, default HEAD) and compared to the current working-tree file. No prior call required — edit the file, then ask "did it beat HEAD?". COMPOSABLE is scored when a .gitnexus dep graph is available.

For untracked/new files or an uncommitted pre-edit baseline (which git cannot serve), use topos_begin_refactor + topos_assess_snapshot.

Assess a multi-file changeset against a git baseline and roll the per-file verdicts into a project before/after (read-only).

Use for a module split or any edit spanning several files; for a single file use topos_assess_worktree_change. Each file is compared to baseline_ref (new files have no baseline). Flags complexity_relocated_within_file when a function shrank but its file's cyclomatic complexity grew, and project_regression when the rollup drops a generator it previously satisfied. Reads from git and the working tree and writes nothing. When COMPOSABLE is blocked (missing_gitnexus_dir / stale_gitnexus_dir in the contract), call topos_generate_depgraph first, then re-assess. Returns a ChangesetResult.

Persist the file's current source as a baseline snapshot before you edit it (writes a snapshot record — its only side effect).

Returns a snapshot_id; edit the file in place, then call topos_assess_snapshot(snapshot_id, filepath) to score the change without re-sending the baseline. Use this when the baseline is not a committed git revision (untracked/new files, or uncommitted prior edits); otherwise topos_assess_worktree_change needs no snapshot at all.

Assess the current file against a baseline captured by topos_begin_refactor.

Loads the stored baseline by snapshot_id and compares it to the current on-disk file, with the same status semantics as topos_assess_improvement (and COMPOSABLE scored when a dep graph is available). A missing or expired snapshot is reported via blocked_by (snapshot_not_found / snapshot_stale).

Compute the AST (tree-edit) distance between two source-code strings.

Read-only and idempotent; parses both snippets in memory, never writes or scores. Use for clone detection or to measure refactor impact; the topos_assess_* tools already fold this in as an anti-gaming check, so call it directly only for the raw number. Returns a ComparisonResult: normalized_distance in [0, 1], similarity (= 1 - it), raw_distance, an operations edit-count map, and source_valid/target_valid (error set if either fails to parse).

Compute the AST (tree-edit) distance between two source files on disk.

Read-only; parses both files, never writes or scores. Use for clone detection or refactor impact; use topos_assess_* for a quality verdict. Returns a ComparisonResult: normalized_distance in [0, 1], similarity (= 1 - it), raw_distance, an operations edit-count map, and source_valid/target_valid (error set on read/parse failure).

Measure how well a test suite exercises its program-under-test, via structural (UAST) coverage (read-only).

A standalone signal, separate from the SIMPLE/COMPOSABLE/SECURE lattice; for a quality verdict use topos_evaluate_* instead. Computes UAST bipartite declaration matching and k-gram path recall. Returns a CoverageResult.

Report .gitnexus availability and freshness (read-only).

Distinguishes a missing graph from a stale one and from a load/schema failure, so an agent knows whether COMPOSABLE can be trusted and what to do next. Never shells out and never mutates state.

Generate the .gitnexus dependency graph via GitNexus (side-effecting).

Ensures the graph by default: no-ops when current, otherwise runs gitnexus analyze. force=True always regenerates.

Return a Topos documentation page as Markdown.

Use when your MCP client does not expose resource fetching to the agent (e.g. Gemini CLI). Clients that do surface resources should prefer the equivalent resource URI for efficiency: topos://docs/{topic}.

Topics:

• agent-contract — compact loop contract. Read first for refactors.

• lattice — the 8-element 3-cube H(G_qual); top = IDEAL, bottom = SLOP.

• metrics — every metric key, thresholds, interpretation.

• preferences — strict generator rankings and preference walks.

• priority — priority profiles (simple/composable/secure).

• workflows — expanded review→plan→refactor→re-measure guide.

Score a raw code string on the SIMPLE / COMPOSABLE / SECURE quality lattice (read-only; never writes or runs the code).

Use for a snippet not yet on disk. Only SIMPLE and SECURE are reachable here (scored from the source's CFG/CPG); COMPOSABLE needs a module dependency graph, so for it use topos_evaluate_file with gitnexus_dir, or topos_evaluate_project for a whole tree. Returns an EvaluationResult: the lattice verdict (SLOP…IDEAL), per-generator scores, and a next-step agent contract.

Score a file on disk on the SIMPLE / COMPOSABLE / SECURE lattice — the only evaluate tool that can reach COMPOSABLE (read-only).

Use for one file on disk. A ModuleDependencyGraph is attached when gitnexus_dir is given or auto-detected at <root>/.gitnexus, enabling COMPOSABLE (SIMPLE/SECURE always run); generate that graph first with topos_generate_depgraph (needs pnpm add -g gitnexus or npm install -g gitnexus). For an in-memory snippet use topos_evaluate_code; for a whole directory use topos_evaluate_project. coupling_available is false when no graph is found, leaving any COMPOSABLE verdict unreachable. Returns an EvaluationResult.

Recursively score every supported source file in a directory on the SIMPLE / COMPOSABLE / SECURE lattice, with a project rollup (read-only).

Use for a whole tree; for a single file use topos_evaluate_file, for a snippet topos_evaluate_code. Autodetects all supported languages (Python, Rust, JavaScript, TypeScript, C++) in one walk — no language argument — and skips unsupported files. Import/export-only entrypoint modules (__init__.py, index.ts, mod.rs) are exempted so trivial re-export hubs don't floor the verdict. The rollup takes the project-wide minimum per dimension (weakest file floors it); progress streams via ctx.report_progress. Returns a paginated per-file table (worst first) plus per-language rollups; page with limit / offset.

Full metric breakdown for a single code unit (inline string or file).

Read-only; provide exactly one of code or filepath. Use when you need the per-function detail behind a verdict; use topos_evaluate_* when the medal alone is enough. For filepath input, language is autodetected from the extension; language only applies to inline code. Returns an InspectionResult: the lattice evaluation, a top-N function complexity table (top_n_functions, default 10), total_functions, and entropy details. The top-N cap keeps large files from blowing out agent context.

Turn a generator ranking into a preference-ordered relaxation walk.

Pure and read-only (lattice math only; no files, no scoring). Call after an evaluation to pick the next verdict to aim for, or to relax the goal gracefully under a token/time budget; pair with topos_evaluate_* for actual metrics. Returns a PreferenceWalkResult: walk (steps from target down to just above current), next_step, progress in [0, 1], aspirational_target/fallback_target, and induced_order (all 8 verdicts ranked).

Refactor hotspots (read-only). See topos_get_doc(topic="workflows").