context-aware 0.3.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.

🌍 Supported Languages

• Python: Full support via Tree-sitter (Classes, Functions, Imports).
• JavaScript/TypeScript: Full support via Tree-sitter (Classes, Functions, Variables).
• Go: Full support via Tree-sitter (Structs, Interfaces, Functions).
• Other Languages: Easily extensible thanks to the new generic Tree-sitter analyzer.

---

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

   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
# Optional: Generate embeddings for semantic search (slower)
context_aware index ./src --semantic

search <query>

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.
• --semantic: Enable Hybrid Semantic Search (combines keywords + embeddings). Requires sentence-transformers.

read <id>

Read the full source code of a specific item found during search.

context_aware read "class:orders/processor.py:OrderProcessor"

impacts <id>

Analyze what depends on a specific item (Reverse Lookup).

context_aware impacts "class:user.py:User"

graph

Export the dependency graph to Mermaid format.

context_aware graph --output architecture.mmd

serve (or mcp)

Starts the Model Context Protocol (MCP) server. This allows AI Agents (like Claude Desktop) to mount the repository as a resource, enabling direct tool usage (search, read, impacts) over stdio.

context_aware serve
# or
context_aware mcp

ui

Starts the interactive visualization server (Browser UI).

context_aware ui --port 8000

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

• Analyzer: TreeSitterAnalyzer provides robust, error-tolerant parsing for Python, JS, TS, and Go. Extracts symbols and dependencies while storing only metadata in the DB.
• 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.