dot-context 0.1.0a1__tar.gz

dot_context-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dot Contributors
+
+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.

dot_context-0.1.0a1/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: dot-context
+Version: 0.1.0a1
+Summary: Dot — a local-first AI context memory daemon. Stop re-explaining your codebase to every AI tool.
+Author: Dot Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/aryanp-spektra/dot-context-engine
+Keywords: ai,context,memory,daemon,copilot,claude,embeddings
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12
+Requires-Dist: fastapi>=0.110
+Requires-Dist: uvicorn[standard]>=0.29
+Requires-Dist: watchdog>=4.0
+Requires-Dist: GitPython>=3.1
+Requires-Dist: SQLAlchemy>=2.0
+Requires-Dist: APScheduler>=3.10
+Requires-Dist: pydantic>=2.6
+Requires-Dist: httpx>=0.27
+Requires-Dist: rich>=13.7
+Provides-Extra: ml
+Requires-Dist: chromadb>=0.5; extra == "ml"
+Requires-Dist: sentence-transformers>=2.7; extra == "ml"
+Provides-Extra: treesitter
+Requires-Dist: tree-sitter>=0.21; extra == "treesitter"
+Requires-Dist: tree-sitter-language-pack>=0.4; extra == "treesitter"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.9; extra == "dev"
+Provides-Extra: all
+Requires-Dist: dot-context[dev,ml,treesitter]; extra == "all"
+Dynamic: license-file
+
+# ● dot
+
+**A local-first AI context memory daemon.** Stop re-explaining your codebase to every AI tool.
+
+Every AI tool starts from zero: you explain your architecture to Claude Code, then again
+to Copilot, then again in a new chat. Dot ends that. It runs silently in the background,
+builds a deep understanding of your codebase and the decisions behind it, and serves the
+right context to any AI tool through a local REST API.
+
+**Local. Private. Model-agnostic. Open source.** No code leaves your machine — embeddings
+are generated locally with sentence-transformers, storage is SQLite + ChromaDB on disk.
+
+## How it works
+
+```
+ filesystem ──▶ watcher ──▶ AST parser ──▶ semantic chunker ──▶ local embeddings
+ git history ──▶ decision miner ──────────────────────────────▶ ┌─────────────┐
+ AI chats ────▶ decision capture ─────────────────────────────▶ │ SQLite +    │
+                                                                │ ChromaDB    │
+        any AI tool ◀── /context (ranked, budgeted, formatted) ◀┴─────────────┘
+```
+
+- **dot-indexer** chunks code by function/class (not fixed token windows), extracts
+  docstrings, imports, and TODO/`decided to…` comments, and embeds everything locally.
+- **dot-memory** mines architectural decisions from commit messages and conversations,
+  with a forgetting curve — stale memories decay, frequently used ones are reinforced.
+- **dot-context** assembles context ranked by semantic similarity, file proximity,
+  recency, and edit frequency, fills a token budget greedily, and formats it for the
+  consumer (Claude XML, concise Copilot, markdown, or raw JSON).
+
+## Quick start
+
+> Not on PyPI yet — install from source. Full walkthrough with test
+> experiments: [docs/getting-started.md](docs/getting-started.md).
+> Deep technical internals: [docs/internals.md](docs/internals.md)
+> (prerequisites taught from zero in [docs/foundations.md](docs/foundations.md)).
+
+```bash
+git clone https://github.com/aryanp-spektra/dot-context-engine.git
+cd dot-context-engine && pip install -e ".[ml]"   # or ".[dev]" for the light build
+
+cd your-project
+dot init                          # index the project, wire up git + Claude Code hooks
+dot daemon start                  # keep watching in the background
+
+dot ask "how does auth middleware work?"
+dot inject "refactoring the billing module" --fmt claude | pbcopy
+dot status
+dot dashboard                     # web UI at http://localhost:7337/ui
+```
+
+### CLI
+
+| command | what it does |
+|---|---|
+| `dot init` | initialize Dot in a project (+ git hook, CLAUDE.md, Claude Code hook) |
+| `dot status` | what Dot knows about the current project |
+| `dot ask "…"` | query your codebase in natural language |
+| `dot inject [query]` | print assembled context — pipe it anywhere |
+| `dot memory list/add/export/delete` | browse and manage captured decisions |
+| `dot sync` | force re-index |
+| `dot forget "pattern"` | remove memories matching a pattern |
+| `dot dashboard` | open the web UI |
+| `dot daemon run/start/stop/install-service` | control the daemon (launchd/systemd) |
+
+### REST API (localhost:7337)
+
+```
+GET  /status                 daemon health + project stats
+GET  /context?query=&file=&fmt=claude|copilot|markdown|raw
+POST /memory                 capture a decision        GET /memory   browse
+POST /memory/conversation    extract decisions from an AI transcript
+DELETE /memory/{id}          forget
+GET  /graph                  dependency graph JSON
+POST /ask                    natural-language codebase query
+POST /sync                   force re-index
+```
+
+## Integrations
+
+- **Claude Code** — `dot init` adds a CLAUDE.md section and a SessionStart hook that
+  injects context at the start of every session.
+- **VS Code / Copilot** — the [extension](vscode-extension/) shows "what Dot knows about
+  this file" in a sidebar, registers Dot as a Language Model tool for Copilot Chat
+  (`#dotContext`), and offers one-click decision capture.
+- **Anything else** — `curl localhost:7337/context?query=...&fmt=raw`.
+
+## Development
+
+```bash
+make install     # editable install with dev extras
+make test        # pytest
+make lint        # ruff
+make dashboard   # build the web UI into dashboard/dist (served at /ui)
+make extension   # compile the VS Code extension
+```
+
+The ML stack (`chromadb`, `sentence-transformers`) and tree-sitter are **optional
+extras** — without them Dot degrades to a deterministic hashing embedder, SQLite
+brute-force vector search, and heuristic parsing, so the full pipeline still works
+(and tests run) on any machine.
+
+See [docs/getting-started.md](docs/getting-started.md) for the full
+walkthrough and test experiments, [docs/internals.md](docs/internals.md)
+for the complete technical deep dive (architecture, algorithms, math, and
+trade-offs), and [docs/integrations.md](docs/integrations.md) for tool wiring.
+
+## License
+
+MIT

dot_context-0.1.0a1/README.md

@@ -0,0 +1,110 @@
+# ● dot
+
+**A local-first AI context memory daemon.** Stop re-explaining your codebase to every AI tool.
+
+Every AI tool starts from zero: you explain your architecture to Claude Code, then again
+to Copilot, then again in a new chat. Dot ends that. It runs silently in the background,
+builds a deep understanding of your codebase and the decisions behind it, and serves the
+right context to any AI tool through a local REST API.
+
+**Local. Private. Model-agnostic. Open source.** No code leaves your machine — embeddings
+are generated locally with sentence-transformers, storage is SQLite + ChromaDB on disk.
+
+## How it works
+
+```
+ filesystem ──▶ watcher ──▶ AST parser ──▶ semantic chunker ──▶ local embeddings
+ git history ──▶ decision miner ──────────────────────────────▶ ┌─────────────┐
+ AI chats ────▶ decision capture ─────────────────────────────▶ │ SQLite +    │
+                                                                │ ChromaDB    │
+        any AI tool ◀── /context (ranked, budgeted, formatted) ◀┴─────────────┘
+```
+
+- **dot-indexer** chunks code by function/class (not fixed token windows), extracts
+  docstrings, imports, and TODO/`decided to…` comments, and embeds everything locally.
+- **dot-memory** mines architectural decisions from commit messages and conversations,
+  with a forgetting curve — stale memories decay, frequently used ones are reinforced.
+- **dot-context** assembles context ranked by semantic similarity, file proximity,
+  recency, and edit frequency, fills a token budget greedily, and formats it for the
+  consumer (Claude XML, concise Copilot, markdown, or raw JSON).
+
+## Quick start
+
+> Not on PyPI yet — install from source. Full walkthrough with test
+> experiments: [docs/getting-started.md](docs/getting-started.md).
+> Deep technical internals: [docs/internals.md](docs/internals.md)
+> (prerequisites taught from zero in [docs/foundations.md](docs/foundations.md)).
+
+```bash
+git clone https://github.com/aryanp-spektra/dot-context-engine.git
+cd dot-context-engine && pip install -e ".[ml]"   # or ".[dev]" for the light build
+
+cd your-project
+dot init                          # index the project, wire up git + Claude Code hooks
+dot daemon start                  # keep watching in the background
+
+dot ask "how does auth middleware work?"
+dot inject "refactoring the billing module" --fmt claude | pbcopy
+dot status
+dot dashboard                     # web UI at http://localhost:7337/ui
+```
+
+### CLI
+
+| command | what it does |
+|---|---|
+| `dot init` | initialize Dot in a project (+ git hook, CLAUDE.md, Claude Code hook) |
+| `dot status` | what Dot knows about the current project |
+| `dot ask "…"` | query your codebase in natural language |
+| `dot inject [query]` | print assembled context — pipe it anywhere |
+| `dot memory list/add/export/delete` | browse and manage captured decisions |
+| `dot sync` | force re-index |
+| `dot forget "pattern"` | remove memories matching a pattern |
+| `dot dashboard` | open the web UI |
+| `dot daemon run/start/stop/install-service` | control the daemon (launchd/systemd) |
+
+### REST API (localhost:7337)
+
+```
+GET  /status                 daemon health + project stats
+GET  /context?query=&file=&fmt=claude|copilot|markdown|raw
+POST /memory                 capture a decision        GET /memory   browse
+POST /memory/conversation    extract decisions from an AI transcript
+DELETE /memory/{id}          forget
+GET  /graph                  dependency graph JSON
+POST /ask                    natural-language codebase query
+POST /sync                   force re-index
+```
+
+## Integrations
+
+- **Claude Code** — `dot init` adds a CLAUDE.md section and a SessionStart hook that
+  injects context at the start of every session.
+- **VS Code / Copilot** — the [extension](vscode-extension/) shows "what Dot knows about
+  this file" in a sidebar, registers Dot as a Language Model tool for Copilot Chat
+  (`#dotContext`), and offers one-click decision capture.
+- **Anything else** — `curl localhost:7337/context?query=...&fmt=raw`.
+
+## Development
+
+```bash
+make install     # editable install with dev extras
+make test        # pytest
+make lint        # ruff
+make dashboard   # build the web UI into dashboard/dist (served at /ui)
+make extension   # compile the VS Code extension
+```
+
+The ML stack (`chromadb`, `sentence-transformers`) and tree-sitter are **optional
+extras** — without them Dot degrades to a deterministic hashing embedder, SQLite
+brute-force vector search, and heuristic parsing, so the full pipeline still works
+(and tests run) on any machine.
+
+See [docs/getting-started.md](docs/getting-started.md) for the full
+walkthrough and test experiments, [docs/internals.md](docs/internals.md)
+for the complete technical deep dive (architecture, algorithms, math, and
+trade-offs), and [docs/integrations.md](docs/integrations.md) for tool wiring.
+
+## License
+
+MIT

dot_context-0.1.0a1/dot/__init__.py

@@ -0,0 +1,10 @@
+"""Dot — a local-first AI context memory daemon.
+
+Dot watches your codebase, indexes it semantically, captures architectural
+decisions, and serves the right context to any AI tool via a local REST API.
+"""
+
+__version__ = "0.1.0"
+
+DEFAULT_PORT = 7337
+DEFAULT_HOST = "127.0.0.1"

dot_context-0.1.0a1/dot/api.py

@@ -0,0 +1,220 @@
+"""Local REST API, served on localhost:7337.
+
+Endpoints:
+    GET    /status         daemon health + project stats
+    GET    /context        assembled context for a file/query
+    POST   /memory         capture a decision/memory
+    GET    /memory         browse memories
+    DELETE /memory/{id}    forget a memory
+    GET    /graph          dependency graph as JSON
+    POST   /ask            natural-language query of the codebase
+    POST   /sync           force re-index
+    POST   /hooks/git/commit   git post-commit ping (installed by dot init)
+    GET    /ui             web dashboard (when dashboard/dist is built)
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from pathlib import Path
+from typing import TYPE_CHECKING, Literal
+
+from fastapi import FastAPI, HTTPException, Query, Response
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel, Field
+
+from dot import __version__
+from dot.context.formatter import FORMATS, context_to_dict, format_context
+
+if TYPE_CHECKING:
+    from dot.daemon import Daemon
+
+logger = logging.getLogger(__name__)
+
+
+class MemoryIn(BaseModel):
+    content: str = Field(min_length=3)
+    kind: Literal["decision", "rejected", "action_item", "note", "conversation"] = "note"
+    source: str = "api"
+    file_path: str = ""
+    tags: list[str] = []
+    confidence: float = Field(default=1.0, ge=0.0, le=1.0)
+    share: bool = False  # also append to dot-memories.jsonl for the team
+
+
+class ConversationIn(BaseModel):
+    transcript: str = Field(min_length=10)
+    source: str = "conversation"
+
+
+class AskIn(BaseModel):
+    question: str = Field(min_length=3)
+    current_file: str | None = None
+    fmt: str = "markdown"
+
+
+class SyncIn(BaseModel):
+    force: bool = False
+
+
+def create_app(daemon: Daemon) -> FastAPI:
+    app = FastAPI(
+        title="Dot",
+        version=__version__,
+        description="Local-first AI context memory daemon",
+    )
+    # The dashboard dev server (vite) runs on another port; same machine only.
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["http://localhost:5173", "http://127.0.0.1:5173"],
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    @app.get("/status")
+    def status() -> dict:
+        return daemon.status()
+
+    @app.get("/context")
+    def get_context(
+        query: str = "",
+        file: str | None = Query(default=None, description="current file path"),
+        fmt: str = Query(default="raw", description=f"one of {FORMATS}"),
+        token_budget: int | None = Query(default=None, ge=100, le=100_000),
+        profile: str | None = None,
+    ):
+        if fmt not in FORMATS:
+            raise HTTPException(422, f"fmt must be one of {FORMATS}")
+        context = daemon.assembler.assemble(
+            query=query, current_file=file, token_budget=token_budget, profile=profile
+        )
+        if fmt == "raw":
+            return context_to_dict(context)
+        return Response(
+            content=format_context(context, fmt),
+            media_type="text/plain; charset=utf-8",
+            headers={"x-dot-assembly-ms": f"{context.assembly_ms:.1f}"},
+        )
+
+    @app.post("/memory", status_code=201)
+    def add_memory(body: MemoryIn) -> dict:
+        memory = daemon.store.add_memory(
+            content=body.content,
+            kind=body.kind,
+            source=body.source,
+            file_path=body.file_path,
+            tags=body.tags,
+            confidence=body.confidence,
+        )
+        shared = False
+        if body.share:
+            from dot.memory.shared import export_memory
+
+            shared = export_memory(daemon.config, memory)
+        return {"id": memory.memory_id, "kind": memory.kind, "shared": shared}
+
+    @app.post("/memory/conversation", status_code=201)
+    def capture_conversation(body: ConversationIn) -> dict:
+        captured = daemon.decisions.capture_from_conversation(body.transcript, body.source)
+        return {"captured": len(captured), "ids": [memory.memory_id for memory in captured]}
+
+    @app.get("/memory")
+    def list_memories(
+        kind: str | None = None,
+        query: str | None = None,
+        limit: int = Query(default=50, ge=1, le=1000),
+    ) -> dict:
+        if query:
+            memories = daemon.store.query_memories(query, n=limit)
+        else:
+            memories = daemon.store.list_memories(kind=kind, limit=limit)
+        return {
+            "memories": [
+                {
+                    "id": memory.memory_id,
+                    "kind": memory.kind,
+                    "content": memory.content,
+                    "source": memory.source,
+                    "file_path": memory.file_path,
+                    "tags": memory.tags,
+                    "confidence": memory.confidence,
+                    "weight": round(memory.weight, 4),
+                    "created_at": memory.created_at.isoformat() if memory.created_at else None,
+                }
+                for memory in memories
+            ]
+        }
+
+    @app.get("/memory/export")
+    def export_memories() -> dict:
+        return {"project": daemon.config.project_name, "memories": daemon.store.export_memories()}
+
+    @app.delete("/memory/{memory_id}")
+    def delete_memory(memory_id: str) -> dict:
+        if not daemon.store.delete_memory(memory_id):
+            raise HTTPException(404, "memory not found")
+        return {"deleted": memory_id}
+
+    @app.get("/graph")
+    def graph() -> dict:
+        return daemon.store.dependency_graph()
+
+    @app.post("/ask")
+    def ask(body: AskIn):
+        """Natural-language query: returns the most relevant code + decisions.
+
+        Dot is model-agnostic and fully local — it retrieves and ranks; the
+        calling tool (Claude, Copilot, a script) does the generation.
+        """
+        context = daemon.assembler.assemble(body.question, current_file=body.current_file)
+        if body.fmt == "raw":
+            return context_to_dict(context)
+        if body.fmt not in FORMATS:
+            raise HTTPException(422, f"fmt must be one of {FORMATS}")
+        return Response(
+            content=format_context(context, body.fmt),
+            media_type="text/plain; charset=utf-8",
+        )
+
+    @app.post("/sync", status_code=202)
+    def sync(body: SyncIn | None = None) -> dict:
+        force = bool(body and body.force)
+        thread = threading.Thread(
+            target=daemon.full_sync, kwargs={"force": force}, daemon=True, name="dot-api-sync"
+        )
+        thread.start()
+        return {"status": "sync started", "force": force}
+
+    @app.post("/conversations/scan", status_code=200)
+    def scan_conversations() -> dict:
+        """Incrementally scan Claude Code transcripts and capture decisions.
+
+        Unlike :http:post:`/sync` (which fires a heavy re-index in the
+        background), this runs synchronously: a conversation scan is cheap
+        (incremental byte-offset reads of local JSONL) so the caller gets the
+        real counts back immediately. Returns ``{"enabled": False, ...}`` when
+        capture is off rather than erroring, so clients can probe safely.
+        """
+        return daemon.scan_conversations()
+
+    @app.post("/hooks/git/commit")
+    def git_commit_hook() -> dict:
+        captured = daemon.decisions.mine_git(max_count=5)
+        return {"decisions_captured": captured}
+
+    # Serve the built dashboard at /ui when present.
+    dist = Path(__file__).resolve().parent.parent / "dashboard" / "dist"
+    if dist.is_dir():
+        from fastapi.staticfiles import StaticFiles
+
+        app.mount("/ui", StaticFiles(directory=str(dist), html=True), name="dashboard")
+    else:
+
+        @app.get("/ui")
+        def ui_placeholder() -> dict:
+            return {
+                "message": "dashboard not built — run `npm install && npm run build` in dashboard/",
+            }
+
+    return app