Metadata-Version: 2.4
Name: context-aware
Version: 0.1.5
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.
*   **Zero Hallucinations**: Provides explicit dependency chains (Import Graph).
*   **Scalable**: Built on SQLite + AST Analysis, works on projects of any size.
*   **Agent-Ready**: Returns structured XML optimized for LLM consumption.

---

## 🤖 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 query "your search terms" --mode=skeleton`
*   **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 retrieve "class:inventory.py:InventoryService" --mode=skeleton`
*   **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 retrieve "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
```

### 3. Search
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.

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

### 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 executes**: The bug is identified. The agent creates a patch.

---

## 🏗 Architecture (v0.4 - Hybrid Lookup)

*   **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 (`retrieve`), 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.

## ⚠️ Limitations
*   **Language Support**: Currently optimized for **Python** only.
*   **Semantic Understanding**: Relies on keyword/symbol matching + FTS. Does not yet use Vector Embeddings (planned for v0.5).
