Metadata-Version: 2.4
Name: context-aware
Version: 0.2.2
Summary: A lightweight, agent-centric context management framework for LLMs.
Author-email: Ferdinando Bonsegna <ferdinando@example.com>
Project-URL: Homepage, https://github.com/yourusername/ContextAware
Project-URL: Bug Tracker, https://github.com/yourusername/ContextAware/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Intended Audience :: Developers
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0.0
Dynamic: license-file

# ContextAware

**ContextAware** is a lightweight, agent-centric context management framework. It acts as a "Map Provider" for LLMs, allowing them to navigate large codebases efficiently without consuming massive amounts of tokens.

## 🚀 Why ContextAware?

Standard RAG (Retrieval-Augmented Generation) is often too imprecise for coding tasks (missing dependencies, hallucinating imports). Reading the entire codebase is too expensive and slow.

**ContextAware solves this by treating your code as a Navigable Graph.**
*   **Token Efficiency**: Reduces exploration costs by 90% via "Skeleton Mode".
*   **Contextual Understanding**: LLMs often need to read dozens of files just to understand the project structure and locate relevant code. ContextAware replaces this with a structured map.
*   **Smart Ranking**: Uses PageRank-like scoring to prioritize core architectural components over utility scripts.
*   **Impact Analysis**: Explicitly answers "What breaks if I change this file?" via reverse graph lookup.
*   **Scalable**: Built on SQLite + Relational Graph, works on projects of any size.
*   **Agent-Ready**: Returns structured XML optimized for LLM consumption.

## 🌍 Supported Languages

*   **Python**: Full support (Classes, Functions, Imports).
*   **JavaScript**: ES6 Modules & CommonJS support.
*   **TypeScript**: Basic support (Structure analysis).


---

## 🤖 Agent Protocol (How to use this tool)

If you are an AI Agent (e.g., Devin, Cline, Gemini Code Assist), follow this explicit protocol to solve tasks with maximum efficiency.

### Workflow: "Skeleton-First" Navigation

Do not read file contents blindly. Use the tool to find what matters.

#### Phase 1: Discovery (Low Cost)
Ask "Where is the code related to X?" getting only the high-level structure.
*   **Command**: `context_aware search "your search terms"`
*   **Goal**: Identify relevant classes/functions and their relationships.
*   **Output**: You will see signatures and `<dependencies>` tags.

#### Phase 2: Traversal (Optional)
If a class depends on another service (e.g., `OrderProcessor` uses `InventoryService`), follow the link.
*   **Command**: `context_aware search "InventoryService"`
*   **Goal**: Understand the API of the dependency without reading its implementation.

#### Phase 3: Extraction (High Cost, High Value)
Once you pinpoint the exact function/class to modify or debug, fetch its full source code.
*   **Command**: `context_aware read "function:file.py:target_function"`
*   **Goal**: Get the actual code to work on.

---

## 📦 Installation & Setup

1.  **Install via pip**:
    ```bash
    pip install context-aware
    ```

2.  **Initialize a Project**:
    Navigate to your target project root and run:
    ```bash
    context_aware init
    ```
    *Or for an external project:*
    ```bash
    context_aware --root /path/to/project init
    ```

3.  **Index the Codebase**:
    Parse and store the project structure (runs locally, no data leaves your machine).
    ```bash
    context_aware index .
    # Or
    context_aware --root /path/to/project index /path/to/project
    ```

---

## 📖 CLI Reference

### `init`
Creates the local SQLite store (`.context_aware/context.db`).
```bash
context_aware init
```

### `index <path>`
Parses Python files, extracts AST nodes (classes, functions, imports), and updates the graph.
```bash
context_aware index ./src
```

### `search <query>`
Search for relevant code context. Returns signatures, docstrings, and dependencies.
```bash
context_aware search "order processing"
```
Options:
- `--type <class|function|file>`: Filter results.
- `--output <file>`: Save results to a file.

### `read <id>`
Read the full source code of a specific item found during search.
```bash
context_aware read "class:orders/processor.py:OrderProcessor"
```

### `impacts <id>`
Analyze what depends on a specific item (Reverse Lookup).
```bash
context_aware impacts "class:user.py:User"
```

### `graph`
Export the dependency graph to Mermaid format.
```bash
context_aware graph --output architecture.mmd
```


### Global Options
*   `--root <path>`: Specify the root directory of the project (where `.context_aware` lives). Essential when working on projects outside the current working directory.

---

## ⚡️ Example Scenario

**Task**: "Fix a bug in the discount calculation logic."

1.  **Agent asks**: Where are discounts handled?
    ```bash
    context_aware search "discount calculation"
    ```
    *Output*: Found `class:PricingService` in `pricing.py`. It uses `UserTierService`.

2.  **Agent analyzes**: I see `PricingService.calculate_discount`. I need to see the code.
    ```bash
    context_aware read "class:pricing.py:PricingService"
    ```
    *Output*: Full Python code of the class.

3.  **Agent plans refactor**: I want to change the User class. context_aware, what depends on it?
    ```bash
    context_aware impacts "class:user.py:User"
    ```
    *Output*: List of dependents: `AccountService`, `TransactionManager`. "Okay, I need to check those files too."

3.  **Agent executes**: The bug is identified. The agent creates a patch.

---

## 🏗 Architecture

*   **Analyzer**: `PythonAnalyzer` extracts symbols and dependencies but **stores only metadata** (pointers) in the DB to keep it light.
*   **Store**: `SQLiteContextStore` with FTS5 for fast fuzzy search of docstrings and names.
*   **Router**: `GraphRouter` performs graph traversal on the metadata.
*   **Retriever**: **On-Demand AST Parsing**. When you request code (`read`), the system reads the file from disk *at that moment* and extracts the function body. This ensures **zero stale data**—you always get the current code.
*   **Compiler**: Converts nodes into XML prompts (`<item>`, `<dependencies>`) for the LLM.
