AI Context Core

Compile token-efficient, verifiable context for AI-assisted coding.

ai-context-core (CLI ai-ctx) turns a Python project into context artifacts an AI agent can consume: a structured AI_CONTEXT.md, a machine-readable project_context.json, a token context_manifest.json and a symbol index. Everything is versioned, provenance-tagged and optionally token-budgeted.

Context-only contract (v5.0.0). ai-context-core is a context compiler (source → transform → render → verify): it consumes analysis instead of owning it. QGIS compliance, i18n, security scanning and quality gates live in qgis-plugin-analyzer; scaffolding in agentic-forge. Commands such as audit, qgis, security, patterns, inspect, full-scan, fix, scaffold, doctor, interactive and serve were removed (hidden redirect stubs remain for one release). See ADR-0008, the v5.0.0 plan and the CHANGELOG.

Features

Context compilation

• Pluggable sources: --source auto|external|builtin. external consumes qgis-plugin-analyzer output (analysis_results/project_context.json); builtin runs the internal AST engine. auto prefers external when present.
• Hybrid by design: structure tree, git evolution and manual notes are always computed by ai-context-core; the analysis fields come from the selected source.
• Provenance: every artifact carries a _meta block (source, schema, tool_version, git_sha, content_hash).

Token budget & manifest

• ai-ctx context --max-tokens N caps AI_CONTEXT.md with deterministic truncation; per-section caps via [context.budget].
• context_manifest.json records exact per-section token deltas, the budget and the total (total == header + sum(sections)).

Verification & index

• ai-ctx verify exits 1 when the tracked sources changed since the last render (content hash); ai-ctx context --check gates CI.
• ai-ctx symbols [--grep] writes a versioned symbols.json (definitions and references with file:line).
• ai-ctx health reports freshness, token usage, symbol coverage and provenance — no quality gate; it fails only on staleness.

Context analysis (builtin source)

• Structure: project tree, slide-of-code and file statistics.
• Entry points: __main__-guard detection.
• Dependencies: import graph, circular dependencies, unused imports, coupling (CBO), graph density/DAG, Mermaid diagram.
• Git evolution: hotspots and code churn.
• Metrics: cyclomatic complexity, Maintenance Index, type-hint coverage.

Performance & robustness

• Incremental cache: hybrid mtime + SHA-256 file cache (--no-cache to bypass).
• Smart parallelism: sequential below a threshold, batched ProcessPoolExecutor above it.
• Fast ignore: compiled-regex file filtering via .analyzerignore.
• Staleness-safe hashing: verification bypasses the in-process read cache.

Installation

Using uv (recommended)

# As a global tool
uv tool install ai-context-core

# Or inside a virtual environment
uv venv && source .venv/bin/activate
uv pip install ai-context-core

Using pip

pip install ai-context-core

It is always recommended to use a virtual environment.

Quick start

# 1. Initialize the .ai-context structure (optional)
ai-ctx init

# 2. Compile context artifacts
ai-ctx context                       # AI_CONTEXT.md + project_context.json + context_manifest.json
ai-ctx context --source external     # consume qgis-plugin-analyzer output
ai-ctx context --max-tokens 8000     # enforce a token budget
ai-ctx context --check               # generate and assert freshness (CI)

# 3. Verify and inspect
ai-ctx verify                        # exit 1 if sources changed since render
ai-ctx symbols --grep my_function    # file:line index lookup
ai-ctx health                        # freshness + tokens + symbols + provenance

Generated artifacts

Configuration

Full reference: docs/CONFIGURATION.md. Defaults live in src/ai_context_core/config/defaults.toml.

context_docs = []                      # extra markdown to embed as architecture notes

[context]
sections = ["structure", "metrics", "dependencies", "git"]

[context.budget]
max_tokens = 8000                      # override per run with --max-tokens N
# [context.budget.sections]
# structure = 1500

[sources]
source = "auto"                        # auto | external | builtin
# external_path = "analysis_results/project_context.json"

Analysis scope (.analyzerignore)

ai-ctx reads .analyzerignore at the project root to exclude paths from the analysis scope (modules, dependency graph, code metrics).

Commands reference

Compile & verify

Inspect

Project setup

Metrics

Metrics are heuristics computed from static analysis and are not directly comparable to the canonical metrics of other tools (e.g. qgis-analyzer).

API stability and deprecations

The canonical public API lives under ai_context_core.analyzer (engine, providers, visitors, builders), ai_context_core.sources, ai_context_core.context, ai_context_core.model and ai_context_core.cli.commands. Anything else is internal.

The v5.0.0 command removals keep hidden redirect stubs (e.g. ai-ctx audit, qgis, security, patterns) that point to their new owner for one release.

No import-level compatibility aliases remain: the ContextAggregator alias and the deprecations module were removed in v5.0.1.

Docker support

Reproducible development, testing and CI via Docker:

make docker-build    # Build all images
make docker-test     # Run the test suite with coverage
make docker-shell    # Interactive development shell
make docker-lint     # Run the linter

License

This project is licensed under the GNU General Public License v3 (GPLv3). See the LICENSE file for the full license text.