context-aware 0.1.1

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".
• 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:

   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

query <text>

Semantic fuzzy search on the graph.

• --mode=skeleton (Recommended): Returns signatures + dependencies.
• --mode=full: Returns full source code.

context_aware query "payment processing" --mode=skeleton

retrieve <id>

Fetches a specific item by its unique ID (found in previous query results).

context_aware retrieve "class:payments.py:PaymentGateway"

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 query "discount calculation" --mode=skeleton
   

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