Tool reference

The tool surface (ToolService, ~135 methods)

The tool surface (ToolService, ~135 methods) — migrated from the README on 2026-08-31 and verified against the code at tag v0.1.4; if code and wiki ever disagree, the code wins and this page gets a PR.

Tool surface — ToolService (cie/tools/__init__.py, ~135 methods)

Every method returns the standard SPEC §0 envelope (ok/tool/results/ truncated/total/hint/elapsed_ms, cie.envelope); errors carry a mandatory hint. Grouped by capability (all also exposed over MCP and POST /tools/{tool}):

Core graph navigation — search_symbol, resolve_import, semantic_search, callers, callees, file_skeleton, path_between, failing_context, affected_by, class_hierarchy, test_map, actual_callers, dead_code_confirm, hybrid_search (lexical + dense vector + graph-centrality, with per-component scores), entity_context, view_file (windowed, line-numbered, joined with the symbol index). Embeddings: host core.llm, or the first-party OpenAI-compatible fallback (CIE_EMBED_DSN + key, stdlib — R10), or a registered override; first-party retrieval measured at recall@8 = 1.0 on two corpora (2026-08-31; comparison doc maintained locally).

GraphRAG Q&A — qa (cie.graphrag): a real pipeline — query_plan.classify picks a retrieval strategy, hybrid_search retrieves, rerank reorders by an LLM relevance judgment, entity_context expands the neighborhood, and a final LLM call answers with citations assembled separately from the graph (the LLM never emits citations itself).

Section 13 — Code Intelligence (on-demand analysis passes written as analysis nodes):

• Clone detection (clone_detect.py, CI-01..05): three fused signals — token-Jaccard (copy-paste), AST-shape Jaccard (renamed clones), embedding cosine (semantic clones) → CloneCluster nodes. Tools: clone_detect_run, clone_clusters, clone_find.
• Performance analysis (perf_analyze.py, CI-06..08): Big-O estimation (loop nesting + recursion) written onto FUNC/METHOD nodes, plus anti-pattern detection (N+1 queries, nested loops, sync I/O in a loop, unbounded growth). Tools: performance_analyze_run, performance_profile, antipattern_scan.
• Drift detection (drift_detect.py, CI-10..12): requirement gaps (task file_path vs indexed FILE nodes), API contract drift (reuses api_routes extraction), architectural drift. Tools: drift_detect_run, drift_report, architecture_check.
• Metrics (metrics.py, CI-19..21): rolls clone/drift/tech-debt into append-only MetricSnapshots (trend answerable from history). Tools: metrics, tech_debt_report, metric_trend.
• Communities (community_detect.py, RQ-04/AI-03): label-propagation detection (the real write-path behind Node.community — previously read-only with nothing populating it) + LLM-thematic CommunitySummary nodes carrying embeddings. Tools: community_detect_run, community_summarize_run, community_search.
• Quality governance: accuracy_check, freshness_report, comprehensiveness_report, salience_report.

Section 0 — Population & Real-Time Sync (sync.py): a two-graph model (speculative vs canonical), a 4-stage GateRunner quality gate, tiered confidence, symbol-level AST delta + move detection, soft-delete-on- revert, idempotent commit-linked batch population, sync-event classification. Tools: sync_quality_gate, sync_promote, sync_revert, sync_ast_delta, sync_evict_speculative, sync_load_commit, configure_layer_rules, get_layer_rules, install_git_hook.

Section 1 — Core Data Model extensions (data_model.py): export_rdf, related_edges, validate_property_constraints, type-flow resolution (type_flow_run/type_flow), dependency-graph (dependency_graph_run/ dependency_graph), documentation graph from markdown (doc_graph_run/ doc_search).

Section 14 — Confidence Framework (spec-vs-code assurance):

• Contracts (contracts.py, CF-01..03): python_assert-form contracts, best-effort binding by name to PRD scope, parameter-name domain-type validation, inject_assertions/strip_assertions. Tools: contracts_run, contracts, validate_types, inject_assertions, strip_assertions.
• Test synthesis (test_synthesis.py, CF-04/05): template-generated skeletons across six test types, bound to code via the same TESTS edges DM-14 uses. Tools: test_skeletons_run, test_skeletons, test_coverage.
• State machines (state_machine.py, CF-06/07): FSM extraction, dead/unreachable-state detection (real graph algorithms), structural code-vs-FSM check. Tools: state_machine_run, state_machine, fsm_validate.
• Traceability (traceability.py, CF-08/09): graph-traversal coverage/orphans/chain on the code side and the PRD-hierarchy side. Tools: traceability_coverage, traceability_orphans, traceability_chain, prd_traceability_coverage, prd_traceability_orphans, prd_traceability_chain.
• Semantic diff (semantic_diff.py, CF-10/11): pattern-matching spec-vs-code check (deliberately conservative, high false-negative by design). Tool: semantic_diff.
• Multi-agent consensus (consensus.py, CF-12/14): verdict storage + query (a durable exactly-once bus is explicitly not built here). Tools: record_verdict, agent_verdicts.
• Confidence scoring (confidence.py, CF-15/16): pure composition over contract/test/consensus signals; generation/runtime layers reported as None. Tools: confidence_report, justification (CF-17/18).
• Invariants & telemetry backflow (invariants.py, CF-19..21): safe contract-expression evaluation against a state snapshot + violation recording; graph traversal from a code node back to its contracts/tests. Tools: check_invariant, invariant_violations, telemetry_to_spec.

Section 15 — Decomposition Engine (decompose.py): reuses the existing HTML walker + interactive-element detector to decompose pages into Page/ImpliedPage/InteractiveElement/DerivedTaskHint nodes. Tools: decompose_page, page_tree, promote_hint_to_task, element_coverage, implied_pages_run, implied_pages.

Section 16 — Test Execution & APM (test_orchestration.py, mocking.py, mock_server.py, apm.py): test-plan generation over interactive elements / contracts / transitions / API endpoints / PRD error scenarios, test execution, coverage-gap reporting, nook-and-corner testing, unified coverage reports; third-party mock orchestration with a real runnable FastAPI mock server (explicit base-URL override, not network interception); APM metric ingestion incl. automatic pytest --junitxml timing collection, baselines, regression detection. Tools: test_plan, run_tests, record_test_result, test_results, coverage_gaps, nook_and_corner_test, unified_coverage_report, mock_registry_run, mock_registry, mock_coverage, start_mock_server, stop_mock_server, mock_violations, record_apm_metric, apm_metrics, performance_baseline, performance_regressions.

Section 17 — System Intelligence (subsystems.py): a static registry of every subsystem actually built in this codebase, with (repo, project) -> int population queries (callable, not raw Cypher, so the same test passes against both Neo4j and the in-memory double). Tools: subsystem_health, subsystem_gaps, subsystem_dependency_graph, subsystem_dependency_graph_run, population_path.

Runtime telemetry ingestion (telemetry.py, CI-15..17): real OpenTelemetry span ingestion over OTLP/HTTP with JSON encoding (received at POST /telemetry/otlp), distinct from test-time APM. Raw protobuf decoding is deliberately not attempted.

Virtual filesystem & sandbox (cie/tools/view.py, edit.py, runner.py, blame.py): jailed view_file (line-numbered, with a graph-joined symbol index, configurable size ceiling), write_file, write_files_atomic, edit_file, delete_file, run (subprocess + cwd jail + hard timeout — CIE_RUN_ROOT widens the jail), blame_history (git history joined with task-graph artifacts). Every write keeps the in-process heuristic symbol index incrementally fresh and re-resolves callers of unchanged files.

Heuristic fallback (cie/tools/index.py, heuristic.py): when a graph call fails or returns empty, ToolService lazily builds an in-memory SymbolIndex by walking+parsing the project tree, so search_symbol/file_skeleton/view_file keep working against an unindexed or partially-indexed tree — same result-shaping code path as the graph-backed path.