Replaced OpenAI LLM API Key with Gemini API Key for the ability to ask questions in plain English. Updated documentation and project version to cover missing items.

Author: deepakdgupta1

.gitignore

@@ -69,7 +69,6 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
 
 # PyBuilder
 .pybuilder/
@@ -104,7 +103,6 @@ ipython_config.py
 #   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
 #   This is especially recommended for binary packages to ensure reproducibility, and is more
 #   commonly ignored for libraries.
-#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
 #poetry.lock
 #poetry.toml
 
@@ -211,5 +209,4 @@ knowcode_knowledge.json
 CHANGELOG.md
 docs_test/
 KnowCode.md
-docs/
 

README.md

@@ -23,6 +23,9 @@ source .venv/bin/activate  # On Windows: .venv\Scripts\activate
 
 # Install KnowCode (with dev dependencies)
 uv sync --dev
+
+# Set OpenAI API Key (required for semantic search and 'ask' command)
+export GOOGLE_API_KEY="sk-..."
 ```
 
 ## Quick Start
@@ -158,6 +161,34 @@ Once running, you can access endpoints like:
 - `POST /api/v1/context/query` `(semantic search)`
 - `POST /api/v1/reload` (to refresh data after a new `analyze` run)
 
+### `history`
+Show git history for the codebase or specific entities. Requires analysis with `--temporal`.
+
+```bash
+knowcode history [target] [--limit <n>]
+```
+
+**Example:**
+```bash
+# Show recent project history
+knowcode history --limit 5
+
+# Show history for a specific class
+knowcode history "KnowledgeStore"
+```
+
+### `ask`
+Ask questions about the codebase using an LLM agent. Requires `GOOGLE_API_KEY` environment variable.
+
+```bash
+knowcode ask <question> [--model <model>]
+```
+
+**Example:**
+```bash
+knowcode ask "How does the graph builder work?"
+```
+
 ## Supported Languages (MVP)
 
 - **Python** (.py) - Full AST parsing (Supports Python 3.9 - 3.12)

docs/api/knowledge_store.md

@@ -0,0 +1,72 @@
+# Knowledge Store API
+
+The `KnowledgeStore` is the central repository for the semantic graph derived from the codebase. It persists the graph to a JSON file and provides query mechanisms.
+
+## Class: `KnowledgeStore`
+
+**Module:** `knowcode.storage.knowledge_store`
+
+### Initialization
+
+```python
+store = KnowledgeStore()
+```
+
+### Persistence
+
+#### `save(path: str | Path)`
+Saves the current graph, including entities, relationships, and metadata, to a JSON file (default `knowcode_knowledge.json`).
+
+#### `load(path: str | Path) -> KnowledgeStore`
+Class method to load a store from a JSON file (or directory containing the file).
+
+### Core Properties
+
+- **`entities`**: A dictionary mapping entity IDs to `Entity` objects.
+- **`relationships`**: A list of `Relationship` objects.
+- **`metadata`**: A dictionary containing scan statistics (scan time, file count) and errors.
+
+### Query Methods
+
+#### `get_entity(entity_id: str) -> Optional[Entity]`
+Retrieve an entity object by its unique ID.
+
+#### `search(pattern: str) -> list[Entity]`
+Search for entities where the name or qualified name matches the substring pattern (case-insensitive).
+
+#### `get_callers(entity_id: str) -> list[Entity]`
+Find all entities that call the target entity (incoming `CALLS` edges).
+
+#### `get_callees(entity_id: str) -> list[Entity]`
+Find all entities that are called by the source entity (outgoing `CALLS` edges).
+
+#### `get_children(entity_id: str) -> list[Entity]`
+Find all entities contained within the source entity (e.g., methods within a class).
+
+#### `get_parent(entity_id: str) -> Optional[Entity]`
+Find the container of an entity (e.g., the class containing a method).
+
+#### `get_dependencies(entity_id: str) -> list[Entity]`
+Get all entities that the target entity depends on via calls or imports.
+
+#### `get_dependents(entity_id: str) -> list[Entity]`
+Get all entities that depend on the target entity via calls or imports.
+
+#### `get_entities_by_kind(kind: EntityKind | str) -> list[Entity]`
+List all entities of a specific kind (e.g., `EntityKind.CLASS`, "function").
+
+### Data Models
+
+#### `Entity`
+- `id`: Unique identifier (path + :: + qualified name)
+- `kind`: `EntityKind` (module, class, function, method, etc.)
+- `name`: Short name
+- `qualified_name`: Full dotted path
+- `location`: File path and line range
+- `source_code`: Raw source code (optional)
+- `docstring`: Extracted docstring (optional)
+
+#### `Relationship`
+- `source_id`: Origin entity ID
+- `target_id`: Destination entity ID
+- `kind`: `RelationshipKind` (calls, imports, contains, inherits, etc.)

docs/evolution.md

@@ -0,0 +1,111 @@
+# **Detailed Architecture & Roadmap**
+
+*Note: This document outlines the conceptual architecture of KnowCode, some of which looks ahead to future phases.*
+
+---
+
+## **1. Layered Architecture**
+
+KnowCode follows a multi-layer design to ensure extensibility, maintainability, and scalability.
+
+1.  **Ingestion Layer**: Source Code scanning, Parsing (AST/Tree-sitter).
+2.  **Analysis Layer**: Structural building, Semantic graph construction.
+3.  **Storage Layer**: Graph persistence, Vector storage.
+4.  **Retrieval Layer**: Hybrid search (Lexical + Semantic).
+5.  **Intelligence Layer**: Context synthesis, RAG orchestration.
+6.  **Interface Layer**: CLI, REST API (FastAPI).
+
+---
+
+## **2. Component Interaction**
+
+```mermaid
+flowchart TB
+    subgraph Ingestion
+        L1[Layer 1: Source Ingestion]
+    end
+    
+    subgraph Analysis
+        L2[Layer 2: Structural Parsing]
+        L3[Layer 3: Semantic Graph]
+        L4[Layer 4: Behavioral Analysis]
+        L5[Layer 5: Runtime Signals]
+        L6[Layer 6: Intent Extraction]
+    end
+    
+    subgraph Intelligence
+        L7[Layer 7: Doc Synthesis]
+        L8[Layer 8: Knowledge Store]
+        L9[Layer 9: Context Synthesis]
+    end
+    
+    subgraph Interface
+        L10[Layer 10: LLM Interface]
+        DEV[Developer]
+    end
+    
+    subgraph Evolution
+        L11[Layer 11: Feedback Loop]
+    end
+    
+    subgraph Cross-Cutting
+        SEC[Security]
+        OBS[Observability]
+        CFG[Configuration]
+    end
+    
+    L1 --> L2
+    L2 --> L3
+    L3 --> L4
+    L3 --> L6
+    L4 --> L8
+    L5 -.-> L8
+    L6 --> L8
+    L8 --> L7
+    L8 --> L9
+    L9 --> L10
+    L10 --> DEV
+    DEV --> L11
+    L11 --> L8
+    L11 --> L3
+    
+    SEC -.-> L1 & L8 & L10
+    OBS -.-> L1 & L3 & L8 & L10
+    CFG -.-> L2 & L4 & L9
+```
+
+---
+
+## **Implementation Status & Roadmap**
+
+### **Phase 1: Foundation (COMPLETED)**
+1. **[x] Source Scanning + Parsing (Layers 1-2)**: Scanner with gitignore support; parsers for Python (AST), JS/TS + Java (Tree-sitter), Markdown, YAML.
+2. **[x] Unified Semantic Graph (Layer 3)**: Entity/relationship model with reference resolution (calls/imports/contains/inherits).
+3. **[x] Local Knowledge Store (Layer 8)**: In-memory graph with JSON persistence and query helpers.
+4. **[x] Token-Budgeted Context Synthesis (Layer 9)**: Priority-ordered sections with truncation handling.
+5. **[x] Service Layer**: Shared business logic for CLI and API.
+
+### **Phase 2: Intelligence Server & RAG (COMPLETED)**
+6. **[x] FastAPI Server (Layer 10)**: Health, stats, search, context, semantic query, reload, entity details, callers/callees.
+7. **[x] Semantic Search & Indexing (Layer 4a)**: Chunker (module header/imports/entities), OpenAI embeddings, FAISS vector store, hybrid BM25+vector retrieval (RRF), reranking, dependency expansion.
+8. **[x] Indexer Persistence + CLI**: `index`/`semantic-search` commands with save/load.
+9. **[x] Watch Mode**: Background indexer + filesystem monitor for incremental re-indexing.
+10. **[x] CLI Workflows**: `analyze`, `query`, `context`, `export`, `stats`, `server`, `history`, `ask`.
+
+### **Phase 3: Temporal & Runtime Signals (COMPLETED)**
+11. **[x] Git History Ingestion (Temporal)**: Commit/author entities, authored/modified/changed_by relationships; surfaced via `--temporal` and `history`.
+12. **[x] Coverage Signals (Layer 5)**: Cobertura ingestion with coverage report entities and covers/executed_by relationships.
+
+### **Phase 4: Documentation Synthesis (PARTIAL)**
+13. **[x] Markdown Export (MVP)**: CLI `export` produces an index-style Markdown doc.
+14. **[ ] Multi-Level Doc Synthesis (Layer 7)**: Architecture/module/function narratives, change summaries, and freshness tracking.
+
+### **Phase 5: Deep Analysis (NEXT)**
+15. **[ ] Static Behavioral Analysis (Layer 4)**: Data flow, state transitions, side-effect classification.
+16. **[ ] Intent Extraction (Layer 6)**: ADR/PR/commit intent linking beyond commit metadata.
+17. **[ ] Confidence Scoring (Layer 3)**: Weighted edges/entities by evidence source.
+
+### **Phase 6: Enterprise (FUTURE)**
+18. **[ ] Security & RBAC**: Permissioned access and audit trails.
+19. **[ ] Scalability**: Large monorepo support and distributed processing.
+20. **[ ] Team Sharing**: Remote knowledge store sync and collaboration.