kaygee 0.1.0__tar.gz

kaygee-0.1.0/.claude/settings.local.json

@@ -0,0 +1,22 @@
+{
+  "permissions": {
+    "allow": [
+      "WebSearch",
+      "Bash(python3:*)",
+      "Bash(wc:*)",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:docs.turso.tech)",
+      "WebFetch(domain:pypi.org)",
+      "WebFetch(domain:www.powersync.com)",
+      "WebFetch(domain:techouse.github.io)",
+      "WebFetch(domain:philipotoole.com)",
+      "Bash(python -m pytest tests/test_changelog.py tests/test_sync.py -v -p no:deepeval)",
+      "Bash(uv run pytest:*)",
+      "Bash(python -m pytest:*)",
+      "Bash(grep:*)",
+      "Bash(/Users/tanmaygupta/dev/kaybee/tests/conftest.py:*)",
+      "Bash(python -c:*)",
+      "Bash(curl:*)"
+    ]
+  }
+}

kaygee-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,27 @@
+name: tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "0.4.20"
+      - name: Install deps
+        run: uv sync --dev
+      - name: Run tests
+        run: make test

kaygee-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.DS_Store
+uv.lock

kaygee-0.1.0/Makefile

@@ -0,0 +1,19 @@
+.PHONY: install test test-verbose publish clean
+
+install:
+	uv sync --dev
+
+test:
+	uv run pytest
+
+test-verbose:
+	uv run pytest -vv
+
+publish:
+	rm -rf dist
+	uv build
+	uv run twine upload --repository pypi dist/kaygee-*
+
+clean:
+	rm -rf dist
+	find . -name "__pycache__" -type d -prune -exec rm -rf {} +

kaygee-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: kaygee
+Version: 0.1.0
+Summary: A flat, SQLite-native knowledge graph with YAML frontmatter and wikilinks
+Project-URL: Homepage, https://github.com/tg1482/kaygee
+Project-URL: Repository, https://github.com/tg1482/kaygee
+Author-email: Tanmay Gupta <tg1482@stern.nyu.edu>
+License: MIT
+Keywords: agents,frontmatter,knowledge-graph,llm,sqlite,wikilinks
+Classifier: Development Status :: 3 - Alpha
+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 :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# kaygee
+
+Flat, SQLite-native knowledge graph for agent memory.
+
+## What it is
+
+A knowledge graph stored in SQLite. Nodes have YAML frontmatter, link to each other with `[[wikilinks]]`, and self-organize into typed tables. No schema upfront — it emerges from the data you write.
+
+```python
+from kaygee import KnowledgeGraph
+
+kg = KnowledgeGraph("brain.db")
+
+kg.write("spreading-activation", """---
+type: concept
+description: How activation propagates through a network
+tags: [cognition, search]
+---
+Follows [[agent-traversal]] paths and uses [[semantic-similarity]].""")
+
+kg.write("turing", """---
+type: person
+role: researcher
+born: 1912
+---
+Pioneered computation and [[agent-traversal]].""")
+```
+
+That's it. Types are tracked, links are resolved, backlinks work automatically.
+
+Internally, all node data lives in a single `_data` table. A `_type_fields` table tracks which columns belong to which type. The `nodes` table is a thin index of name + type.
+
+```python
+# Raw SQL is available when you need it
+kg.query("SELECT name, description FROM _data WHERE name = ?", ("spreading-activation",))
+```
+
+## Core operations
+
+```python
+# Write and read
+kg.write("name", "---\ntype: concept\n---\nBody text with [[links]].")
+kg.cat("name")              # full content (frontmatter + body)
+kg.body("name")             # body only
+kg.frontmatter("name")      # metadata dict
+kg.read("name", depth=1)    # this node + content of linked nodes
+
+# Organize
+kg.touch("name")             # create if not exists
+kg.rm("name")                # delete
+kg.mv("old", "new")          # rename
+kg.cp("src", "dst")          # copy
+
+# Search
+kg.ls("concept")             # nodes of type
+kg.find(name="activ.*")      # regex on names
+kg.grep("pattern", content=True)  # regex across content
+kg.tags()                    # {tag: [node, ...]} mapping
+
+# Graph
+kg.wikilinks("name")         # outgoing link targets
+kg.backlinks("name")         # who links here
+kg.graph()                   # full adjacency dict
+kg.schema()                  # {type: [fields]} across all types
+
+# Raw SQL
+kg.query("SELECT name FROM nodes WHERE type = ?", ("concept",))
+```
+
+## Changelog
+
+Every mutation is recorded in an append-only changelog (enabled by default). This drives delta sync and audit trails.
+
+```python
+kg = KnowledgeGraph("brain.db")  # changelog=True by default
+
+kg.write("sa", "---\ntype: concept\n---\nSpreading activation.")
+kg.rm("sa")
+
+entries = kg.changelog(since_seq=0, limit=100)
+# [(1, '2026-...', 'node.write', 'sa', '{"type": "concept", ...}'),
+#  (2, '2026-...', 'node.rm',    'sa', '{"type": "concept"}')]
+
+kg.changelog_truncate(before_seq=2)  # prune old entries
+```
+
+Operations logged: `node.write`, `node.rm`, `node.mv`, `node.cp`, `node.type_change`, `type.add`, `type.rm`.
+
+Disable with `KnowledgeGraph("brain.db", changelog=False)` if you don't need it.
+
+## Sync
+
+Push local changes to a remote MySQL database, scoped by team/user/project. Pull to replicate back.
+
+```python
+from kaygee import sync_push, sync_pull
+
+# Push changelog deltas to MySQL (only changed rows sent)
+last_seq = sync_push(kg, mysql_conn, scope={"team_id": "eng"}, since_seq=0)
+# Persist last_seq for next call
+
+# Pull all rows matching scope from MySQL into local SQLite
+count = sync_pull(kg, mysql_conn, scope={"team_id": "eng"})
+```
+
+- **Push** replays changelog entries — upserts and deletes flow through, including type changes and renames.
+- **Pull** is a full pull filtered by scope. Writes bypass the changelog to avoid push-back loops.
+- Falls back to full-table-scan push when changelog is disabled (deletes not propagated in this mode).
+
+## Constraints
+
+Free-form by default. Add structure when you want it.
+
+```python
+from kaygee import Validator, freeze_schema, requires_field, requires_link, no_orphans
+
+v = Validator()
+v.add(freeze_schema("concept", ["description", "tags"]))
+v.add(requires_field("concept", "description"))
+v.add(requires_link("paper", target_type="person"))
+v.add(no_orphans())
+
+v.check(kg)          # raises ValidationError with all violations
+kg.set_validator(v)  # gatekeeper: blocks invalid writes before they persist
+```
+
+## Shell
+
+```python
+from kaygee import GraphShell
+
+sh = GraphShell(kg)
+sh.run("touch", ["neuron", "---\ntype: concept\n---\nA unit of [[computation]]."])
+sh.run("ls", ["concept"])
+sh.run("links", ["neuron"])
+sh.execute("cat neuron | grep computation")
+```
+
+## Visualization
+
+```python
+from kaygee import visualize
+
+visualize(kg, path="graph.html")  # self-contained interactive HTML
+```
+
+## Install
+
+```bash
+pip install kaygee
+```
+
+## License
+
+MIT

kaygee-0.1.0/README.md

@@ -0,0 +1,155 @@
+# kaygee
+
+Flat, SQLite-native knowledge graph for agent memory.
+
+## What it is
+
+A knowledge graph stored in SQLite. Nodes have YAML frontmatter, link to each other with `[[wikilinks]]`, and self-organize into typed tables. No schema upfront — it emerges from the data you write.
+
+```python
+from kaygee import KnowledgeGraph
+
+kg = KnowledgeGraph("brain.db")
+
+kg.write("spreading-activation", """---
+type: concept
+description: How activation propagates through a network
+tags: [cognition, search]
+---
+Follows [[agent-traversal]] paths and uses [[semantic-similarity]].""")
+
+kg.write("turing", """---
+type: person
+role: researcher
+born: 1912
+---
+Pioneered computation and [[agent-traversal]].""")
+```
+
+That's it. Types are tracked, links are resolved, backlinks work automatically.
+
+Internally, all node data lives in a single `_data` table. A `_type_fields` table tracks which columns belong to which type. The `nodes` table is a thin index of name + type.
+
+```python
+# Raw SQL is available when you need it
+kg.query("SELECT name, description FROM _data WHERE name = ?", ("spreading-activation",))
+```
+
+## Core operations
+
+```python
+# Write and read
+kg.write("name", "---\ntype: concept\n---\nBody text with [[links]].")
+kg.cat("name")              # full content (frontmatter + body)
+kg.body("name")             # body only
+kg.frontmatter("name")      # metadata dict
+kg.read("name", depth=1)    # this node + content of linked nodes
+
+# Organize
+kg.touch("name")             # create if not exists
+kg.rm("name")                # delete
+kg.mv("old", "new")          # rename
+kg.cp("src", "dst")          # copy
+
+# Search
+kg.ls("concept")             # nodes of type
+kg.find(name="activ.*")      # regex on names
+kg.grep("pattern", content=True)  # regex across content
+kg.tags()                    # {tag: [node, ...]} mapping
+
+# Graph
+kg.wikilinks("name")         # outgoing link targets
+kg.backlinks("name")         # who links here
+kg.graph()                   # full adjacency dict
+kg.schema()                  # {type: [fields]} across all types
+
+# Raw SQL
+kg.query("SELECT name FROM nodes WHERE type = ?", ("concept",))
+```
+
+## Changelog
+
+Every mutation is recorded in an append-only changelog (enabled by default). This drives delta sync and audit trails.
+
+```python
+kg = KnowledgeGraph("brain.db")  # changelog=True by default
+
+kg.write("sa", "---\ntype: concept\n---\nSpreading activation.")
+kg.rm("sa")
+
+entries = kg.changelog(since_seq=0, limit=100)
+# [(1, '2026-...', 'node.write', 'sa', '{"type": "concept", ...}'),
+#  (2, '2026-...', 'node.rm',    'sa', '{"type": "concept"}')]
+
+kg.changelog_truncate(before_seq=2)  # prune old entries
+```
+
+Operations logged: `node.write`, `node.rm`, `node.mv`, `node.cp`, `node.type_change`, `type.add`, `type.rm`.
+
+Disable with `KnowledgeGraph("brain.db", changelog=False)` if you don't need it.
+
+## Sync
+
+Push local changes to a remote MySQL database, scoped by team/user/project. Pull to replicate back.
+
+```python
+from kaygee import sync_push, sync_pull
+
+# Push changelog deltas to MySQL (only changed rows sent)
+last_seq = sync_push(kg, mysql_conn, scope={"team_id": "eng"}, since_seq=0)
+# Persist last_seq for next call
+
+# Pull all rows matching scope from MySQL into local SQLite
+count = sync_pull(kg, mysql_conn, scope={"team_id": "eng"})
+```
+
+- **Push** replays changelog entries — upserts and deletes flow through, including type changes and renames.
+- **Pull** is a full pull filtered by scope. Writes bypass the changelog to avoid push-back loops.
+- Falls back to full-table-scan push when changelog is disabled (deletes not propagated in this mode).
+
+## Constraints
+
+Free-form by default. Add structure when you want it.
+
+```python
+from kaygee import Validator, freeze_schema, requires_field, requires_link, no_orphans
+
+v = Validator()
+v.add(freeze_schema("concept", ["description", "tags"]))
+v.add(requires_field("concept", "description"))
+v.add(requires_link("paper", target_type="person"))
+v.add(no_orphans())
+
+v.check(kg)          # raises ValidationError with all violations
+kg.set_validator(v)  # gatekeeper: blocks invalid writes before they persist
+```
+
+## Shell
+
+```python
+from kaygee import GraphShell
+
+sh = GraphShell(kg)
+sh.run("touch", ["neuron", "---\ntype: concept\n---\nA unit of [[computation]]."])
+sh.run("ls", ["concept"])
+sh.run("links", ["neuron"])
+sh.execute("cat neuron | grep computation")
+```
+
+## Visualization
+
+```python
+from kaygee import visualize
+
+visualize(kg, path="graph.html")  # self-contained interactive HTML
+```
+
+## Install
+
+```bash
+pip install kaygee
+```
+
+## License
+
+MIT