codebookx 3.0.0__tar.gz

codebookx-3.0.0/NOTICE.md

@@ -0,0 +1,20 @@
+# NOTICE
+
+Codebase-X includes code from the following open-source projects, used under their respective licenses:
+
+1. **GitNexus** (https://github.com/abhigyanpatwari/GitNexus)
+   - License: Apache License 2.0
+   - Adapted modules: AST parsing, symbol extraction logic.
+   - Original copyright (c) 2024 Abhigyan Patwari.
+
+2. **claude-mem** (https://github.com/thedotmack/claude-mem)
+   - License: MIT License
+   - Adapted modules: Structural skeleton extraction.
+   - Original copyright (c) 2024 thedotmack.
+
+3. **repomix** (https://github.com/yamadashy/repomix)
+   - License: MIT License
+   - Adapted logic: File packing algorithm.
+   - Original copyright (c) 2024 yamadashy.
+
+All original copyright notices have been preserved in the adapted source files where applicable.

codebookx-3.0.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: codebookx
+Version: 3.0.0
+Summary: Codebase-X: Production-grade, offline code comprehension and AI-tasking platform
+Author-email: Satvik Jain <klickbae8yt@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/satvikjain/codebook
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: NOTICE.md
+Requires-Dist: requests>=2.28.0
+Requires-Dist: tqdm>=4.64.0
+Requires-Dist: questionary>=2.0.0
+Requires-Dist: tomli>=2.0.0; python_version < "3.11"
+Provides-Extra: ui
+Requires-Dist: flask>=2.0.0; extra == "ui"
+Provides-Extra: dev
+Requires-Dist: black; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: tree-sitter; extra == "dev"
+Dynamic: license-file
+
+# Codebase-X
+
+**The Intelligent AI Assistant for Your Entire Codebase.**
+
+Codebase-X is a production-grade, offline platform designed to give you total control over your code. By building a deep, persistent Knowledge Graph of your repository, Codebase-X enables advanced architectural analysis, atomic task decomposition, and prompt engineering—all while keeping your data 100% private and local.
+
+---
+
+## 🗺️ User Journey
+
+1.  **`codebookx analyze`**: Scan your repository to build a Knowledge Graph and architectural teardown.
+2.  **`codebookx view`**: Launch the interactive Knowledge Graph browser to explore your code visually.
+3.  **`codebookx ask "..."`**: Ask technical questions about your codebase, powered by the Knowledge Graph context.
+
+---
+
+## 🚀 Core Capabilities
+
+### 🏛️ Codebase Teardown (Analyze)
+Stop guessing how your system works. Codebase-X scans your entire repository to generate a high-level architectural blueprint.
+*   **Elevator Pitch:** Get an instant summary of any project.
+*   **Architecture Blueprint:** Automatically mapped folder roles and purposes.
+*   **Data Flow:** Understand how the core components of your system interact.
+```bash
+codebookx analyze
+```
+
+### 🔨 Atomic Task Decomposition (Decompose)
+Break complex features into small, manageable pieces. Codebase-X analyzes your feature request against your actual codebase to produce a series of atomic tasks.
+*   **AI-Ready:** Each task includes a "copy-paste" prompt specifically designed for AI coding assistants.
+*   **Context-Aware:** Tasks reference the exact files and symbols needed.
+```bash
+codebookx decompose "Add a user settings page"
+```
+
+### ✨ Prompt Enhancement (Enhance)
+Stop writing vague prompts. The Prompt Enhancer uses the Knowledge Graph to inject relevant file paths, function signatures, and dependencies into your request, creating a high-context prompt that gets it right the first time.
+```bash
+codebookx enhance "Refactor the authentication flow"
+```
+
+### 🕸️ Knowledge Graph Browser (View)
+Explore your code visually. Launch an interactive local web UI to traverse your project's dependency graph, find symbols, and manage your AI tasks.
+*   **Visual Map:** Interactive D3.js force-directed graph available at `/graph`.
+*   **Relations:** Track CALLS, IMPORTS, and CONTAINS relationships cross-file.
+```bash
+codebookx view
+```
+
+### ❓ Technical Q&A (Ask)
+Knowledge Graph-backed Q&A for your codebase. Answers are saved automatically.
+```bash
+# Single question
+codebookx ask "How is the authentication handled in this project?"
+
+# Interactive chat mode (multi-turn, context carry-over)
+codebookx ask -c "Walk me through the data flow"
+
+# Save Q&A logs to a custom directory
+codebookx ask "What does run_ask do?" --dir ~/my-notes
+```
+*   **Auto-save:** Every Q&A and chat session is saved to `ask_history/` by default (`--dir` to override, or set `CODEBOOK_ASK_DIR` env var).
+*   **Chat mode (`-c`):** Multi-turn conversation with full context carry-over. Each turn is saved incrementally — no history lost on crash.
+
+---
+
+## 🛠️ Getting Started
+
+**1. Install**
+```bash
+pip install .
+```
+
+**2. Local LLM Setup**
+Codebase-X is designed to work with **LM Studio**, **Ollama**, or any OpenAI-compatible local server. Ensure your server is running.
+
+**3. Initial Analysis**
+Scan your repository to build the Knowledge Graph:
+```bash
+codebookx analyze
+```
+
+---
+
+## 🔒 Privacy & Performance
+*   **100% Offline:** Your code never leaves your machine. No cloud APIs, no subscriptions.
+*   **Persistent Indexing:** Uses a lightning-fast SQLite-backed Knowledge Graph with hash-based caching.
+*   **Multi-Language:** Deep support for Python, TypeScript, JavaScript, and more.
+
+---
+
+## 📄 License
+Codebase-X is released under the MIT License.

codebookx-3.0.0/README.md

@@ -0,0 +1,93 @@
+# Codebase-X
+
+**The Intelligent AI Assistant for Your Entire Codebase.**
+
+Codebase-X is a production-grade, offline platform designed to give you total control over your code. By building a deep, persistent Knowledge Graph of your repository, Codebase-X enables advanced architectural analysis, atomic task decomposition, and prompt engineering—all while keeping your data 100% private and local.
+
+---
+
+## 🗺️ User Journey
+
+1.  **`codebookx analyze`**: Scan your repository to build a Knowledge Graph and architectural teardown.
+2.  **`codebookx view`**: Launch the interactive Knowledge Graph browser to explore your code visually.
+3.  **`codebookx ask "..."`**: Ask technical questions about your codebase, powered by the Knowledge Graph context.
+
+---
+
+## 🚀 Core Capabilities
+
+### 🏛️ Codebase Teardown (Analyze)
+Stop guessing how your system works. Codebase-X scans your entire repository to generate a high-level architectural blueprint.
+*   **Elevator Pitch:** Get an instant summary of any project.
+*   **Architecture Blueprint:** Automatically mapped folder roles and purposes.
+*   **Data Flow:** Understand how the core components of your system interact.
+```bash
+codebookx analyze
+```
+
+### 🔨 Atomic Task Decomposition (Decompose)
+Break complex features into small, manageable pieces. Codebase-X analyzes your feature request against your actual codebase to produce a series of atomic tasks.
+*   **AI-Ready:** Each task includes a "copy-paste" prompt specifically designed for AI coding assistants.
+*   **Context-Aware:** Tasks reference the exact files and symbols needed.
+```bash
+codebookx decompose "Add a user settings page"
+```
+
+### ✨ Prompt Enhancement (Enhance)
+Stop writing vague prompts. The Prompt Enhancer uses the Knowledge Graph to inject relevant file paths, function signatures, and dependencies into your request, creating a high-context prompt that gets it right the first time.
+```bash
+codebookx enhance "Refactor the authentication flow"
+```
+
+### 🕸️ Knowledge Graph Browser (View)
+Explore your code visually. Launch an interactive local web UI to traverse your project's dependency graph, find symbols, and manage your AI tasks.
+*   **Visual Map:** Interactive D3.js force-directed graph available at `/graph`.
+*   **Relations:** Track CALLS, IMPORTS, and CONTAINS relationships cross-file.
+```bash
+codebookx view
+```
+
+### ❓ Technical Q&A (Ask)
+Knowledge Graph-backed Q&A for your codebase. Answers are saved automatically.
+```bash
+# Single question
+codebookx ask "How is the authentication handled in this project?"
+
+# Interactive chat mode (multi-turn, context carry-over)
+codebookx ask -c "Walk me through the data flow"
+
+# Save Q&A logs to a custom directory
+codebookx ask "What does run_ask do?" --dir ~/my-notes
+```
+*   **Auto-save:** Every Q&A and chat session is saved to `ask_history/` by default (`--dir` to override, or set `CODEBOOK_ASK_DIR` env var).
+*   **Chat mode (`-c`):** Multi-turn conversation with full context carry-over. Each turn is saved incrementally — no history lost on crash.
+
+---
+
+## 🛠️ Getting Started
+
+**1. Install**
+```bash
+pip install .
+```
+
+**2. Local LLM Setup**
+Codebase-X is designed to work with **LM Studio**, **Ollama**, or any OpenAI-compatible local server. Ensure your server is running.
+
+**3. Initial Analysis**
+Scan your repository to build the Knowledge Graph:
+```bash
+codebookx analyze
+```
+
+---
+
+## 🔒 Privacy & Performance
+*   **100% Offline:** Your code never leaves your machine. No cloud APIs, no subscriptions.
+*   **Persistent Indexing:** Uses a lightning-fast SQLite-backed Knowledge Graph with hash-based caching.
+*   **Multi-Language:** Deep support for Python, TypeScript, JavaScript, and more.
+
+---
+
+## 📄 License
+Codebase-X is released under the MIT License.

codebookx-3.0.0/codebookx/__init__.py

@@ -0,0 +1 @@
+__version__ = "3.0.0"

codebookx-3.0.0/codebookx/cli.py

@@ -0,0 +1,85 @@
+import argparse
+import sys
+from pathlib import Path
+from .core import run_generate, run_analyze, run_decompose, run_enhance, run_ask, run_ask_chat
+from .webapp.app import run_server
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="codebookx",
+        description="Codebase-X: Evolution of Codebook for offline code comprehension."
+    )
+    
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # Generate (Classic Codebook)
+    gen_parser = subparsers.add_parser("generate", help="Generate classic CODEBASE_BOOK.md")
+    gen_parser.add_argument("target_dir", nargs="?", default=".", help="Directory to scan")
+    gen_parser.add_argument("--url", help="LM Studio base URL")
+    gen_parser.add_argument("--model", help="Model name")
+    gen_parser.add_argument("--output", help="Output file path")
+    gen_parser.add_argument("--prompt-lang", help="Language for explanations")
+    gen_parser.add_argument("--file", help="Annotate single file only")
+
+    # Analyze (PCTF)
+    analyze_parser = subparsers.add_parser("analyze", help="Run PCTF Codebase Teardown")
+    analyze_parser.add_argument("target_dir", nargs="?", default=".", help="Directory to scan")
+    analyze_parser.add_argument("--force", action="store_true", help="Force re-analysis")
+
+    # Decompose (AATD)
+    decompose_parser = subparsers.add_parser("decompose", help="Run AATD Feature Decomposition")
+    decompose_parser.add_argument("feature", help="Feature description to decompose")
+    decompose_parser.add_argument("target_dir", nargs="?", default=".", help="Directory to scan")
+    decompose_parser.add_argument("--deep", action="store_true", help="Use deep context (repomix)")
+
+    # Enhance (New: Prompt Enhancement)
+    enhance_parser = subparsers.add_parser("enhance", help="Enhance a prompt with codebase context (requires: codebook analyze first)")
+    enhance_parser.add_argument("feature", help="Feature description to enhance")
+    enhance_parser.add_argument("target_dir", nargs="?", default=".", help="Directory to scan")
+
+    # Ask
+    ask_parser = subparsers.add_parser("ask", help="Ask a question about the codebase (requires: codebook analyze first)")
+    ask_parser.add_argument("question", help="The question to ask about your codebase")
+    ask_parser.add_argument("target_dir", nargs="?", default=".", help="Directory to scan")
+    ask_parser.add_argument("--dir", default=None,
+        help="Directory to save Q&A log (default: $CODEBOOK_ASK_DIR or ./ask_history)")
+    ask_parser.add_argument("-c", "--chat", action="store_true",
+        help="Interactive chat mode (multi-turn, context carry-over) (requires: codebook analyze first)")
+
+    # View
+    view_parser = subparsers.add_parser("view", help="Launch local Knowledge Graph web UI")
+    view_parser.add_argument("target_dir", nargs="?", default=".", help="Directory to scan")
+    view_parser.add_argument("--port", type=int, default=8050, help="Port to run the UI on")
+
+    # Backward compatibility: Intercept sys.argv
+    if len(sys.argv) > 1 and not sys.argv[1].startswith("-") and sys.argv[1] not in ["generate", "analyze", "decompose", "ask", "enhance", "view", "-h", "--help"]:
+        sys.argv.insert(1, "generate")
+    elif len(sys.argv) == 1:
+        sys.argv.append("generate")
+
+    args = parser.parse_args()
+
+    if args.command == "generate":
+        run_generate(args)
+    elif args.command == "analyze":
+        run_analyze(args)
+    elif args.command == "decompose":
+        run_decompose(args)
+    elif args.command == "enhance":
+        run_enhance(args)
+    elif args.command == "ask":
+        if getattr(args, "chat", False):
+            run_ask_chat(args)
+        else:
+            run_ask(args)
+    elif args.command == "view":
+        root = Path(args.target_dir or ".").resolve()
+        db_path = root / ".codebook_cache.db"
+        print(f"Starting local UI on http://localhost:{args.port}...")
+        print(f"Using database: {db_path}")
+        run_server(port=args.port, db_path=str(db_path))
+    else:
+        parser.print_help()
+
+if __name__ == "__main__":
+    main()