codebookx 3.0.0__py3-none-any.whl

codebookx/llm.py

@@ -0,0 +1,73 @@
+import json
+import re
+import requests
+from typing import Optional, Tuple
+from tqdm import tqdm
+
+def check_server(base_url: str) -> tuple[bool, Optional[str]]:
+    """Check if an LLM server is running and return (is_running, model_name)."""
+
+    try:
+        r = requests.get(f"{base_url.rstrip('/')}/models", timeout=3)
+        if r.status_code == 200:
+            data = r.json()
+            models = data.get("data", [])
+            if models:
+                model_name = models[0].get("id", "unknown")
+                return True, model_name
+            return True, None
+    except Exception:
+        pass
+    return False, None
+
+def strip_think_tokens(text: str) -> str:
+    """Remove <think>...</think> blocks (used by reasoning models like DeepSeek-R1)."""
+    return re.sub(r"<think>.*?</think>", "", text, flags=re.DOTALL).strip()
+
+def stream_chat_completion(url: str, model: str, messages: list, temperature: float = 0.3, max_tokens: int = 4096) -> str:
+    """Send messages to LM Studio and stream the response, returning the full text."""
+    try:
+        response = requests.post(
+            f"{url.rstrip('/')}/chat/completions",
+            json={
+                "model": model,
+                "messages": messages,
+                "temperature": temperature,
+                "max_tokens": max_tokens,
+                "stream": True,
+            },
+            stream=True,
+            timeout=(10, 60),
+        )
+        response.raise_for_status()
+
+        full_text_chunks = []
+        content_type = response.headers.get("content-type", "")
+
+        if "application/json" in content_type:
+            data = response.json()
+            full_text = data["choices"][0]["message"]["content"]
+            print(full_text)
+            return strip_think_tokens(full_text)
+        else:
+            for line in response.iter_lines():
+                if not line:
+                    continue
+                line = line.decode("utf-8") if isinstance(line, bytes) else line
+                if line.startswith("data: "):
+                    line = line[6:]
+                if line == "[DONE]":
+                    break
+                try:
+                    chunk = json.loads(line)
+                    delta = chunk["choices"][0]["delta"].get("content", "")
+                    if delta:
+                        print(delta, end="", flush=True)
+                        full_text_chunks.append(delta)
+                except (json.JSONDecodeError, KeyError, IndexError):
+                    continue
+        print()
+        return strip_think_tokens("".join(full_text_chunks))
+    except Exception as e:
+        print(f"\n[Error: {e}]")
+        return f"[Error: {e}]"

codebookx/prompts.py

@@ -0,0 +1,43 @@
+PCTF_SYSTEM_PROMPT = """You are a Senior Software Architect. You are given details about a codebase and must explain it to a product manager who has zero technical knowledge. Use simple language, real-world analogies (like a restaurant kitchen or a library), and avoid jargon.
+
+You MUST output your response exactly in the following Markdown format:
+
+# Codebase Teardown
+
+## Elevator Pitch
+[2-3 sentences explaining what this project does and why it exists]
+
+## Architecture Blueprint
+| Folder | Purpose |
+|--------|---------|
+| [folder path] | [plain English purpose] |
+
+## Core Features
+- **[Feature 1]**: [Brief description]
+- **[Feature 2]**: [Brief description]
+
+## High-Level Architecture
+[A few paragraphs describing how the system is structured, layered, or how data flows through it, using analogies.]
+"""
+
+AATD_SYSTEM_PROMPT = """You are a Senior Developer breaking down a feature for a junior AI assistant. 
+You MUST output a JSON array of tasks. Each task object MUST have:
+- task_id: number
+- title: short string
+- purpose: string
+- file_path_hint: string
+- function_or_component: string
+- input_output: string
+- constraints: string
+- relevant_context: string
+- copy_paste_prompt: a complete self-contained prompt for the AI to execute only this task.
+"""
+
+ENHANCE_SYSTEM_PROMPT = """You are an expert Prompt Engineer and Senior Architect. 
+Your goal is to take a simple feature request and turn it into a high-context, detailed prompt for an AI coding tool like Cursor or Copilot.
+Incorporate file paths, symbol names, and architectural constraints provided in the context.
+"""
+
+QA_SYSTEM_PROMPT = """You are a senior engineer who knows this codebase inside out. 
+Answer the user's question concisely. Reference specific files and symbols when relevant.
+If you're not sure, say so — don't make things up."""

codebookx/webapp/app.py

@@ -0,0 +1,153 @@
+from flask import Flask, jsonify, request, current_app, send_from_directory
+from pathlib import Path
+import sqlite3
+import os
+
+app = Flask(__name__)
+
+@app.route("/static/<path:filename>")
+def static_files(filename):
+    return send_from_directory(
+        os.path.join(os.path.dirname(__file__), "static"), filename
+    )
+
+@app.route("/graph")
+def graph_view():
+    return """<!DOCTYPE html>
+<html lang="en">
+<head><meta charset="UTF-8"><title>Codebase Knowledge Graph</title>
+<style>
+  body { margin: 0; font-family: sans-serif; overflow: hidden; }
+  #legend { position: absolute; top: 10px; left: 10px; background: rgba(255,255,255,0.9); padding: 8px 14px; border-radius: 6px; font-size: 12px; }
+  #legend span { display: inline-block; width: 12px; height: 12px; border-radius: 50%; margin-right: 4px; }
+  .link { stroke: #999; stroke-opacity: 0.5; }
+  .link.CALLS { stroke: #4caf50; }
+  .link.IMPORTS { stroke: #2196f3; }
+  .link.CONTAINS { stroke: #ff9800; }
+</style>
+</head>
+<body>
+<div id="legend">
+  <div><span style="background:#4caf50"></span> CALLS</div>
+  <div><span style="background:#2196f3"></span> IMPORTS</div>
+  <div><span style="background:#ff9800"></span> CONTAINS</div>
+</div>
+<div id="graph"></div>
+<script src="/static/d3.min.js"></script>
+<script>
+const W = window.innerWidth, H = window.innerHeight;
+const svg = d3.select("#graph").append("svg").attr("width", W).attr("height", H);
+const defs = svg.append("defs");
+defs.append("marker").attr("id", "arrow").attr("viewBox", "0 -5 10 10").attr("refX", 20).attr("refY", 0)
+  .append("path").attr("d", "M0,-5L10,0L0,5").attr("fill", "#999");
+
+Promise.all([
+  fetch("/api/symbols?limit=200").then(r => r.json()),
+  fetch("/api/relations").then(r => r.json())
+]).then(([data, relations]) => {
+  const symbols = data.symbols;
+  const total = data.total;
+  if (total > symbols.length) {
+    d3.select("#legend").append("p").attr("style", "color:red;font-weight:bold;margin-top:8px")
+      .text(`⚠️ Showing ${symbols.length} of ${total} symbols`);
+  }
+  const nodes = symbols.map(s => ({id: s.id, name: s.name}));
+  const nodeIds = new Set(nodes.map(n => n.id));
+  const links = relations.filter(r => nodeIds.has(r.from_id) && nodeIds.has(r.to_id))
+    .map(r => ({ source: r.from_id, target: r.to_id, type: r.type }));
+  const sim = d3.forceSimulation(nodes)
+    .force("link", d3.forceLink(links).id(d => d.id).distance(120))
+    .force("charge", d3.forceManyBody().strength(-300))
+    .force("center", d3.forceCenter(W/2, H/2));
+  const link = svg.selectAll(".link").data(links).join("line")
+    .attr("class", d => `link ${d.type}`)
+    .attr("marker-end", "url(#arrow)");
+  const node = svg.selectAll(".node").data(nodes).join("g").attr("class", "node")
+    .call(d3.drag().on("start", (e,d) => { if(!e.active) sim.alphaTarget(0.3).restart(); d.fx = d.x; d.fy = d.y; })
+      .on("drag", (e,d) => { d.fx = e.x; d.fy = e.y; })
+      .on("end", (e,d) => { if(!e.active) sim.alphaTarget(0); d.fx = null; d.fy = null; }));
+  node.append("circle").attr("r", 7).attr("fill", "#69b3a2").attr("stroke", "#333").attr("stroke-width", 1.5);
+  node.append("text").attr("dx", 12).attr("dy", 4).style("font-size", "11px").text(d => d.name);
+  sim.on("tick", () => {
+    link.attr("x1", d => d.source.x).attr("y1", d => d.source.y)
+        .attr("x2", d => d.target.x).attr("y2", d => d.target.y);
+    node.attr("transform", d => `translate(${d.x},${d.y})`);
+  });
+});
+</script>
+</body></html>"""
+
+def get_db_connection():
+    db_path = current_app.config.get('DB_PATH')
+    if not db_path:
+        db_path = Path(".codebook_cache.db").resolve()
+    conn = sqlite3.connect(db_path)
+    conn.row_factory = sqlite3.Row
+    return conn
+
+@app.route("/")
+def index():
+    db_path = current_app.config.get('DB_PATH', 'Not set (using default)')
+    rows_html = ""
+    try:
+        conn = get_db_connection()
+        relations = conn.execute("""
+            SELECT s1.name as source_name, r.type, s2.name as target_name
+            FROM relations r
+            JOIN symbols s1 ON r.source_id = s1.id
+            JOIN symbols s2 ON r.target_id = s2.id
+            LIMIT 100
+        """).fetchall()
+        conn.close()
+        for r in relations:
+            d = dict(r)
+            rows_html += f"<tr><td>{d['source_name']}</td><td>{d['type']}</td><td>{d['target_name']}</td></tr>\n"
+    except Exception:
+        rows_html = "<tr><td colspan='3'>No relations found. Run 'codebookx analyze' first.</td></tr>"
+    
+    return f"""<h1>Codebase-X Knowledge Graph Viewer</h1>
+<p>Database: {db_path}</p>
+<p>API endpoints: /api/files, /api/symbols, /api/relations</p>
+<p>🚀 <strong><a href="/graph">View Interactive Knowledge Graph</a></strong></p>
+<h2>🔗 Relations</h2>
+<table border="1"><tr><th>Source Symbol</th><th>Type</th><th>Target Symbol</th></tr>
+{rows_html}</table>
+<p>💡 <strong>CONTAINS</strong> means a file includes a symbol. 
+<strong>CALLS</strong> and <strong>IMPORTS</strong> show cross-file dependencies.</p>"""
+
+@app.route("/api/relations")
+def get_relations():
+    try:
+        conn = get_db_connection()
+        relations = conn.execute("SELECT * FROM relations LIMIT 500").fetchall()
+        conn.close()
+        return jsonify([dict(r) for r in relations])
+    except Exception as e:
+        return jsonify({"error": str(e)}), 500
+
+@app.route("/api/files")
+def get_files():
+    try:
+        conn = get_db_connection()
+        files = conn.execute("SELECT * FROM files").fetchall()
+        conn.close()
+        return jsonify([dict(f) for f in files])
+    except Exception as e:
+        return jsonify({"error": str(e)}), 500
+
+@app.route("/api/symbols")
+def get_symbols():
+    try:
+        limit = request.args.get("limit", 100, type=int)
+        limit = min(limit, 200)
+        conn = get_db_connection()
+        total = conn.execute("SELECT COUNT(*) FROM symbols").fetchone()[0]
+        symbols = conn.execute("SELECT * FROM symbols LIMIT ?", (limit,)).fetchall()
+        conn.close()
+        return jsonify({"symbols": [dict(s) for s in symbols], "total": total})
+    except Exception as e:
+        return jsonify({"error": str(e)}), 500
+
+def run_server(port=8050, db_path=".codebook_cache.db"):
+    app.config['DB_PATH'] = Path(db_path).resolve()
+    app.run(host="127.0.0.1", port=port)

codebookx-3.0.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,17 @@
+codebookx/__init__.py,sha256=EPmgXOdWKks5S__ZMH7Nu6xpAeVrZpfxaFy4pykuyeI,22
+codebookx/cli.py,sha256=hV-9ojUJSgP6pqqNwVryo4iWgSU79biE6pcK_lQdQ4M,4098
+codebookx/core.py,sha256=yIK2RZJ7fEZq0KFz2u05ZaIYKIHsZOObAIT3Wolk6sI,21756
+codebookx/llm.py,sha256=IsvZ4BRv0crS0iMusynMuoOqYBGb3ZpPZe1Jkz5LcVo,2685
+codebookx/prompts.py,sha256=hiNh2NZ079n-vAB0bITOrclN9VS2GNXqijsEBMPk9A8,1824
+codebookx/engine/graph.py,sha256=aI496ZO9WJQeB5a_Ox-T7WNZTE53RaP5_Q1xiYvSeeI,5921
+codebookx/engine/indexer.py,sha256=E8r-hcmKoZ4veXP7TGIi-jZxw-U1N1P_W_Vr4cE6OoA,5584
+codebookx/engine/parser.py,sha256=sxd2tFiNA_mBB8XQS3sFkUbMC8dvOXHPgDAGjDCsXws,12548
+codebookx/engine/vendor/claude_mem_lite.py,sha256=IUFxGF_2VmmoYJn6i9NH3YevBDJ5zTSXWLHhgxh57tU,1655
+codebookx/engine/vendor/repomix_lite.py,sha256=84he25PLhK0qa7gpX8y2mjnwk7-S4H6laGavDAYxa7o,1235
+codebookx/webapp/app.py,sha256=LpED173MMldRrh1iVBCF1OtQ983irsOFQ3P2h8bnVs4,6266
+codebookx-3.0.0.dist-info/licenses/NOTICE.md,sha256=_uMKd-2xfoO8XRxtunU0jvlJx1BYlPjAsn_oHT9gKew,775
+codebookx-3.0.0.dist-info/METADATA,sha256=mRT8BaA_zOkwkSPqUYQiwIDjJEJtzzNoiQvbuXnWIDE,4506
+codebookx-3.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+codebookx-3.0.0.dist-info/entry_points.txt,sha256=A6ijqPE8joUoN_a45-J0zZ2n86JpjnlVDoI5G70Couw,79
+codebookx-3.0.0.dist-info/top_level.txt,sha256=su_fZ6tEsa4GWjZFsinfGAqXtrXlU0YHVNnpUNaxh2E,10
+codebookx-3.0.0.dist-info/RECORD,,

codebookx-3.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

codebookx-3.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+codebook = codebookx.cli:main
+codebookx = codebookx.cli:main

codebookx-3.0.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+codebookx