Skip to content

AGENTS.md

Latest commit

 

History

History
107 lines (85 loc) · 4.68 KB

AGENTS.md

File metadata and controls

107 lines (85 loc) · 4.68 KB
Raw

AGENTS.md: vault

qp-vault: governed knowledge store. Trust-weighted search, SHA3-256 content IDs, Merkle verification, RBAC, Membrane content screening, knowledge graph. Python 3.12+, Apache 2.0, published on PyPI as qp-vault.

Stack

  • Python 3.12+, Pydantic 2.12+, async-first, hatchling build.
  • Tooling: ruff (line-length 100, target py312), mypy strict, pytest + pytest-asyncio + pytest-cov.
  • Storage: SQLite by default (aiosqlite), or PostgreSQL + pgvector via [postgres] extra.
  • Optional extras: encryption (AES-256-GCM + NaCl), pq (ML-KEM-768 + ML-DSA-65), docling, local (sentence-transformers), openai, fastapi, cli, integrity, capsule.

Commands

make install    # pip install -e ".[sqlite,cli,fastapi,integrity,dev]"
make lint       # ruff check src/ tests/
make format     # ruff check --fix src/ tests/
make typecheck  # mypy src/qp_vault/ (strict)
make test       # pytest with coverage, --cov=qp_vault
make test-all   # lint + typecheck + test

For work needing other extras, install them first: pip install -e ".[postgres,encryption,pq,dev]".

Docker test harness is available: docker compose -f docker-compose.test.yml up (uses Dockerfile.test).

CLI entry: vault (from qp_vault.cli.main:app), 15 commands. See docs/cli.md.

Structure

src/qp_vault/
  vault.py        Vault + AsyncVault top-level API
  config.py       VaultConfig (all configurable settings live here)
  protocols.py    StorageBackend, Embedder, Parser Protocol types
  models.py       Resource, Chunk, SearchQuery, SearchResult, VaultEvent
  enums.py        TrustTier, Lifecycle, MemoryLayer, Role
  exceptions.py   VaultError hierarchy
  streaming.py    VaultEventStream
  core/           chunker, search, lifecycle, freshness decay, trust weighting
  storage/        SQLite + PostgreSQL backends (implement StorageBackend)
  processing/     file parsers (text, transcripts, docling)
  embeddings/     embedder plugins (local, openai)
  membrane/       content screening (prompt injection, XSS, jailbreak)
  graph/          knowledge graph (nodes, edges, mentions, backlinks)
  integrity/      staleness and duplicate detection
  encryption/     AES-256-GCM classical + ML-KEM-768 hybrid
  rbac.py         Reader / Writer / Admin role matrix
  plugins/        registry and @embedder / @parser decorators
  integrations/   fastapi_routes (22+ REST endpoints)
  cli/            typer CLI (entry: vault)
  audit/          VaultEvent stream + optional qp-capsule audit provider
tests/            1048+ tests. Markers: unit, integration, e2e, postgres, slow
docs/             16 topic docs (getting-started, architecture, trust-tiers, lifecycle, security, ...)

Style

  • No em dashes anywhere. Use commas, periods, colons, parentheses.
  • Type hints on every public function, docstrings on public classes and methods.
  • Async-first: all I/O must be async. Never block the event loop.
  • No hardcoded values: configurable settings go through VaultConfig.
  • Crypto allowlist: SHA3-256, AES-256-GCM, ML-KEM-768, ML-DSA-65, Ed25519 (via qp-capsule). Never MD5, SHA1, SHA2, RSA, 3DES, RC4.

Plugin pattern:

from qp_vault.plugins import embedder

@embedder("my-model")
class MyEmbedder:
    dimensions = 768
    async def embed(self, texts: list[str]) -> list[list[float]]:
        return my_model.encode(texts)

Git workflow

  • Conventional commits with scope: feat(core): ..., fix(storage): ..., docs(rbac): ....
  • Never include Co-Authored-By, Generated by, or any AI attribution.
  • Tests required for every behavior change. Target 100% coverage on new code.
  • make test-all must pass before commit.

Boundaries

Always:

  • Use Protocol types (StorageBackend, Embedder, Parser) for pluggable surfaces.
  • Add tests alongside new behavior, and update tests when behavior changes.
  • Route inbound content through the Membrane.

Ask first:

  • Adding a new required dependency to pyproject.toml. Prefer optional extras.
  • Breaking a public surface: Vault / AsyncVault methods, CLI commands, REST endpoints.
  • Changing the on-disk storage schema or migration paths.

Never:

  • Introduce deprecated cryptography (see Style).
  • Add synchronous I/O to async code paths.
  • Change SHA3-256 CID derivation. Content addressability is an invariant.
  • Bypass the Membrane for inbound content.
  • Commit real user content as test fixtures.

Related