context-aware 0.2.0

A lightweight, agent-centric context management framework for LLMs.

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.

---

🤖 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:

   pip install context-aware
   

2. Initialize a Project: Navigate to your target project root and run:

   context_aware init
   

   Or for an external project:

   context_aware --root /path/to/project init
   

3. Index the Codebase: Parse and store the project structure (runs locally, no data leaves your machine).

   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).

context_aware init

index <path>

Parses Python files, extracts AST nodes (classes, functions, imports), and updates the graph.

context_aware index ./src

3. Search

Search for relevant code context. Returns signatures, docstrings, and dependencies.

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.

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?

   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.

   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?

   context_aware impacts "class:user.py:User"
   

   Output: List of dependents: AccountService, TransactionManager. "Okay, I need to check those files too."

4. 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).