degraph 1.0.0__tar.gz

degraph-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rahul Kumar
+
+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.

degraph-1.0.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: degraph
+Version: 1.0.0
+Summary: Decision-Evidence Graph: traceable, challengeable, temporal decision provenance for AI agents
+Project-URL: Homepage, https://github.com/rkstu/deg
+Project-URL: Repository, https://github.com/rkstu/deg
+Project-URL: Issues, https://github.com/rkstu/deg/issues
+Author-email: Rahul Kumar <rahulkc.dev@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: adr,ai-agents,architecture-decision-records,claude,context,cursor,decisions,knowledge-graph,mcp,memory,provenance,session-memory,temporal
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: all
+Requires-Dist: deg[graph,mcp,search]; extra == 'all'
+Provides-Extra: graph
+Requires-Dist: networkx>=3.0; extra == 'graph'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Provides-Extra: search
+Requires-Dist: faiss-cpu>=1.7; extra == 'search'
+Requires-Dist: numpy>=1.24; extra == 'search'
+Requires-Dist: sentence-transformers>=2.2; extra == 'search'
+Description-Content-Type: text/markdown
+
+# DEG — Decision-Evidence Graph
+
+Persistent decision memory for AI agents. DEG records WHY decisions were made, WHAT alternatives were rejected, and WHEN to reconsider — across sessions, with full provenance. It integrates as a Claude Code skill (via MCP + hooks) so decisions are captured and queried automatically, with zero manual documentation maintenance.
+
+## Quick Start
+
+```bash
+pip install deg[mcp]
+cd my-project
+deg init --goal "Build a fraud detector" --phase "Research"
+deg setup
+# Restart Claude Code — DEG is now active
+```
+
+## What Happens After Setup
+
+Claude Code will automatically:
+
+- Record decisions with evidence, alternatives, and reconsider-if triggers
+- Surface stale decisions when triggers fire (time-based, metric drift, dependency changes)
+- Trace provenance chains when you ask "why did we choose X?"
+- Challenge decisions when new evidence contradicts them
+- Hand off session state so the next session starts with full context
+
+You don't invoke DEG manually. It runs reflexively via hooks and MCP tools.
+
+## Core Operations
+
+| Operation | Description |
+|-----------|-------------|
+| `status()` | Project state, stale alerts, and next actions |
+| `decide()` | Record a decision with evidence, alternatives, and reconsider_if |
+| `evidence()` | Record a finding with source, confidence, and temporal validity |
+| `search(query)` | Hybrid semantic + keyword + graph-walk retrieval |
+| `trace(id)` | Full upstream provenance chain (BFS) |
+| `challenge(id)` | Check validity, triggers, evidence health, and alternatives |
+| `impact(id)` | Downstream cascade — all affected nodes |
+| `continue_research(id)` | Next searches, open questions, and look_for directives |
+| `close_session()` | Save state for the next session |
+| `compile()` | Incremental YAML-to-JSONL+FAISS compilation |
+
+## CLI Commands
+
+```
+deg init          Initialize a DEG project (creates decisions/, evidence/, .deg/)
+deg setup         Configure Claude Code skill (CLAUDE.md + MCP + hooks)
+deg status        Show project state and stale alerts
+deg decide        Record a decision interactively
+deg evidence      Record evidence interactively
+deg search        Search the decision graph
+deg trace         Trace provenance for a node
+deg challenge     Challenge a decision's validity
+deg impact        Show downstream impact of a node
+deg continue      Show next steps for a research thread
+deg close         Close session and save state
+deg compile       Force recompilation of all sources
+deg export        Export graph as JSON/DOT/Mermaid
+deg serve         Start MCP server (for non-Claude clients)
+```
+
+## MCP Tools
+
+DEG exposes 9 tools via MCP for any compatible AI client:
+
+| Tool | Purpose |
+|------|---------|
+| `deg_status` | Get project state and alerts |
+| `deg_decide` | Record a decision |
+| `deg_evidence` | Record evidence |
+| `deg_search` | Query the decision graph |
+| `deg_trace` | Get provenance chain |
+| `deg_challenge` | Challenge a decision |
+| `deg_impact` | Get downstream cascade |
+| `deg_continue_research` | Get next research steps |
+| `deg_close_session` | Save session state |
+
+## How It Works
+
+```
+decisions/         YAML frontmatter markdown (human-readable, git-friendly)
+evidence/          Same format for findings, measurements, sources
+.deg/
+  index.jsonl      Compiled node index
+  graph.jsonl      Edge list
+  embeddings.faiss IDMap2(FlatL2) vector index
+  state.yaml       Session handoff state
+```
+
+Architecture:
+
+1. Decisions and evidence are stored as markdown files with YAML frontmatter
+2. `deg compile` incrementally hashes and indexes them into `.deg/` (content-hash dedup, ~100x embedding savings)
+3. Claude accesses the graph via MCP tools during conversation
+4. Hooks auto-fire `deg status` on session start and `deg close` on session end
+5. Retrieval is hybrid: semantic (FAISS) + keyword (BM25-like) + graph walk (Personalized PageRank)
+6. DEG itself makes zero LLM calls — all intelligence comes from the host agent
+
+Latency: status 0.6ms, decide/evidence 22ms, search 6ms, trace/impact <1ms.
+
+## Ecosystem
+
+DEG handles decision provenance. For full agent context, pair with:
+
+- **Understand-Anything** — code structure graph (replaces architecture docs)
+- **TinyFish** — web research with source tracking
+- **Probe-Ratchet** — deterministic experiment loops with automatic evidence capture
+- **ML-Intern** — deep literature research agent (feeds evidence into DEG)
+
+Together with DEG, these replace all manually-maintained .md files except a minimal CLAUDE.md.
+
+## Install Options
+
+```bash
+pip install deg[mcp]    # Recommended: MCP server + CLI + hooks
+pip install deg         # Minimal: CLI only, no MCP
+pip install deg[all]    # Full: adds local FAISS semantic search
+```
+
+## Requirements
+
+- Python 3.10+
+- Claude Code (or any MCP-compatible client)
+- No API keys needed — DEG makes zero external calls
+
+## License
+
+MIT

degraph-1.0.0/README.md

@@ -0,0 +1,127 @@
+# DEG — Decision-Evidence Graph
+
+Persistent decision memory for AI agents. DEG records WHY decisions were made, WHAT alternatives were rejected, and WHEN to reconsider — across sessions, with full provenance. It integrates as a Claude Code skill (via MCP + hooks) so decisions are captured and queried automatically, with zero manual documentation maintenance.
+
+## Quick Start
+
+```bash
+pip install deg[mcp]
+cd my-project
+deg init --goal "Build a fraud detector" --phase "Research"
+deg setup
+# Restart Claude Code — DEG is now active
+```
+
+## What Happens After Setup
+
+Claude Code will automatically:
+
+- Record decisions with evidence, alternatives, and reconsider-if triggers
+- Surface stale decisions when triggers fire (time-based, metric drift, dependency changes)
+- Trace provenance chains when you ask "why did we choose X?"
+- Challenge decisions when new evidence contradicts them
+- Hand off session state so the next session starts with full context
+
+You don't invoke DEG manually. It runs reflexively via hooks and MCP tools.
+
+## Core Operations
+
+| Operation | Description |
+|-----------|-------------|
+| `status()` | Project state, stale alerts, and next actions |
+| `decide()` | Record a decision with evidence, alternatives, and reconsider_if |
+| `evidence()` | Record a finding with source, confidence, and temporal validity |
+| `search(query)` | Hybrid semantic + keyword + graph-walk retrieval |
+| `trace(id)` | Full upstream provenance chain (BFS) |
+| `challenge(id)` | Check validity, triggers, evidence health, and alternatives |
+| `impact(id)` | Downstream cascade — all affected nodes |
+| `continue_research(id)` | Next searches, open questions, and look_for directives |
+| `close_session()` | Save state for the next session |
+| `compile()` | Incremental YAML-to-JSONL+FAISS compilation |
+
+## CLI Commands
+
+```
+deg init          Initialize a DEG project (creates decisions/, evidence/, .deg/)
+deg setup         Configure Claude Code skill (CLAUDE.md + MCP + hooks)
+deg status        Show project state and stale alerts
+deg decide        Record a decision interactively
+deg evidence      Record evidence interactively
+deg search        Search the decision graph
+deg trace         Trace provenance for a node
+deg challenge     Challenge a decision's validity
+deg impact        Show downstream impact of a node
+deg continue      Show next steps for a research thread
+deg close         Close session and save state
+deg compile       Force recompilation of all sources
+deg export        Export graph as JSON/DOT/Mermaid
+deg serve         Start MCP server (for non-Claude clients)
+```
+
+## MCP Tools
+
+DEG exposes 9 tools via MCP for any compatible AI client:
+
+| Tool | Purpose |
+|------|---------|
+| `deg_status` | Get project state and alerts |
+| `deg_decide` | Record a decision |
+| `deg_evidence` | Record evidence |
+| `deg_search` | Query the decision graph |
+| `deg_trace` | Get provenance chain |
+| `deg_challenge` | Challenge a decision |
+| `deg_impact` | Get downstream cascade |
+| `deg_continue_research` | Get next research steps |
+| `deg_close_session` | Save session state |
+
+## How It Works
+
+```
+decisions/         YAML frontmatter markdown (human-readable, git-friendly)
+evidence/          Same format for findings, measurements, sources
+.deg/
+  index.jsonl      Compiled node index
+  graph.jsonl      Edge list
+  embeddings.faiss IDMap2(FlatL2) vector index
+  state.yaml       Session handoff state
+```
+
+Architecture:
+
+1. Decisions and evidence are stored as markdown files with YAML frontmatter
+2. `deg compile` incrementally hashes and indexes them into `.deg/` (content-hash dedup, ~100x embedding savings)
+3. Claude accesses the graph via MCP tools during conversation
+4. Hooks auto-fire `deg status` on session start and `deg close` on session end
+5. Retrieval is hybrid: semantic (FAISS) + keyword (BM25-like) + graph walk (Personalized PageRank)
+6. DEG itself makes zero LLM calls — all intelligence comes from the host agent
+
+Latency: status 0.6ms, decide/evidence 22ms, search 6ms, trace/impact <1ms.
+
+## Ecosystem
+
+DEG handles decision provenance. For full agent context, pair with:
+
+- **Understand-Anything** — code structure graph (replaces architecture docs)
+- **TinyFish** — web research with source tracking
+- **Probe-Ratchet** — deterministic experiment loops with automatic evidence capture
+- **ML-Intern** — deep literature research agent (feeds evidence into DEG)
+
+Together with DEG, these replace all manually-maintained .md files except a minimal CLAUDE.md.
+
+## Install Options
+
+```bash
+pip install deg[mcp]    # Recommended: MCP server + CLI + hooks
+pip install deg         # Minimal: CLI only, no MCP
+pip install deg[all]    # Full: adds local FAISS semantic search
+```
+
+## Requirements
+
+- Python 3.10+
+- Claude Code (or any MCP-compatible client)
+- No API keys needed — DEG makes zero external calls
+
+## License
+
+MIT

degraph-1.0.0/pyproject.toml

@@ -0,0 +1,64 @@
+[project]
+name = "degraph"
+version = "1.0.0"
+description = "Decision-Evidence Graph: traceable, challengeable, temporal decision provenance for AI agents"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{name = "Rahul Kumar", email = "rahulkc.dev@gmail.com"}]
+keywords = [
+    "decisions", "provenance", "ai-agents", "memory", "mcp",
+    "knowledge-graph", "architecture-decision-records", "adr",
+    "claude", "cursor", "context", "session-memory", "temporal",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Documentation",
+    "Topic :: Software Development :: Quality Assurance",
+    "Typing :: Typed",
+]
+
+dependencies = [
+    "pyyaml>=6.0",
+    "pydantic>=2.0",
+    "click>=8.0",
+]
+
+[project.optional-dependencies]
+search = [
+    "sentence-transformers>=2.2",
+    "faiss-cpu>=1.7",
+    "numpy>=1.24",
+]
+graph = [
+    "networkx>=3.0",
+]
+mcp = [
+    "mcp>=1.0",
+]
+all = ["deg[search,graph,mcp]"]
+
+[project.urls]
+Homepage = "https://github.com/rkstu/deg"
+Repository = "https://github.com/rkstu/deg"
+Issues = "https://github.com/rkstu/deg/issues"
+
+[project.scripts]
+deg = "deg.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/deg"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/deg/**", "README.md", "LICENSE"]

degraph-1.0.0/refs/Understand-Anything/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yuxiang Lin
+
+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.