jnaapakam 0.3.0__tar.gz

jnaapakam-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - name: Verify SQLite ships FTS5 on this runner
+        run: |
+          python - <<'PY'
+          import sqlite3
+          db = sqlite3.connect(":memory:")
+          db.execute("CREATE VIRTUAL TABLE t USING fts5(body)")
+          print("FTS5 available; sqlite", sqlite3.sqlite_version)
+          PY
+      - run: ruff check src tests
+      - run: pytest -q

jnaapakam-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,74 @@
+name: Publish to PyPI
+
+# Publishing is irreversible: a version number can never be reused on PyPI, even
+# after deletion. So this runs only on an explicit tag, and the release job is
+# gated behind a GitHub Environment you can require manual approval on.
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Run the full test suite before building
+        run: |
+          pip install -e ".[dev]"
+          ruff check src tests
+          pytest -q
+
+      - name: Refuse to publish a version that is not release-ready
+        run: |
+          python - <<'PY'
+          import re, pathlib, sys
+          version = re.search(
+              r'^version = "([^"]+)"', pathlib.Path("pyproject.toml").read_text(), re.M
+          ).group(1)
+          print(f"pyproject version: {version}")
+          if any(marker in version for marker in ("dev", "a", "b", "rc")):
+              sys.exit(f"Refusing to publish pre-release version {version!r}. Set a final version first.")
+          PY
+
+      - name: Build sdist and wheel
+        run: |
+          pip install build
+          python -m build
+
+      - name: Verify the artifacts are well-formed
+        run: |
+          pip install twine
+          twine check dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # Configure this environment in repo Settings → Environments and add a required
+    # reviewer if you want a human approval step before anything reaches PyPI.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/jnaapakam
+    permissions:
+      # Required for Trusted Publishing. No API token is stored anywhere.
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

jnaapakam-0.3.0/.gitignore

@@ -0,0 +1,11 @@
+*.db
+*.egg-info/
+*.pyc
+.env
+.venv/
+.worktrees/
+__pycache__/
+build/
+dist/
+inbox/
+uv.lock

jnaapakam-0.3.0/CHANGELOG.md

@@ -0,0 +1,108 @@
+# Changelog
+
+All notable changes to jñāpakaṁ are recorded here. The protocol specification is
+[PROTOCOL.md](PROTOCOL.md); this file tracks the reference implementation.
+
+## [0.3.0] — 2026-08-31
+
+**Generational continuity.** An agent's model, runtime, tools, hardware and
+capabilities may all change without changing its continuity identity.
+
+This is a claim about systems, not minds: jñāpakaṁ defines a stable identifier, a
+verifiable memory corpus, an auditable lineage and migration provenance. It makes
+no claim about consciousness or subjective identity.
+
+### Added
+
+- **Permanent agent identity** — `urn:jnaapakam:agent:<32 hex>`, minted once and
+  independent of the agent's display name, model, provider, runtime, host,
+  hardware, OS and generation number. Opening an existing database mints one
+  automatically.
+- **Generations** — a portable record of the runtime an agent ran as, with an
+  optional manifest describing runtime, inference, environment, hardware,
+  workspace revision, capabilities and external state. Every section is optional;
+  a minimal generation is `{}`. Unknown sections are preserved verbatim.
+- **Branch-capable lineage** — generations name a parent, so two candidates staged
+  from one parent do not corrupt each other's ancestry.
+- **Migration records** — provenance for every transition, with statuses `staged`,
+  `validated`, `failed`, `promoted`, `rejected` and `rolled_back`.
+- **Continuity validation** — six checks (`identity`, `memory`, `recall`, `soul`,
+  `context`, `behavioral`), each reporting its own result. A check that was not
+  requested reports `skipped`, never `pass`.
+- **Integrity metadata** — SHA-256 over the exact bytes of soul files, plus an
+  order-independent digest over the memory corpus that survives a restore
+  renumbering every row.
+- **Endpoints** — `GET /agent`, `GET /generations`, `GET /generations/diff`,
+  `GET /migrations`; `POST /generations`, `/generations/artifacts`,
+  `/generations/validate`, `/generations/promote`, `/generations/reject`,
+  `/generations/rollback`. All behind the existing bearer authentication.
+- **MCP tools** — `get_agent_identity`, `list_generations`, `diff_generations`.
+  Read-only: deciding which runtime *is* the agent stays an operator action, the
+  same reason `/clear` and `/restore` are not MCP tools.
+- **CLI** — `jnaapakam agent` and `jnaapakam generation {list,show,create,seal,
+  validate,promote,reject,rollback,diff}`. These open the database directly, so
+  continuity works offline with no server, token or network. `validate` exits
+  non-zero on failure, which makes it usable as a migration gate.
+- **Schema** — `meta`, `generations`, `migrations` and `generation_artifacts`
+  tables; `PRAGMA user_version` 3 → 4.
+- **Example** — [examples/generational-continuity](examples/generational-continuity/),
+  a vendor-neutral Generation 1 → Generation 2 walkthrough.
+
+### Changed
+
+- `/backup` now carries `agent_id`, `current_generation`, `corpus_digest`,
+  `generations`, `migrations` and `artifacts`. Soul files remain excluded, exactly
+  as in v0.2 — only their digests travel.
+- `/restore` adopts the backup's `agent_id` when the target store has no lineage
+  of its own, and refuses a different agent when it does. Re-importing an agent's
+  own backup no longer forks its lineage.
+- `version` reported by `/status` and `/backup` is now `"0.3"`; the server and MCP
+  `serverInfo` report `0.3.0`.
+- The full-text index backfill is gated on `user_version < 3` rather than on the
+  current schema version, so future schema bumps no longer trigger a pointless
+  reindex.
+
+### Security
+
+- Generation manifests and external-state references are treated as untrusted
+  metadata: never executed, never dereferenced, never used to build a filesystem
+  path, and never placed in an LLM prompt.
+- Manifests carrying a field named like a credential, or a reference URI with
+  embedded userinfo, are refused. Manifest size and nesting depth are bounded.
+- The server never reads a file to hash it. Digests arrive precomputed; the CLI
+  does the reading, locally, restricted to soul filenames in a directory the
+  operator names. An endpoint that hashes a caller-supplied path would be an
+  arbitrary-file-read oracle.
+- Artifact names must be plain labels and are rejected if they could be resolved
+  against a filesystem.
+- `/restore` validates the entire payload, including manifests and digests, before
+  mutating anything.
+
+### Not in this release
+
+- **Signatures.** v0.3 provides integrity, not authenticity: a digest proves the
+  bytes did not change, but anyone who can write the store can write a digest.
+  Do not read one as the other.
+
+### Compatibility
+
+- Every v0.2 test passes unchanged.
+- A v0.2 database opens and upgrades in place, gaining an identity without losing
+  a memory.
+- A v0.2 backup still restores.
+- A v0.3 backup restored by a v0.2 implementation imports its memories and
+  consolidations and ignores the continuity keys — the lineage is dropped, not
+  corrupted.
+- The only breaking change is the `version` string, and only for a client
+  asserting it exactly.
+
+## [0.2.0]
+
+Retrieval as a protocol operation (`/search`, ranking requirements); enforceable
+namespaces; memory correction by supersession; gated contradiction detection and
+soft forgetting; bearer authentication and safe bind defaults; error semantics;
+corrected default port and `/backup` payload.
+
+## [0.1.0]
+
+Initial protocol specification and reference implementation.

jnaapakam-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,94 @@
+# Contributing to jñāpakaṁ
+
+Thanks for your interest in contributing! Here's how to get started.
+
+## Areas We Need Help With
+
+- 🏷️ **Multi-agent namespacing** — the largest open design question; see PROTOCOL.md §6
+- 🧬 **Signed continuity records** — v0.3 gives integrity, not authenticity; see PROTOCOL.md §10.6
+- 🔌 **Integration examples** — more framework integrations (AutoGen, Semantic Kernel, ADK, etc.)
+- 🤖 **LLM providers** — additional backend support (Groq, Together, Mistral, local models)
+- 📊 **Memory visualization** — dashboard or CLI tools to browse memories
+- 🔒 **Security** — encryption at rest
+- 📏 **Benchmarks** — retrieval quality and latency at realistic memory scales
+- 📝 **Documentation** — tutorials, guides, use case examples
+
+## Development Setup
+
+```bash
+git clone https://github.com/yablokolabs/jnaapakam.git
+cd jnaapakam
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Running the Test Suite
+
+```bash
+pytest                    # all tests
+pytest -q tests/test_store.py
+ruff check src tests      # lint
+```
+
+Tests need no API key, no network, and no database setup: the suite uses a
+deterministic rule-based LLM stand-in and temporary SQLite files.
+
+To run the server locally:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...   # or OPENAI_API_KEY, or LLM_BASE_URL
+jnaapakam serve
+```
+
+## How to Contribute
+
+1. Fork the repo
+2. Create a feature branch: `git checkout -b feature/my-feature`
+3. **Write a failing test first**, then make it pass
+4. Run `pytest` and `ruff check src tests`
+5. Submit a PR
+
+## Guidelines
+
+- Keep the protocol simple — complexity is the enemy
+- No vendor lock-in — everything should work with any LLM provider
+- Privacy first — no telemetry, no external calls except to the configured LLM
+- Document your changes
+
+## Testing Guidelines
+
+The suite is the specification. A few rules that keep it useful:
+
+- **Test behavior, not implementation.** Assert on what an endpoint returns or what
+  ends up in the store — never that a particular function was called.
+- **Don't assert on mocks.** The LLM stand-in in `tests/conftest.py` is a real
+  implementation with deterministic rules. Prefer extending it over patching.
+- **Don't test data shapes for their own sake.** A test that only checks a dict has
+  certain keys tells you nothing about whether the system works.
+- **Failure paths matter as much as success paths.** A silently degraded memory is
+  worse than a loud error; several tests exist specifically to prevent that.
+- **New model IDs need a guard.** Provider models get retired, and a retired ID
+  returns 404. `tests/test_model_selection.py` fails the build if a shipped alias
+  points at a known-retired model — add to its list when a model is withdrawn.
+
+## Code Style
+
+- Python: PEP 8, type hints appreciated. `ruff` config lives in `pyproject.toml`
+- Keep runtime dependencies minimal — `aiohttp` is the only one, and additions need
+  a strong justification. Anything that requires a daemon, a compiled extension, or
+  a network call at first run must be optional and runtime-detected
+- Docstrings on public functions; explain *why*, not *what*
+
+## Protocol Changes
+
+Changes to `PROTOCOL.md` require discussion in an issue first. The protocol should remain:
+- Simple to implement
+- Framework agnostic
+- Backward compatible when possible
+
+When a change is not backward compatible, say so explicitly in the version history
+table and describe what breaks.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

jnaapakam-0.3.0/LICENSE

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