ai-context-core 2.5.0

Core logic for AI-driven development context management

AI Context Core

The central nervous system for your AI-assisted coding workflow.

Features

• Project Analysis: Deep AST analysis for Python projects.
• Context Management: Keeps .ai-context files updated.
• Profiles:
  • python-generic: Standard Python support.
  • qgis-plugin: Specialized rules for QGIS plugin development, including:
    • Processing Framework validation.
    • i18n (self.tr) coverage metrics.
    • Qt6/QGIS 4 transition audit.
    • metadata.txt strict validation.
• Workflow Automation: Standardized scripts for session management.
• Advanced Analysis:
  • Entry Point Detection: Supports QGIS plugins, Click CLIs, Flask, and FastAPI apps.
  • Anti-Pattern Detection: Identifies God Objects, Spaghetti Code, Magic Numbers, and Dead Code.
  • Design Pattern Detection: Native support for Strategy, Singleton, Observer, Factory, and Decorator patterns.
  • Security Audit: Scans for vulnerabilities like SQL Injection, eval/exec, and Secrets detection with false-positive filtering.
  • Advanced Metrics: Integrated Maintenance Index (MI) and CBO (Coupling Between Objects).
• Reporting:
  • Interactive HTML: Generate interactive project summaries with --format html.
  • Dependency Graphs: Automated Mermaid.js diagrams integrated into reports.
• Optimization:
  • FastIgnore: Ultra-fast file filtering using compiled Regex.
  • Smart Parallelism: Dynamic switching between sequential and parallel execution based on project size.
  • Single-Pass AST: Unified pattern detection for maximum performance.
  • Increment Cache: SHA-256 based file caching with --no-cache option to force full re-analysis.
• AI Recommendations: Heuristic-based actionable advice for code hygiene.

Installation

Using uv (Recommended)

uv is extremely fast and the preferred way to manage this tool.

As a global tool:

uv tool install ai-context-core

In a virtual environment:

uv venv
source .venv/bin/activate
uv pip install ai-context-core

Using pip

You can install ai-context-core using standard pip:

pip install ai-context-core

Note: It is always recommended to use a virtual environment.

Commands Reference

ai-ctx --version

Displays the current version of the tool.

• Usage: ai-ctx --version

ai-ctx init

Initializes the .ai-context structure in your project. It creates configuration files and initial prompt templates.

• Usage: ai-ctx init --profile <name>
• Example: ai-ctx init --profile qgis-plugin

ai-ctx analyze

Runs the complete analysis pipeline. Generates AI_CONTEXT.md, PROJECT_SUMMARY.md/html, and project_context.json.

• Options:
  • --format html: Generates an interactive HTML report.
  • --no-cache: Forces a full re-analysis of all files.
• Usage: ai-ctx analyze

ai-ctx inspect <file>

Performs a deep, granular analysis of a single Python file. Ideal for checking metrics and security for a specific module without running the full project analysis.

• Usage: ai-ctx inspect src/my_script.py

ai-ctx audit

A utility designed for CI/CD pipelines. It calculates the project's Quality Score and exits with code 1 if it falls below the specified threshold.

• Options:
  • --threshold <value>: Minimum score required (default: 70).
• Usage: ai-ctx audit --threshold 85

ai-ctx serve

Starts a local HTTP server to view the interactive PROJECT_SUMMARY.html report in your browser.

• Options:
  • --port <number>: Port to use (default: 8000).
  • --open: Opens the browser automatically.
• Usage: ai-ctx serve --open

ai-ctx patterns

Displays a clean, tabulated view of all Design Patterns detected across the project (Singleton, Factory, etc.).

• Usage: ai-ctx patterns

ai-ctx security

Executes a security-focused scan. It only runs checks for SQL injections, Secrets, and insecure code patterns, making it extremely fast.

• Usage: ai-ctx security

ai-ctx help-me

Provides a prioritized list of AI Recommendations generated by our heuristic engine. It focuses purely on actionable quality improvements.

• Usage: ai-ctx help-me

ai-ctx profiles

Lists all available configuration profiles.

• Usage: ai-ctx profiles

Comparison with Other Tools

ai-context-core is unique because it combines deep static analysis with workflow automation. Here is how it compares to other popular tools:

Feature	ai-context-core	repo2txt/code2prompt	aider
AST Analysis	✅ Deep (Patterns/Metrics)	❌ Basic/None	⚠️ Moderate (Repo Map)
Interactive CLI	✅ Extensive	❌ Simple Input/Output	✅ Full Chat UI
Security Audit	✅ Advanced (SQLi/Secrets)	❌ No	❌ No
Incremental Cache	✅ Yes (SHA-256)	❌ Usually No	✅ Yes
HTML Reports	✅ Interactive + Mermaid	❌ Text/Markdown only	❌ No
Project Profiles	✅ Specialized (QGIS, etc.)	❌ No	❌ No
Primary Goal	Smart Context & Hygiene	Code Ingestion	AI Pair Programming

Why choose ai-context-core?

• Unlike ingestion tools (repo2txt), we don't just dump code; we extrapolate meaning (patterns, debt, security).
• Unlike AI pair programmers (aider), we are LLM-agnostic and focus on providing the "source of truth" context for any AI assistant you use.
• Our Audit and Inspect modes make us the only tool in this category suitable for CI/CD pipelines.

Docker Support

The project includes Docker support for reproducible development, testing, and CI/CD.

Quick Start with Docker

# Build all images
make docker-build

# Run tests in Docker
make docker-test

# Interactive development shell
make docker-shell

# Run linter
make docker-lint

Docker Images

• Development (ai-ctx:dev) - Full environment with dev dependencies
• Test (ai-ctx:test) - Runs test suite with coverage
• Production (ai-ctx:prod) - Minimal runtime image

---

Generated by Ai-Context-Core