Metadata-Version: 2.4
Name: ai-context-core
Version: 2.5.1
Summary: Core logic for AI-driven development context management
Author-email: "Juan M. Bernales" <juanbernales@gmail.com>
License: GPL-3.0-or-later
Project-URL: Repository, https://github.com/geociencio/ai-context-core
Project-URL: Issues, https://github.com/geociencio/ai-context-core/issues
Project-URL: Documentation, https://github.com/geociencio/ai-context-core/blob/main/README.md
Keywords: ai,context,llm,analysis,development-tools,productivity
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Dynamic: license-file

# 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**:
```bash
uv tool install ai-context-core
```

**In a virtual environment**:
```bash
uv venv
source .venv/bin/activate
uv pip install ai-context-core
```

### Using `pip`

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

```bash
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

```bash
# 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
