v0.1.4

sciogen v0.1.4

Released 2026-07-08

MCP tools now fail open with actionable results

Agents were quietly abandoning the sciogen MCP tools — falling back to grep/read, or looping endlessly when a symbol wasn't found. The root cause was that the query tools failed closed: an empty index looked identical to a genuine miss, and a miss returned a bare error the agent had no way to act on.

This release makes every query tool fail open — it always returns a structured result that tells the agent what happened and what to do next.

Highlights

• "Not indexed" is now a distinct, recoverable state. A new NotIndexedError is raised when the graph is empty (index_version == 0), so an unindexed project no longer masquerades as a symbol miss. The MCP layer surfaces it with a clear next step: index the codebase first.

• Every miss comes with suggestions. SymbolNotFound now carries a .suggestions list, populated on both symbol and file lookups. Suggestions are computed with a SQL LIKE narrow followed by a difflib similarity rank over the already-indexed symbols/files tables — so a near-miss on a name gets the agent straight to the right symbol instead of a dead end.

• Structured MCP results. A new _safe wrapper on the 7 query tools converts NotIndexedError and SymbolNotFound into structured dicts containing a next step and suggestions, rather than raising raw exceptions across the protocol boundary. index_codebase is intentionally left unwrapped.

Changes

Area	What changed
sciogen/query/engine.py	New NotIndexedError, guarded in _cached. SymbolNotFound gains .suggestions, populated on every miss.
sciogen/stores/meta.py	New suggest_symbol_ids() / suggest_files() — LIKE narrow + difflib rank over indexed tables.
sciogen/mcp/server.py	New _safe wrapper maps errors to structured dicts with next + suggestions across the 7 query tools.
Tests	Suggestions + not-indexed guard coverage in tests/test_pipeline_and_query.py; new tests/test_mcp_server.py for _safe mapping. 57 tests pass.

Known follow-ups

These are tracked but not part of this release:

• index_codebase(path) with a non-empty path builds a second SciogenGraph that can lock-clash with the long-lived server singleton on the same KuzuDB directory. A future change should reuse the singleton when the path resolves to the server root.
• The tools only appear in an agent's tool list if the MCP server is registered — confirm sciogen setup-agent registration per project.

---

No changes to the indexing pipeline, graph schema, or query semantics. This is a reliability and ergonomics release for the MCP interface.

v0.1.3

v0.1.3 — Seamless sciogen explore on large codebases

Highlights

sciogen explore no longer gets laggy as the graph grows. Previously every
interaction — expanding a node, dragging the confidence slider, even hovering —
tore down the entire Cytoscape graph and re-ran a full force-directed layout
over everything on screen. On large codebases that meant visible stutter and, on
"Expand all", a frozen tab.

The rendering model is now incremental and position-locked: interactions only
touch the delta, and existing nodes never move.

What's fixed

• Expand / collapse is now local and instant. Revealing a node's children no
  longer relayouts the whole graph — new nodes fade in around the node that
  expanded them, and everything already on screen stays put.
• Confidence slider is smooth. Dragging it is debounced and only shows/hides
  edges instead of rebuilding the graph per pixel.
• Hover no longer janks on dense graphs. Focus highlighting is batched into a
  single redraw.
• "Expand all" no longer freezes the tab. It runs a single layout pass and
  skips layout animation past 700 nodes so large graphs snap into place.
• Faster edge computation. On-screen edges are gathered from the adjacency of
  visible nodes only, so cost scales with what's shown — not with the size of the
  entire codebase.
• Fixed a potential stack overflow in node-size scaling on very large graphs
  (Math.max(...spread) over all in-degrees).

Notes

• Purely a client-side rendering change to the generated explore HTML. No
  changes to indexing, the graph schema, stored data, or the Python/MCP query
  APIs.
• Existing .sciogen indexes work as-is — just re-run sciogen explore to
  regenerate the snapshot with the new viewer.

v0.1.2

sciogen v0.1.2

Fixed

Indexing no longer crashes on large, multi-language codebases.

sciogen index could fail during the Linking dependencies step with:

RuntimeError: Runtime exception: Node(nodeOffset: ...) has connected edges in table
CALLS in the bwd direction, which cannot be deleted. Please delete the edges first
or try DETACH DELETE.

Orphan-placeholder pruning relied on a single undirected degree count
(OPTIONAL MATCH (n)-[r]-()), which KuzuDB undercounts across multiple relationship
tables on large graphs. That caused a DELETE to be attempted on a node that still
had incoming CALLS edges. Pruning now computes true orphans by enumerating edge
endpoints per relationship table — exact regardless of graph size.

This also closes a latent correctness bug: the old undercount could have silently
pruned placeholder nodes that were legitimate call targets, dropping valid CALLS
edges from the graph.

Internal

• Added GraphStore regression tests for placeholder pruning (referenced
  placeholders retained, true orphans removed, no crash).