agent-kg 0.7.0__tar.gz

agent_kg-0.7.0/LICENSE

@@ -0,0 +1,94 @@
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+**You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.**
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor's trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to the
+software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms or the URL for them above, as well as copies of
+any plain-text lines beginning with "Required Notice:" that the licensor provided
+with the software. For example:
+
+Required Notice: Copyright (c) 2026 Eric G. Suchanek, PhD
+
+## No Other Rights
+
+These terms do not imply any other licenses not expressly granted in this
+license.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you with
+a notice of your violation, and you cease all violation of this license no later
+than 30 days after you receive that notice, your licenses will be reinstated
+retroactively. However, if you violate these terms after such reinstatement, any
+additional violation of these terms will cause your licenses to terminate
+automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising out
+of these terms or the use or nature of the software, under any kind of legal
+claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion of
+it.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+Control means ownership of substantially all the assets of an entity, or the
+power to direct its management and policies by vote, contract, or otherwise.
+Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.
+
+**Trademark** means trademarks, service marks, and similar rights.

agent_kg-0.7.0/PKG-INFO

@@ -0,0 +1,377 @@
+Metadata-Version: 2.4
+Name: agent-kg
+Version: 0.7.0
+Summary: Conversational memory as a knowledge graph
+License-Expression: Elastic-2.0
+License-File: LICENSE
+Keywords: knowledge-graph,conversation-memory,lancedb,mcp,semantic-search,claude
+Author: Eric G. Suchanek, PhD
+Author-email: suchanek@flux-frontiers.com
+Requires-Python: >=3.12,<3.14
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Provides-Extra: all
+Provides-Extra: dev
+Provides-Extra: kgdeps
+Provides-Extra: llm
+Provides-Extra: local
+Provides-Extra: viz
+Requires-Dist: anthropic (>=0.25.0) ; extra == "all"
+Requires-Dist: anthropic (>=0.25.0) ; extra == "llm"
+Requires-Dist: click (>=8.1.0,<9)
+Requires-Dist: detect-secrets (>=1.5.0) ; extra == "all"
+Requires-Dist: detect-secrets (>=1.5.0) ; extra == "dev"
+Requires-Dist: doc-kg (>=0.16.0) ; extra == "all"
+Requires-Dist: doc-kg (>=0.16.0) ; extra == "kgdeps"
+Requires-Dist: kgmodule-utils (>=0.4.5)
+Requires-Dist: lancedb (>=0.29.0)
+Requires-Dist: mcp (>=1.0.0)
+Requires-Dist: numpy (>=1.24.0)
+Requires-Dist: openai (>=1.30.0) ; extra == "all"
+Requires-Dist: openai (>=1.30.0) ; extra == "local"
+Requires-Dist: pdoc (>=14.0.0) ; extra == "all"
+Requires-Dist: pdoc (>=14.0.0) ; extra == "dev"
+Requires-Dist: pre-commit (>=4.5.1) ; extra == "all"
+Requires-Dist: pre-commit (>=4.5.1) ; extra == "dev"
+Requires-Dist: pycode-kg (>=0.19.3) ; extra == "all"
+Requires-Dist: pycode-kg (>=0.19.3) ; extra == "kgdeps"
+Requires-Dist: pytest (>=8.0.0) ; extra == "all"
+Requires-Dist: pytest (>=8.0.0) ; extra == "dev"
+Requires-Dist: pytest-cov (>=5.0.0) ; extra == "all"
+Requires-Dist: pytest-cov (>=5.0.0) ; extra == "dev"
+Requires-Dist: pyvis (>=0.3.2) ; extra == "all"
+Requires-Dist: pyvis (>=0.3.2) ; extra == "viz"
+Requires-Dist: rich (>=14.0.0)
+Requires-Dist: ruff (>=0.4.0) ; extra == "all"
+Requires-Dist: ruff (>=0.4.0) ; extra == "dev"
+Requires-Dist: safetensors (>=0.5.0)
+Requires-Dist: sentence-transformers (>=5.2.0)
+Requires-Dist: spacy (>=3.7.0)
+Requires-Dist: streamlit (>=1.35.0) ; extra == "all"
+Requires-Dist: streamlit (>=1.35.0) ; extra == "viz"
+Requires-Dist: torch (>=2.5.1)
+Requires-Dist: transformers (>=4.40.0,<4.57)
+Requires-Dist: ty (>=0.0.41) ; extra == "all"
+Requires-Dist: ty (>=0.0.41) ; extra == "dev"
+Project-URL: Homepage, https://github.com/Flux-Frontiers/agent_kg
+Project-URL: Repository, https://github.com/Flux-Frontiers/agent_kg
+Description-Content-Type: text/markdown
+
+
+[![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13-blue.svg)](https://www.python.org/)
+[![License: Elastic-2.0](https://img.shields.io/badge/License-Elastic%202.0-blue.svg)](https://www.elastic.co/licensing/elastic-license)
+[![Version](https://img.shields.io/badge/version-0.7.0-blue.svg)](https://github.com/Flux-Frontiers/agent_kg/releases)
+[![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/)
+[![DOI](https://zenodo.org/badge/1186774406.svg)](https://zenodo.org/badge/latestdoi/1186774406)
+
+**AgentKG** — Conversational Memory as a Live, Queryable Knowledge Graph
+
+*Author: Eric G. Suchanek, PhD*
+
+*Flux-Frontiers, Liberty TWP, OH*
+
+---
+
+## Overview
+
+AgentKG stores every conversation turn, topic, entity, intent, task, and user preference as a node in a **persistent knowledge graph** (SQLite + LanceDB). Edges encode relationships between turns, sessions, and profile facts. The result is a queryable, prunable, semantically searchable memory that survives context resets and accumulates across projects.
+
+The graph is split into two stores:
+
+- **Per-repo conversation graph** (`.agentkg/`) — turns, topics, entities, intents, tasks, summaries
+- **Global user profile** (`~/.kgrag/profiles/<person>/`) — preferences, expertise, style, commitments, interests; never pruned
+
+Embeddings use `all-MiniLM-L6-v2` (384-dim) via `sentence-transformers` + LanceDB. Structure is treated as ground truth; semantic search is strictly a retrieval accelerant.
+
+---
+
+## Features
+
+- **Incremental ingest** — every turn indexed in real-time; topics, entities, and intents extracted automatically via spaCy + keyword fallback
+- **Hybrid query** — semantic seeding (LanceDB) + structural expansion (graph traversal)
+- **Global UserProfile tree** — preference, expertise, style, commitment, interest, and context nodes accumulated across all repos
+- **Structured onboarding** — four-phase interview populates the profile on first use
+- **Implicit profile updates** — NLP pipeline extracts standing rules from natural language ("always do X", "I prefer Y")
+- **Context assembly** — token-budgeted context block built from the graph for LLM prompt injection
+- **KG Context Pruning** — old turns compressed into Summary nodes when the graph grows large
+- **Temporal snapshots** — point-in-time JSON snapshots for diffing session state
+- **MCP server** — exposes the full query pipeline as structured tools for AI agent integration
+- **Script-based hooks** — three Claude Code hooks (UserPromptSubmit, Stop, PreCompact) deployed as shell scripts via `install-hooks`
+
+---
+
+## Quick Start
+
+```bash
+# 1. Download the embedding model and create your profile directory
+agentkg init --person <you>
+
+# 2. Run the onboarding interview
+agentkg onboard --person <you>
+
+# 3. Check your profile
+agentkg profile --person <you>
+```
+
+Embeddings are on by default. `init` pre-warms the model cache so the first `ingest` does not pause to download.
+
+---
+
+## Person ID
+
+`--person` identifies the **global user profile** at `~/.kgrag/profiles/<person>/`.
+The default is your OS login name (`getpass.getuser()`), which is correct automatically
+on a single-user machine — you rarely need to set it explicitly.
+
+**`--person` only affects profile-scoped commands:** `init`, `onboard`, `profile`,
+`viz --profile`, `wipe --global`. Local graph commands (`query`, `assemble`, `stats`,
+`sessions`, `snapshot`, `prune`, `ingest`, `analyze`) are repo-scoped and ignore it.
+
+```bash
+# Single-user machine: default is correct, no flag needed
+agentkg onboard    # writes to ~/.kgrag/profiles/<your-os-username>/
+agentkg profile    # reads the same path ← correct
+
+# Multi-user or named profiles: be explicit on profile commands only
+agentkg onboard --person alice
+agentkg profile --person alice
+agentkg query "auth strategy"   # no --person needed here
+```
+
+If `agentkg profile` returns an empty `# UserProfile`, check which `--person` value
+was used during `onboard`. The completion message prints the exact path.
+
+---
+
+## CLI Reference
+
+All commands accept `--repo <path>` (default `.`). `--person <id>` defaults to your OS
+username and is only needed for profile-scoped commands (`init`, `onboard`, `profile`,
+`viz --profile`, `wipe --global`).
+
+| Command | Description |
+|---|---|
+| `agentkg init` | Download embedding model and create profile directory (run first) |
+| `agentkg install-hooks` | Deploy hook scripts and wire Claude Code settings.json |
+| `agentkg onboard` | Run the structured UserProfile onboarding interview |
+| `agentkg profile` | Show the UserProfile as Markdown |
+| `agentkg ingest` | Add a turn to the conversation graph |
+| `agentkg query` | Semantic search over the graph |
+| `agentkg assemble` | Assemble a token-budgeted context block |
+| `agentkg prune` | Compress old turns into Summary nodes |
+| `agentkg stats` | Show graph node/edge counts |
+| `agentkg analyze` | Print a full Markdown analysis report |
+| `agentkg sessions` | List all sessions for this repo |
+| `agentkg snapshot` | Capture a point-in-time snapshot |
+| `agentkg mcp` | Start the MCP server (stdio transport) |
+
+Each command also ships as a dedicated `agentkg-<name>` script — no `poetry run` needed:
+
+```bash
+agentkg-init     --person egs          # profile-scoped
+agentkg-onboard  --person egs          # profile-scoped
+agentkg-profile  --person egs          # profile-scoped
+agentkg-stats    --repo .
+agentkg-query    "authentication strategy" --k 8 --repo .
+agentkg-assemble "what did we decide about auth?" --budget 4000 --repo .
+agentkg-prune    --window 20 --repo .
+agentkg-mcp
+```
+
+---
+
+## Installation
+
+**Requirements:** Python ≥ 3.12, < 3.14
+
+### Poetry (recommended)
+
+```bash
+git clone https://github.com/Flux-Frontiers/agent_kg.git
+cd agent_kg
+poetry install
+```
+
+### As a dependency
+
+```toml
+[tool.poetry.dependencies]
+agent-kg = {git = "https://github.com/Flux-Frontiers/agent_kg.git"}
+```
+
+### Optional extras
+
+```bash
+poetry install -E llm    # Anthropic summarizer backend
+poetry install -E viz    # Streamlit explorer UI + pyvis graph visualization
+poetry install -E local  # httpx for local LLM backends
+poetry install -E all    # everything above
+```
+
+spaCy is a **required** dependency (not an extra) — it is always installed and drives topic and entity extraction. The `en_core_web_sm` model must be downloaded separately:
+
+```bash
+python -m spacy download en_core_web_sm
+```
+
+Without the model, extraction falls back to keyword/regex heuristics automatically.
+
+---
+
+## Data Layout
+
+```
+<repo-root>/.agentkg/
+  graph.sqlite          # nodes + edges (conversation graph)
+  lancedb/              # vector embeddings
+  snapshots/            # point-in-time JSON snapshots
+
+~/.kgrag/profiles/<person>/
+  userprofile.sqlite    # global UserProfile tree (never pruned)
+```
+
+---
+
+## Node Kinds
+
+| Kind | What it stores |
+|---|---|
+| `turn` | Raw user/assistant message text |
+| `topic` | N-gram topics extracted from turns |
+| `entity` | Named entities (people, tools, projects) |
+| `intent` | Classified intent category per turn |
+| `task` | Action items extracted from conversation |
+| `summary` | Pruned turn summaries (after prune pass) |
+| `preference` | User coding/style preferences (profile) |
+| `commitment` | Standing rules — "always do X" (profile) |
+| `expertise` | Domain knowledge areas (profile) |
+| `interest` | Topics the user cares about (profile) |
+| `style` | Formatting/docstring/verbosity preferences (profile) |
+| `context` | Role, machine, projects context (profile) |
+| `education` | Educational background entries (profile) |
+
+---
+
+## MCP Server
+
+AgentKG ships a **Model Context Protocol (MCP) server** that exposes the full query pipeline as structured tools for AI agents.
+
+```bash
+agentkg-mcp   # stdio transport
+```
+
+Configure in `.mcp.json` (Claude Code / Kilo Code):
+
+```json
+{
+  "mcpServers": {
+    "agent-kg": {
+      "command": "agentkg-mcp"
+    }
+  }
+}
+```
+
+---
+
+## Hooks (Auto-Ingest)
+
+AgentKG ships three Claude Code hook scripts that are deployed by the installer:
+
+| Hook | Script | What it does |
+|---|---|---|
+| `UserPromptSubmit` | `agent_kg_user_prompt_hook.sh` | Ingests each user turn with embeddings |
+| `Stop` | `agent_kg_stop_hook.sh` | Ingests assistant turn; runs `prune` async every 20 exchanges; snapshots |
+| `PreCompact` | `agent_kg_precompact_hook.sh` | Runs `prune` + snapshot **synchronously** before context compaction — ensures no turns are lost |
+
+### Install
+
+```bash
+# Deploy scripts to ~/.agentkg/hooks/ and wire into ~/.claude/settings.json (all repos)
+agentkg install-hooks --global
+
+# Or wire into .claude/settings.json for this repo only
+agentkg install-hooks --claude
+
+# Force-overwrite existing hooks
+agentkg install-hooks --global --force
+```
+
+The installer:
+1. Copies the three `.sh` scripts from the package into `~/.agentkg/hooks/` (executable)
+2. Merges `UserPromptSubmit`, `Stop`, and `PreCompact` entries into the target `settings.json`
+
+The scripts are portable — they use `git rev-parse --show-toplevel` to locate the repo and only fire when a `.agentkg/` directory is present.
+
+### Hook state and logs
+
+```
+~/.agentkg/hook_state/
+  hook.log                          # timestamped log of all hook activity
+  <session_id>_last_consolidate     # exchange counter for periodic prune
+```
+
+---
+
+## Project Structure
+
+```
+agent_kg/
+├── README.md
+├── pyproject.toml
+├── hooks/                            # reference copies of hook scripts
+│   ├── agent_kg_user_prompt_hook.sh
+│   ├── agent_kg_stop_hook.sh
+│   └── agent_kg_precompact_hook.sh
+├── scripts/
+│   └── generate_wiki.py              # GitHub wiki generator
+├── src/
+│   └── agent_kg/
+│       ├── __init__.py
+│       ├── graph.py                  # AgentKG orchestrator
+│       ├── store.py                  # SQLite + LanceDB storage
+│       ├── index.py                  # LanceDB semantic indexing
+│       ├── ingest.py                 # Phase 1 incremental turn ingest
+│       ├── user_profile.py           # Global UserProfile tree
+│       ├── onboard.py                # Structured onboarding interview
+│       ├── session.py                # Session lifecycle
+│       ├── query.py                  # Hybrid semantic + graph query
+│       ├── assemble.py               # Token-budgeted context assembly
+│       ├── prune.py                  # KG Context Pruning
+│       ├── consolidate.py            # Deferred embedding consolidation
+│       ├── summarize.py              # LLM-backed summarization
+│       ├── snapshots.py              # Point-in-time snapshot capture
+│       ├── schema.py                 # Node/Edge dataclasses
+│       ├── kg.py                     # High-level KG facade
+│       ├── app.py                    # Streamlit explorer UI
+│       ├── viz.py                    # Visualization helpers (Rich + pyvis)
+│       ├── hooks/                    # bundled hook scripts (deployed by install-hooks)
+│       │   ├── agent_kg_user_prompt_hook.sh
+│       │   ├── agent_kg_stop_hook.sh
+│       │   └── agent_kg_precompact_hook.sh
+│       ├── cli/
+│       │   ├── main.py               # Click CLI entry points
+│       │   └── __init__.py
+│       ├── mcp/
+│       │   └── server.py             # MCP server
+│       └── nlp/                      # NLP pipeline (spaCy + regex fallback)
+│           ├── entities.py
+│           ├── intent.py
+│           ├── preferences.py
+│           └── topics.py
+└── tests/
+```
+
+---
+
+## License
+
+[Elastic License 2.0](https://www.elastic.co/licensing/elastic-license) — see [LICENSE](LICENSE).
+
+Free to use, modify, and distribute. You may not offer the software as a hosted or managed service to third parties. Commercial use internally is permitted.
+