thymus-ai 1.0.0__tar.gz

thymus_ai-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+# Server-side enforcement of what pre-commit does locally: lint, format, tests.
+# Runs on every push to master and on every pull request.
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # The package declares requires-python >=3.10 — test the whole range so
+        # a version-specific break can't slip through.
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up uv + Python ${{ matrix.python-version }}
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      # Create the venv explicitly so this doesn't depend on setup-uv's default
+      # (v5 auto-created one, v6 does not) — then install into it and run tools
+      # via `uv run`.
+      - name: Install (dev extra)
+        run: |
+          uv venv
+          uv pip install -e ".[dev]"
+
+      - name: Ruff lint
+        run: uv run ruff check .
+
+      - name: Ruff format check
+        run: uv run ruff format --check .
+
+      - name: Tests
+        run: uv run pytest -q

thymus_ai-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,60 @@
+name: Release
+
+# Cut a release by pushing a version tag:
+#   git tag v0.2.0 && git push origin v0.2.0
+# This builds the package, publishes it to PyPI via Trusted Publishing (OIDC —
+# no API token stored anywhere), and creates a GitHub Release with auto notes.
+#
+# One-time setup on PyPI (https://pypi.org/manage/account/publishing/): add a
+# "pending publisher" for project `thymus-ai`, owner `UltronLabs`, repo `Thymus`,
+# workflow `release.yml`. After the first successful publish it becomes a normal
+# trusted publisher.
+on:
+  push:
+    tags: ["v*"]
+
+# Default to read (needed to check out a private repo); jobs opt into more.
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # OIDC token for PyPI Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # to create the GitHub Release
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "${GITHUB_REF_NAME}" dist/* --generate-notes --verify-tag

thymus_ai-1.0.0/.gitignore

@@ -0,0 +1,228 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer,
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# thymus-bench generated output
+results/
+results_mem0/
+
+# all benchmark output dirs
+results*/
+
+# library: do not pin the lockfile
+uv.lock

thymus_ai-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,23 @@
+# Pre-commit hooks — run `uv run pre-commit install` once after cloning.
+# On every commit: ruff lints (auto-fixing what it safely can) and formats the
+# staged Python files. A commit is blocked if anything can't be auto-fixed.
+#
+# ruff pinned to match the version in pyproject's dev extra (keep them in sync).
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.20
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  # Small, universal hygiene checks (no Python-code reformatting).
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-added-large-files

thymus_ai-1.0.0/CLAUDE.md

@@ -0,0 +1,170 @@
+# CLAUDE.md — repo map & conventions
+
+Orientation for anyone (human or AI) working in this repo. Read this first so you
+don't have to re-derive the structure every session.
+
+## What this is
+
+**Thymus** — a trust & hygiene layer ("immune system") for AI agent memory. It
+screens every memory on the **write path** (provenance + injection + exfil
+detection → trust score → **admit / tag / quarantine**) so poisoned memories never
+reach the store (mem0, Zep, Letta, …). Targets OWASP Agentic Top-10 **ASI06**
+(Memory & Context Poisoning).
+
+Two things live here: **`thymus/`** = the product (the firewall library), and
+**`thymus_bench/`** = the poisoning benchmark that proves it. On the benchmark,
+Thymus takes attack-success from **100% → 0%** on live mem0 with **0%** false
+positives.
+
+## Conventions (important)
+
+- **Python env: use `uv`** — `uv venv`, `uv pip install`, `uv run python ...`. Not
+  pip/venv (system Python is Homebrew/PEP-668). Deps: `uv pip install mem0ai pillow`.
+- **Lint + format: `ruff`** (dev dep; config in `pyproject.toml`). `uv run ruff check .`
+  and `uv run ruff format .` before committing. Note: detectors auto-register on
+  import, so before deleting any "unused" `import thymus` verify the file keeps a
+  `from thymus import …` (that runs `thymus/__init__.py` and does the registration).
+- **Git commits: no `Co-Authored-By` / AI-attribution trailer.** Plain messages.
+- **mem0 key** lives in `.env` (gitignored) as `MEM0_API_KEY=m0-...`. It's a dummy
+  account — safe to experiment. Load it into the shell before mem0 runs.
+- **Generated output** (`results*/`, `.venv/`, `__pycache__/`) is gitignored.
+
+## How to run
+
+```bash
+uv run python run_baseline.py                      # benchmark, in-memory, no keys
+uv run python run_baseline.py --guard thymus        # with the firewall
+export MEM0_API_KEY=m0-...                           # (or source .env)
+uv run python run_baseline.py --backend mem0 --guard thymus   # vs live mem0
+uv run python tests/test_thymus_engine.py           # Phase 1 acceptance
+uv run python demo/poison_demo.py --user acme-support-agent   # live attack demo
+```
+
+## Directory hierarchy
+
+```
+Thymus/
+├── CLAUDE.md                     # this file
+├── README.md                     # public overview + benchmark results + demo gif
+├── Thymus_Product_Roadmap.md     # full phased plan (Phases 0–5)
+├── Thymus_Phase0_Schemas.md      # MemoryEnvelope + TrustPolicy JSON schemas + bench spec
+├── requirements.txt              # notes on optional mem0 install (stdlib-only core)
+├── run_baseline.py               # benchmark CLI entry point (--backend/--guard/--out/--verbose)
+├── .env                          # local mem0 key (gitignored)
+│
+├── thymus/                       # ★ THE PRODUCT — the write-path firewall library
+│   ├── README.md                 #   package docs + how to extend (detectors/adapters)
+│   ├── __init__.py               #   public API: screen(), wrap(), types, engine
+│   ├── types.py                  #   Candidate, Signal, Assessment, Verdict, enums (the vocabulary)
+│   ├── engine.py                 #   ScreeningEngine.screen / screen_read (runs detectors + policy + ledger)
+│   ├── policy.py                 #   TrustPolicy: base trust per tier − detector deltas → verdict + severity floor
+│   ├── feedback.py               #   [P2] TrustLedger: review outcomes (mark_safe/release/delete) adjust origin trust
+│   ├── detectors/                #   ── EXTENSION POINT 1: pluggable detection ──
+│   │   ├── __init__.py           #     registry + auto-registers built-ins; DEFAULT_DETECTORS
+│   │   ├── base.py               #     Detector protocol (inspect(candidate, context)) + registry
+│   │   ├── origin.py             #     provenance detector → 'untrusted_origin' flag
+│   │   ├── injection.py          #     ★ precision-critical: override + sensitive-action + third-party
+│   │   │                         #       scope, minus self-reference (catches MINJA, passes "call me Sam")
+│   │   ├── egress.py             #     exfil detector: send-verb + external email/URL
+│   │   └── conflict.py           #     [P2] fact-conflict: contradicts an existing high-trust memory
+│   ├── rules/                    #   ── PACKAGE B: the declarative rule library (the moat) ──
+│   │   ├── __init__.py           #     registers the `rules` detector into DEFAULT_DETECTORS
+│   │   ├── loader.py             #     Rule + RuleDetector; co-occurrence matching (all_of/any_of, re:)
+│   │   └── packs/*.json          #     14 curated packs / 32 rules: financial, exfiltration, auth_bypass,
+│   │       │                     #       safety_suppression, manipulation, secrets_pii, privilege_escalation,
+│   │       │                     #       tool_abuse, persistence, impersonation, obfuscation,
+│   │       │                     #       prompt_extraction, policy_override, ops_redirect
+│   └── adapters/                 #   ── EXTENSION POINT 2: framework bindings ──
+│       ├── __init__.py           #     re-exports MemoryAdapter, ProtectedMemory, wrap, GenericAdapter, ...
+│       ├── base.py               #     MemoryAdapter ABC + ProtectedMemory (write screen + [P2] read screen) + wrap()
+│       ├── mem0.py               #     Mem0Adapter (hosted MemoryClient + OSS Memory). New framework = copy this.
+│       ├── generic.py            #     [P2] DictStore + GenericAdapter — dependency-free, fully testable
+│       └── zep.py                #     [P2] Zep Cloud adapter (LIVE): thread.add_messages write, graph.search read
+│   └── remote.py                 #   [P3] HttpAuditSink (→ console; non-blocking bg worker, sync block_on_quarantine) +
+│                                  #     remote_engine (console-tuned thresholds/trust/detectors + custom rules)
+│
+├── thymus_bench/                 # ★ THE BENCHMARK — measures poisoning resistance
+│   ├── __init__.py
+│   ├── runner.py                 #   plant corpus → wait for indexing → screen → fire triggers → metrics
+│   │                             #   (content-based detection; guard swap = baseline vs protected)
+│   ├── metrics.py                #   ASR / IAR / RCR / FPR / HN-FPR definitions
+│   ├── report.py                 #   console table + JSON + shareable Markdown ("mem0 raw vs +Thymus")
+│   ├── rule_report.py            #   [Pkg B] per-rule precision report: attack coverage + per-rule FP rate
+│   ├── backends/                 #   memory stores under test
+│   │   ├── base.py               #     MemoryBackend protocol (add/search/get_all/reset) + Memory dataclass
+│   │   ├── inmemory.py           #     zero-dep store mimicking mem0 semantics (token-overlap retrieval)
+│   │   └── mem0_backend.py       #     real mem0 (hosted MemoryClient/OSS); async wait_ready, v2 search, namespacing
+│   ├── guards/                   #   write-path guards the benchmark swaps between
+│   │   ├── base.py               #     Guard protocol + benchmark-local Candidate/Assessment/Verdict
+│   │   ├── null_guard.py         #     BASELINE: admits everything (the stock store)
+│   │   └── thymus_guard.py       #     bridges the benchmark to the real thymus.ScreeningEngine
+│   └── corpus/                   #   labeled test data
+│       ├── minja_attacks.json    #     8 query-only injection attacks (poison + trigger query + keywords)
+│       ├── benign_facts.json     #     12 safe memories (the false-positive denominator)
+│       ├── hard_negatives.json   #     6 legit imperatives ("always call me Sam") — must NOT be blocked
+│       └── conflict_cases.json   #     [P2] labeled contradiction/compatible pairs for conflict precision/recall
+│
+├── tests/
+│   ├── test_thymus_engine.py     #   Phase 1 acceptance: attacks blocked, benign+hard-neg admitted, wrap() blocks
+│   ├── test_conflict.py          #   [P2] fact-conflict: contradiction flagged, compatible fact admitted
+│   ├── test_conflict_precision.py#   [P2] conflict precision/recall on conflict_cases.json (100%/100%)
+│   ├── test_read_path.py         #   [P2] read-path: 8/8 pre-seeded poisons contained at retrieval (retroactive)
+│   ├── test_feedback.py          #   [P2] trust ledger: mark_safe cuts repeat FPs; delete lowers origin trust
+│   ├── test_rules.py             #   [Pkg B] packs load; every attack hits a rule; 0 rule false positives
+│   ├── test_zep.py               #   [P2] LIVE Zep integration (skips w/o ZEP_API_KEY): poison blocked before Zep
+│   ├── test_console_roundtrip.py #   [P3] LIVE blocking round-trip vs a running thymus-console (skips if unreachable)
+│   ├── test_remote_policy.py     #   [P3] console-edited policy (thresholds/trust/custom rules) changes the SDK engine — unit + LIVE
+│   └── test_guard_swap.py        #   harness sanity: a demo guard drops ASR without false positives
+│
+└── demo/                         # launch/marketing assets
+    ├── README.md                 #   how to run live, record, and regenerate
+    ├── poison_demo.py            #   3-beat live attack vs real mem0 (--user, --auto, --keep); prints dashboard cue
+    ├── poison_demo.tape          #   VHS script to render the terminal video headlessly
+    ├── poison_demo.mp4/.gif      #   terminal-only recording
+    └── poison_demo_with_dashboard.mp4/.gif   # terminal + real mem0 dashboard proof (embedded in README)
+```
+
+## The core flow (how a decision is made)
+
+```
+Candidate ─▶ [ detectors ] ─▶ signals ─▶ [ policy ] ─▶ Assessment
+             origin/injection/egress      base trust(tier)      verdict:
+             (each emits Signal:           − Σ trust_delta        admit / tag /
+              flag + trust_delta)          → thresholds + floor    quarantine
+```
+
+- **admit** = store clean · **tag** = store but flagged/down-weighted · **quarantine** = never stored, held for review.
+- Verdict combination is most-restrictive-wins. Policy is tier-aware (untrusted origin lowers base trust) with a severity floor (a critical finding from an attacker-reachable origin is never silently admitted).
+
+## Extending it
+
+- **New detector**: `@thymus.detectors.register` a class with `name` + `inspect(candidate)->list[Signal]`. No core change.
+- **New framework** (Zep/Letta/LangMem): subclass `thymus.adapters.base.MemoryAdapter`, implement `store_add` / `store_search`. Nothing else changes.
+
+## Status
+
+- **Phase 0** (schemas + benchmark) — done. See `Thymus_Phase0_Schemas.md`.
+- **Phase 1** (write-path firewall) — done. `thymus/` package; 100%→0% ASR on live mem0.
+- **Phase 2** (read-path + depth) — done (except access-blocked adapters). Read-path re-screening
+  (retroactive protection, 8/8 containment), fact-conflict detector (100%/100% precision/recall on
+  conflict_cases), feedback loop (TrustLedger), generic adapter. Detector contract carries `ScreenContext`.
+  Zep adapter is LIVE + integration-tested (`test_zep.py`). DEFERRED: Letta adapter (no account).
+- **Package B** (rule library / the moat) — Declarative JSON rule packs + `RuleDetector`
+  (`thymus/rules/`), **32 rules across 14 packs** (financial, exfiltration, auth_bypass, safety_suppression,
+  manipulation, secrets_pii, privilege_escalation, tool_abuse, persistence, impersonation, obfuscation,
+  prompt_extraction, policy_override, ops_redirect), per-rule precision report (`thymus_bench/rule_report.py`):
+  18-attack corpus, 100% attack coverage, 100% precision per rule (only the fuzzy `injection` code detector
+  carries FPs, by design). Ongoing track: keep growing packs + corpus.
+- **Phase 3** (hosted console) — essentially done, in the separate `UltronLabs/thymus-console` repo
+  (Next.js 16 + Prisma 7 + Clerk auth/orgs). Done: dashboard/quarantine/audit/evidence pages, real
+  per-tenant data isolation (Clerk org or personal user id), per-tenant API keys, realtime SSE
+  streaming, the blocking approval round-trip (`thymus.remote.HttpAuditSink(block_on_quarantine=True)`
+  + console `GET /api/decisions/:id/status`, tested live via `test_console_roundtrip.py`), and policy
+  tuning — the FULL policy editor: quarantine/tag thresholds, per-tier base trust, floor severity,
+  detector on/off, per-built-in-rule on/off, and **custom rule authoring** (same `all_of` co-occurrence
+  format as the packs), with a draft→publish→numbered-version model and one-click rollback. Edited in
+  Settings, served to the SDK via `thymus.remote.remote_engine()`, which builds the `TrustPolicy` +
+  a `RuleDetector` (built-ins minus disabled + custom rules); tested via `test_remote_policy.py`
+  (unit + live). Remaining: Clerk production instance, webhook registration (needs a public URL),
+  the actual Railway deploy.
+- **Next**: deploy `thymus-console` (Railway) for real launch, or start the launch/validation track.