srcodex 0.2.0__tar.gz

srcodex-0.2.0/.env.example

@@ -0,0 +1,27 @@
+# srcodex Environment Configuration
+
+# =============================================================================
+# Claude API Configuration
+# =============================================================================
+
+# Public Anthropic API (default)
+ANTHROPIC_API_KEY=sk-ant-your-key-here
+ANTHROPIC_BASE_URL=https://api.anthropic.com
+ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-20250514
+
+# =============================================================================
+# Enterprise Gateway Support (AMD/Google/NVIDIA internal users)
+# =============================================================================
+# If your organization uses an LLM gateway, configure accordingly:
+
+# Example: Internal gateway with subscription key
+# AMD_LLM_API_KEY=your-subscription-key
+# ANTHROPIC_BASE_URL=https://your-gateway.company.com/Anthropic
+# ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4.5
+
+# =============================================================================
+# Notes
+# =============================================================================
+# - Public users: Set ANTHROPIC_API_KEY
+# - Enterprise users: Set your company's gateway key (e.g., AMD_LLM_API_KEY)
+# - The service auto-detects which mode to use based on available keys

srcodex-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonathan L'Work
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

srcodex-0.2.0/MANIFEST.in

@@ -0,0 +1,14 @@
+include README.md
+include LICENSE
+include pyproject.toml
+include .env.example
+
+# Include CSS files for TUI
+recursive-include srcodex/tui *.tcss
+
+# Exclude development files
+exclude STATUS.md
+exclude WORKFLOW.md
+global-exclude __pycache__
+global-exclude *.py[co]
+global-exclude .DS_Store

srcodex-0.2.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: srcodex
+Version: 0.2.0
+Summary: Semantic code explorer with AI-powered search and analysis
+Author-email: Jonathan Antoun <jonathan.antoun@amd.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Jonathan03ant/srcodex
+Project-URL: Repository, https://github.com/Jonathan03ant/srcodex
+Project-URL: Issues, https://github.com/Jonathan03ant/srcodex/issues
+Keywords: code-search,semantic-analysis,ai,llm,code-exploration
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1.0
+Requires-Dist: textual[syntax]>=0.47.0
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: uvicorn>=0.23.0
+Requires-Dist: anthropic>=0.7.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: tqdm>=4.66.0
+Dynamic: license-file
+
+# srcodex
+
+**Semantic code explorer with AI-powered search and analysis**
+
+srcodex builds a semantic graph of your codebase and provides AI-powered exploration through natural language queries. Think of it as an intelligent code search that understands relationships, call graphs, and architecture.
+
+## Why srcodex?
+
+Unlike generic code assistants (Claude CLI, GitHub Copilot, etc.) that read entire files to answer questions, srcodex uses a **semantic graph database** to understand your code:
+
+| Question | Generic Assistant | srcodex |
+|----------|------------------|---------|
+| "Who calls function X?" | Grep entire codebase (20K tokens) | `get_callers('X')` (200 tokens) |
+| "Show call chain A→B" | Read multiple files, manual tracing | Graph query (500 tokens) |
+| "Find all ioctls" | Grep + read matches (15K tokens) | Database search (300 tokens) |
+| "Explain module Y" | Read 10+ files (30K tokens) | Aggregate query (2K tokens) |
+
+**Result:** 90% more token-efficient, instant relationship queries, and unique capabilities impossible for file-based tools (call chains, data flow analysis, architecture visualization).
+
+## Features
+
+- **Semantic Indexing**: Builds a persistent graph of symbols, functions, types, and their relationships
+- **AI-Powered Search**: Ask questions in natural language about your code
+- **Call Graph Analysis**: Trace function calls, dependencies, and execution paths
+- **Terminal UI**: Beautiful terminal interface with file browser and AI chat
+- **Multi-Language**: Supports C, C++, Python, and more
+- **Fast**: SQLite-backed graph queries with intelligent caching
+- **Portable**: `.srcodex/` directory makes indexed projects shareable
+
+## Installation
+
+```bash
+pip install srcodex
+```
+
+## Quick Start
+
+```bash
+# Index your codebase (first time)
+cd /path/to/your/project
+srcodex
+
+# Output:
+# No .srcodex/ found. Index this directory? (y/n) y
+# [Indexing happens...]
+# [TUI launches]
+
+# Next time - instant launch
+srcodex
+```
+
+## Usage
+
+Once indexed, use the TUI to:
+- Browse files and symbols
+- Search across your codebase
+- Chat with AI about your code architecture
+- Trace call chains and dependencies
+
+### Example AI Queries
+
+```
+"What does the init_system function do?"
+"Show me all functions that call malloc"
+"Trace the execution path from main to shutdown"
+"What structs are defined in config.h?"
+```
+
+## Configuration
+
+Copy `.env.example` to `.env` and configure your API key:
+
+```bash
+# Public Anthropic API
+ANTHROPIC_API_KEY=sk-ant-your-key-here
+
+# Or enterprise gateway (if applicable)
+AMD_LLM_API_KEY=your-subscription-key
+```
+
+## Requirements
+
+- Python 3.9+
+- Universal CTags (`brew install universal-ctags` or `apt install universal-ctags`)
+- Cscope (optional, for call graph)
+- Claude API key (Anthropic or enterprise gateway)
+
+## How It Works
+
+1. **Indexing**: Extracts symbols, relationships, and metadata using CTags and Cscope
+2. **Graph Building**: Creates semantic graph with typed edges (CALLS, INCLUDES, ACCESSES)
+3. **AI Integration**: Claude queries the graph using specialized tools (not reading full files)
+4. **Token Efficiency**: **99%+ reduction** in tokens vs. traditional code assistants
+   - **Breakthrough caching architecture**: 25-100 tokens per query after initial cache build
+   - Aggressive parallel tool batching (20-40 tools per iteration)
+   - 3-iteration cache strategy: iterations 1-3 cached, iteration 4 answers with cached data
+   - Semantic graph queries instead of file reads (10-100x more efficient)
+   - **Real example**: 500 input tokens vs 60,000+ for traditional file-based approaches
+   - Cache persists across queries - subsequent questions cost nearly nothing!
+
+## Project Structure
+
+After indexing, your project will have:
+
+```
+your-project/
+├── .srcodex/
+│   ├── metadata.json       # Project stats
+│   ├── config.toml         # Indexing config
+│   ├── data/
+│   │   └── project.db      # Semantic graph
+│   └── logs/               # Debug logs
+└── [your source files...]
+```
+
+## Development
+
+```bash
+# Clone repository
+git clone https://github.com/Jonathan03ant/srcodex.git
+cd srcodex
+
+# Install in development mode
+pip install -e .
+
+# Run tests
+pytest
+```
+
+## License
+
+MIT License - see LICENSE file for details
+
+## Contributing
+
+Contributions welcome! Please open an issue or pull request.
+
+## Links
+
+- [GitHub Repository](https://github.com/Jonathan03ant/srcodex)
+- [Issue Tracker](https://github.com/Jonathan03ant/srcodex/issues)
+- [Documentation](https://github.com/Jonathan03ant/srcodex/wiki)

srcodex-0.2.0/README.md

@@ -0,0 +1,142 @@
+# srcodex
+
+**Semantic code explorer with AI-powered search and analysis**
+
+srcodex builds a semantic graph of your codebase and provides AI-powered exploration through natural language queries. Think of it as an intelligent code search that understands relationships, call graphs, and architecture.
+
+## Why srcodex?
+
+Unlike generic code assistants (Claude CLI, GitHub Copilot, etc.) that read entire files to answer questions, srcodex uses a **semantic graph database** to understand your code:
+
+| Question | Generic Assistant | srcodex |
+|----------|------------------|---------|
+| "Who calls function X?" | Grep entire codebase (20K tokens) | `get_callers('X')` (200 tokens) |
+| "Show call chain A→B" | Read multiple files, manual tracing | Graph query (500 tokens) |
+| "Find all ioctls" | Grep + read matches (15K tokens) | Database search (300 tokens) |
+| "Explain module Y" | Read 10+ files (30K tokens) | Aggregate query (2K tokens) |
+
+**Result:** 90% more token-efficient, instant relationship queries, and unique capabilities impossible for file-based tools (call chains, data flow analysis, architecture visualization).
+
+## Features
+
+- **Semantic Indexing**: Builds a persistent graph of symbols, functions, types, and their relationships
+- **AI-Powered Search**: Ask questions in natural language about your code
+- **Call Graph Analysis**: Trace function calls, dependencies, and execution paths
+- **Terminal UI**: Beautiful terminal interface with file browser and AI chat
+- **Multi-Language**: Supports C, C++, Python, and more
+- **Fast**: SQLite-backed graph queries with intelligent caching
+- **Portable**: `.srcodex/` directory makes indexed projects shareable
+
+## Installation
+
+```bash
+pip install srcodex
+```
+
+## Quick Start
+
+```bash
+# Index your codebase (first time)
+cd /path/to/your/project
+srcodex
+
+# Output:
+# No .srcodex/ found. Index this directory? (y/n) y
+# [Indexing happens...]
+# [TUI launches]
+
+# Next time - instant launch
+srcodex
+```
+
+## Usage
+
+Once indexed, use the TUI to:
+- Browse files and symbols
+- Search across your codebase
+- Chat with AI about your code architecture
+- Trace call chains and dependencies
+
+### Example AI Queries
+
+```
+"What does the init_system function do?"
+"Show me all functions that call malloc"
+"Trace the execution path from main to shutdown"
+"What structs are defined in config.h?"
+```
+
+## Configuration
+
+Copy `.env.example` to `.env` and configure your API key:
+
+```bash
+# Public Anthropic API
+ANTHROPIC_API_KEY=sk-ant-your-key-here
+
+# Or enterprise gateway (if applicable)
+AMD_LLM_API_KEY=your-subscription-key
+```
+
+## Requirements
+
+- Python 3.9+
+- Universal CTags (`brew install universal-ctags` or `apt install universal-ctags`)
+- Cscope (optional, for call graph)
+- Claude API key (Anthropic or enterprise gateway)
+
+## How It Works
+
+1. **Indexing**: Extracts symbols, relationships, and metadata using CTags and Cscope
+2. **Graph Building**: Creates semantic graph with typed edges (CALLS, INCLUDES, ACCESSES)
+3. **AI Integration**: Claude queries the graph using specialized tools (not reading full files)
+4. **Token Efficiency**: **99%+ reduction** in tokens vs. traditional code assistants
+   - **Breakthrough caching architecture**: 25-100 tokens per query after initial cache build
+   - Aggressive parallel tool batching (20-40 tools per iteration)
+   - 3-iteration cache strategy: iterations 1-3 cached, iteration 4 answers with cached data
+   - Semantic graph queries instead of file reads (10-100x more efficient)
+   - **Real example**: 500 input tokens vs 60,000+ for traditional file-based approaches
+   - Cache persists across queries - subsequent questions cost nearly nothing!
+
+## Project Structure
+
+After indexing, your project will have:
+
+```
+your-project/
+├── .srcodex/
+│   ├── metadata.json       # Project stats
+│   ├── config.toml         # Indexing config
+│   ├── data/
+│   │   └── project.db      # Semantic graph
+│   └── logs/               # Debug logs
+└── [your source files...]
+```
+
+## Development
+
+```bash
+# Clone repository
+git clone https://github.com/Jonathan03ant/srcodex.git
+cd srcodex
+
+# Install in development mode
+pip install -e .
+
+# Run tests
+pytest
+```
+
+## License
+
+MIT License - see LICENSE file for details
+
+## Contributing
+
+Contributions welcome! Please open an issue or pull request.
+
+## Links
+
+- [GitHub Repository](https://github.com/Jonathan03ant/srcodex)
+- [Issue Tracker](https://github.com/Jonathan03ant/srcodex/issues)
+- [Documentation](https://github.com/Jonathan03ant/srcodex/wiki)

srcodex-0.2.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "srcodex"
+version = "0.2.0"
+description = "Semantic code explorer with AI-powered search and analysis"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [
+    {name = "Jonathan Antoun", email = "jonathan.antoun@amd.com"}
+]
+keywords = [
+    "code-search",
+    "semantic-analysis",
+    "ai",
+    "llm",
+    "code-exploration"
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+]
+
+dependencies = [
+    "click>=8.1.0",
+    "textual[syntax]>=0.47.0",
+    "fastapi>=0.100.0",
+    "uvicorn>=0.23.0",
+    "anthropic>=0.7.0",
+    "httpx>=0.24.0",
+    "tqdm>=4.66.0",
+]
+
+[project.scripts]
+srcodex = "srcodex.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/Jonathan03ant/srcodex"
+Repository = "https://github.com/Jonathan03ant/srcodex"
+Issues = "https://github.com/Jonathan03ant/srcodex/issues"

srcodex-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

srcodex-0.2.0/srcodex/backend/chat.py

@@ -0,0 +1,79 @@
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel
+from .services.claude_service import ClaudeService
+from .services.logger_setup import setup_backend_logging
+from fastapi.responses import StreamingResponse
+import json
+import logging
+
+
+setup_backend_logging()
+logger = logging.getLogger(__name__)
+
+app = FastAPI()
+
+try:
+    claude_service = ClaudeService()
+except ValueError as e:
+    print(f"Warning: {e}")
+    claude_service = None
+
+class ChatRequest(BaseModel):
+    """Request body for chat endpoint"""
+    message: str
+    conversation_history: list = []
+
+class ChatResponse(BaseModel):
+    """Response body for chat endpoint"""
+    response: str
+
+@app.post("/api/chat", response_model=ChatResponse)
+async def chat(request: ChatRequest):
+    """
+    Chat endpoint - sends message to Claude and returns response
+    Example:
+        POST /api/chat
+        {"message": "What does functionX do?"}
+
+        Returns:
+        {"response": "FunctionX is a function that..."}
+    """
+    if not claude_service:
+        raise HTTPException(status_code=500, detail="Claude service not initialized - check API key")
+
+    if not request.message.strip():
+        raise HTTPException(status_code=400, detail="Message cannot be empty")
+
+    try:
+        logger.info(f"Chat request: {request.message[:100]}...")
+        response = claude_service.send_message_with_tools(request.message, request.conversation_history)
+        logger.info(f"Chat response: {len(response)} chars")
+        return ChatResponse(response=response)
+    except Exception as e:
+        logger.error(f"Claude API error: {str(e)}")
+        raise HTTPException(status_code=500, detail=f"Claude API error: {str(e)}")
+
+@app.post("/api/chat/stream")
+async def chat_stream(request: ChatRequest):
+    """
+    Streaming chat endpoint - streams Claude's response in real-time
+
+    Streams newline-delimited JSON objects:
+    - Text chunks: {"type": "text", "content": "..."}
+    - Token metadata: {"type": "tokens", "input": 1234, "output": 56, "total": 1290}
+    """
+    if not claude_service:
+        raise HTTPException(status_code=500, detail="Claude service not initialized")
+
+    if not request.message.strip():
+        raise HTTPException(status_code=400, detail="Message cannot be empty")
+
+    try:
+        def generate():
+            for chunk in claude_service.stream_message_with_tools(request.message, request.conversation_history):
+                # Stream as newline-delimited JSON
+                yield json.dumps(chunk) + "\n"
+
+        return StreamingResponse(generate(), media_type="application/x-ndjson")
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Claude API error: {str(e)}")

srcodex-0.2.0/srcodex/backend/main.py

@@ -0,0 +1,98 @@
+"""
+srcodex Backend - Semantic Graph API
+"""
+
+from fastapi import FastAPI
+from pathlib import Path
+from typing import Dict, List, Any
+import sys
+sys.path.insert(0, str(Path(__file__).parent))
+from services.file_tree import FileTreeService
+DB_PATH = Path(__file__).parent.parent / "data" / "pmfw_main.db" ##Database path
+
+app = FastAPI(title="srcodex API", version="0.1.0")
+file_tree_service = FileTreeService(str(DB_PATH))
+
+@app.get("/")
+async def root() -> Dict[str, str]:
+    """ API Root, returns basic information """
+    return {
+        "name": "srcodex API",
+        "version": "0.1.0"
+    }
+
+@app.get("/projects/{project_id}/root")
+async def get_project_root(project_id: str) -> Dict[str, Any]:
+    """
+    Get Project root metadata
+    Example: GET /projects/pmfw_main/root
+    """
+    if project_id != Path(DB_PATH).stem:
+        return {"error": f"Project '{project_id}' not found!"}, 404
+
+    return file_tree_service.get_root()
+
+@app.get("/projects/{project_id}/children")
+def get_children(project_id: str, path: str = "") -> List[Dict[str, Any]]:
+    """
+    Get Immediate children of a directory.
+    Examples:
+        GET /projects/pmfw_main/children?path=
+        → Returns root children: [mp1/, mpccx/, common/, test/]
+        GET /projects/pmfw_main/children?path=mp1/src/app/
+        → Returns contents of mp1/src/app/
+    """
+    if project_id != Path(DB_PATH).stem:
+        return {"error": f"Project '{project_id}' not found!"}, 404
+
+    return file_tree_service.get_children(path)
+
+@app.get("/projects/{project_id}/search/files")
+def search_file(project_id: str, q: str = "") -> List[Dict[str, Any]]:
+    """
+    Search for files by name or path (like Ctrl+P in VSCode).
+    Examples:
+        GET /projects/pmfw_main/search/files?q=msg
+        → Returns files matching "msg": [msg.c, msg.h, ...]
+        GET /projects/pmfw_main/search/files?q=app/pow
+        → Returns files in "app" matching "pow": [mp1/src/app/power.c, ...]
+    """
+    if project_id != Path(DB_PATH).stem:
+        return {"error": f"Project '{project_id}' not found!"}, 404
+
+    return file_tree_service.search_file(q)
+
+@app.get("/projects/{project_id}/search/symbols")
+def search_symbol_global(project_id: str, q: str = "") -> List[Dict[str, Any]]:
+    """
+    Search for symbols globally across entire codebase (like Ctrl+Shift+F in VSCode).
+    Examples:
+        GET /projects/pmfw_main/search/symbols?q=voltage
+        → Returns all voltage-related symbols (variables, macros, structs, ...)
+        GET /projects/pmfw_main/search/symbols?q=Init
+        → Returns all initialization functions
+    """
+    if project_id != Path(DB_PATH).stem:
+        return {"error": f"Project '{project_id}' not found!"}, 404
+
+    return file_tree_service.search_symbol_global(q)
+
+@app.get("/projects/{project_id}/files/{file_path:path}/symbols")
+def search_symbol_infile(project_id: str, file_path: str, q: str = "") -> List[Dict[str, Any]]:
+    """
+    Search symbols within a specific file (like Ctrl+F in VSCode on open file).
+    Examples:
+        GET /projects/pmfw_main/files/mp1/src/app/msg.c/symbols?q=Isr
+        → Returns all symbols matching "Isr" in msg.c: [IsrHostMsg, IsrBiosMsg, ...]
+        GET /projects/pmfw_main/files/mp1/src/app/power.c/symbols?q=Init
+        → Returns all Init functions in power.c
+    """
+    if project_id != Path(DB_PATH).stem:
+        return {"error": f"Project '{project_id}' not found!"}, 404
+
+    return file_tree_service.search_symbol_infile(q, file_path)
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run("main:app", host="0.0.0.0", port=8000, reload=True)
+