agentforge-memory-postgres 0.2.3__py3-none-any.whl

agentforge_memory_postgres/__init__.py

@@ -0,0 +1,19 @@
+"""AgentForge — Postgres + pgvector memory and vector drivers.
+
+Implements `MemoryStore` (claim audit log) and `VectorStore` (semantic
+search via pgvector) over Postgres via the official `asyncpg` driver.
+Sister package to `agentforge-memory-sqlite`; same locked contracts,
+same conformance suites.
+
+Per ADR-0014 every code path is async — uses `asyncpg`, never the
+sync `psycopg`, in agent code paths.
+"""
+
+from __future__ import annotations
+
+from agentforge_memory_postgres.memory import PostgresMemoryStore
+from agentforge_memory_postgres.vector import PostgresVectorStore
+
+__version__ = "0.2.3"
+
+__all__ = ["PostgresMemoryStore", "PostgresVectorStore", "__version__"]

agentforge_memory_postgres/_migrator.py

@@ -0,0 +1,153 @@
+"""`PostgresMigrator` — Postgres-side implementation of the feat-024
+:class:`agentforge_core.Migrator` Protocol.
+
+Migrations ship at
+``agentforge_memory_postgres/migrations/NNNN_<name>.sql``. The first
+migration (``0000_migrations_table.sql``) creates the
+``agentforge_migrations`` tracking table; subsequent migrations carry
+the actual schema deltas. Each migration is executed inside its own
+asyncpg transaction so a partial failure rolls back cleanly.
+
+The migrator consumes the existing :class:`PostgresRunner` Protocol
+so unit tests can inject the same fake the rest of the package uses.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from agentforge_core.contracts.migrator import (
+    Migration,
+    MigrationChecksumError,
+    MigrationStatus,
+)
+from agentforge_core.migrations import discover_migrations, render_migration_up
+
+from agentforge_memory_postgres._runner import PostgresRunner
+
+_MIGRATIONS_TABLE = "agentforge_migrations"
+
+_SELECT_APPLIED_SQL = (
+    f"SELECT id, name, checksum, applied_at "  # noqa: S608  # nosec B608
+    f"  FROM {_MIGRATIONS_TABLE} ORDER BY id"
+)
+_INSERT_APPLIED_SQL = (
+    f"INSERT INTO {_MIGRATIONS_TABLE} (id, name, checksum) "  # noqa: S608  # nosec B608
+    f"VALUES ($1, $2, $3)"
+)
+_TABLE_EXISTS_SQL = "SELECT to_regclass($1) IS NOT NULL AS exists_"  # type checker hint
+
+
+def _default_migrations_path() -> Path:
+    """Return the in-package migrations directory."""
+    return Path(__file__).parent / "migrations"
+
+
+class PostgresMigrator:
+    """Postgres implementation of :class:`agentforge_core.Migrator`.
+
+    Args:
+        runner: Live `PostgresRunner` (production or fake) — the
+            same one the rest of the driver uses.
+        migrations_path: Override for the in-package migrations
+            directory (test fixtures use this).
+    """
+
+    def __init__(
+        self,
+        runner: PostgresRunner,
+        *,
+        variables: dict[str, str] | None = None,
+        migrations_path: Path | None = None,
+    ) -> None:
+        self._r = runner
+        self._path = migrations_path or _default_migrations_path()
+        self._variables = variables
+        self._migrations: list[Migration] = discover_migrations(self._path, suffix="sql")
+
+    @property
+    def migrations(self) -> list[Migration]:
+        return list(self._migrations)
+
+    async def current_version(self) -> str | None:
+        if not await self._tracking_table_exists():
+            return None
+        rows = await self._r.fetch(_SELECT_APPLIED_SQL)
+        if not rows:
+            return None
+        return str(max(row["id"] for row in rows))
+
+    async def status(self) -> list[MigrationStatus]:
+        applied = await self._fetch_applied()
+        results: list[MigrationStatus] = []
+        for migration in self._migrations:
+            record = applied.get(migration.id)
+            if record is None:
+                results.append(
+                    MigrationStatus(
+                        migration=migration,
+                        applied=False,
+                        applied_at=None,
+                        checksum_match=False,
+                    )
+                )
+                continue
+            results.append(
+                MigrationStatus(
+                    migration=migration,
+                    applied=True,
+                    applied_at=record["applied_at"],
+                    checksum_match=record["checksum"] == migration.checksum,
+                )
+            )
+        return results
+
+    async def apply_pending(self) -> list[Migration]:
+        applied = await self._fetch_applied()
+
+        # Verify previously-applied migrations' checksums haven't drifted
+        # before applying anything new.
+        for migration in self._migrations:
+            record = applied.get(migration.id)
+            if record is not None and record["checksum"] != migration.checksum:
+                msg = (
+                    f"Postgres migration {migration.id}_{migration.name} "
+                    f"checksum drift: recorded {record['checksum']!r} but "
+                    f"file is now {migration.checksum!r}."
+                )
+                raise MigrationChecksumError(msg)
+
+        new_applied: list[Migration] = []
+        for migration in self._migrations:
+            if migration.id in applied:
+                continue
+            rendered = render_migration_up(migration.up, self._variables)
+            await self._r.execute(rendered)
+            await self._r.execute(
+                _INSERT_APPLIED_SQL,
+                migration.id,
+                migration.name,
+                migration.checksum,
+            )
+            new_applied.append(migration)
+        return new_applied
+
+    async def _tracking_table_exists(self) -> bool:
+        row = await self._r.fetchrow(_TABLE_EXISTS_SQL, _MIGRATIONS_TABLE)
+        if row is None:
+            return False
+        return bool(row["exists_"])
+
+    async def _fetch_applied(self) -> dict[str, dict[str, Any]]:
+        if not await self._tracking_table_exists():
+            return {}
+        rows = await self._r.fetch(_SELECT_APPLIED_SQL)
+        return {
+            str(row["id"]): {
+                "name": row["name"],
+                "checksum": row["checksum"],
+                "applied_at": row["applied_at"],
+            }
+            for row in rows
+        }

agentforge_memory_postgres/_runner.py

@@ -0,0 +1,135 @@
+"""Internal asyncpg-runner abstraction.
+
+Production stores wrap an `asyncpg.Pool`; unit tests inject a
+`PostgresFakeRunner` that interprets the SQL vocabulary the drivers
+emit and routes operations to in-memory backings. Every `*Store` in
+this package goes through the runner — never the pool directly — so
+the test boundary is a single interface.
+
+Per ADR-0014 every code path is async. Callers must `await close()`
+at shutdown to release the pool's pooled connections.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+from pgvector.asyncpg import register_vector
+
+
+class PostgresRunner(Protocol):
+    """Internal protocol — every SQL statement goes through one of these.
+
+    Mirrors a thin slice of `asyncpg.Connection` / `asyncpg.Pool`:
+
+      - `fetch` returns a list of rows (`asyncpg.Record`-like)
+      - `fetchrow` returns a single row or None
+      - `execute` runs a statement that doesn't return rows
+      - `executemany` runs a statement with a list of parameter tuples
+      - `close` releases the pool
+
+    The vector store also needs a `register_vector(conn)` hook on
+    each pooled connection so pgvector's codec is set up; the
+    production runner handles that on acquisition.
+    """
+
+    async def fetch(self, sql: str, *params: Any) -> list[Any]: ...
+
+    async def fetchrow(self, sql: str, *params: Any) -> Any | None: ...
+
+    async def execute(self, sql: str, *params: Any) -> None: ...
+
+    async def executemany(self, sql: str, args: list[tuple[Any, ...]]) -> None: ...
+
+    async def execute_returning_count(self, sql: str, *params: Any) -> int: ...
+
+    async def close(self) -> None: ...
+
+
+class _AsyncpgPoolRunner:
+    """Production runner — wraps an `asyncpg.Pool`.
+
+    Each call acquires a connection from the pool, runs the
+    statement, and releases. Mutating calls (`execute`,
+    `executemany`) wrap in an `async with conn.transaction():` block
+    so a failed statement doesn't leave partial state.
+
+    `setup_pgvector` should be True when this runner serves a
+    `PostgresVectorStore`, so each pooled connection registers the
+    pgvector codec on first acquisition.
+    """
+
+    def __init__(self, pool: Any, *, setup_pgvector: bool = False) -> None:
+        # `pool` is `asyncpg.Pool`; typed as Any because asyncpg ships
+        # without py.typed and the workspace mypy override strips its
+        # types.
+        self._pool = pool
+        self._setup_pgvector = setup_pgvector
+
+    async def fetch(self, sql: str, *params: Any) -> list[Any]:
+        async with self._pool.acquire() as conn:
+            await self._maybe_register_vector(conn)
+            return list(await conn.fetch(sql, *params))
+
+    async def fetchrow(self, sql: str, *params: Any) -> Any | None:
+        async with self._pool.acquire() as conn:
+            await self._maybe_register_vector(conn)
+            return await conn.fetchrow(sql, *params)
+
+    async def execute(self, sql: str, *params: Any) -> None:
+        async with self._pool.acquire() as conn:
+            await self._maybe_register_vector(conn)
+            async with conn.transaction():
+                await conn.execute(sql, *params)
+
+    async def executemany(self, sql: str, args: list[tuple[Any, ...]]) -> None:
+        async with self._pool.acquire() as conn:
+            await self._maybe_register_vector(conn)
+            async with conn.transaction():
+                await conn.executemany(sql, args)
+
+    async def execute_returning_count(self, sql: str, *params: Any) -> int:
+        """Execute a mutating statement and return the affected-row count.
+
+        asyncpg's `conn.execute` returns a status tag like
+        ``"DELETE 3"``; we parse the trailing integer. Used by
+        `MemoryStore.delete` to surface the deleted-row count back to
+        callers.
+        """
+        async with self._pool.acquire() as conn:
+            await self._maybe_register_vector(conn)
+            async with conn.transaction():
+                tag = await conn.execute(sql, *params)
+        return _parse_count(tag)
+
+    async def close(self) -> None:
+        await self._pool.close()
+
+    async def _maybe_register_vector(self, conn: Any) -> None:
+        """Register the pgvector codec on this connection (idempotent).
+
+        pgvector ships an asyncpg helper that teaches the codec how
+        to encode `list[float]` as the `vector` type and decode it
+        back. We call it lazily on first use of each pooled
+        connection — asyncpg caches type codecs per-connection so
+        this is cheap on subsequent calls.
+        """
+        if not self._setup_pgvector:
+            return
+        await register_vector(conn)
+
+
+def _parse_count(tag: Any) -> int:
+    """Extract the affected-row count from an asyncpg status tag."""
+    if not isinstance(tag, str):
+        return 0
+    parts = tag.rsplit(maxsplit=1)
+    if not parts:
+        return 0
+    try:
+        return int(parts[-1])
+    except ValueError:
+        return 0
+
+
+__all__ = ["PostgresRunner"]

agentforge_memory_postgres/memory.py

@@ -0,0 +1,296 @@
+"""`PostgresMemoryStore` — `MemoryStore` over Postgres via asyncpg.
+
+Single-table schema: every claim is one row keyed by `id` with
+project / agent / category / run_id / supersedes columns and a JSONB
+payload. Queries hit composite indices on the common filter
+combinations.
+
+`init_schema()` creates the table + indices via
+`CREATE TABLE IF NOT EXISTS`. Idempotent. No migration framework —
+the schema shape is pinned for v0.1; a future delta lands alongside
+schema-migrations support.
+
+Per ADR-0014 every code path is async (asyncpg, not psycopg).
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator
+from datetime import datetime
+from types import TracebackType
+from typing import Any, Self
+
+import asyncpg
+from agentforge_core.contracts.memory import MemoryStore
+from agentforge_core.production.exceptions import ModuleError
+from agentforge_core.values.claim import Claim
+
+from agentforge_memory_postgres._migrator import PostgresMigrator
+from agentforge_memory_postgres._runner import PostgresRunner, _AsyncpgPoolRunner
+
+# Table names are framework constants — never derived from user input.
+# All SQL composed from these constants is parameterised via asyncpg's
+# `$1, $2, ...` placeholders (no user input in f-strings). The S608 /
+# B608 noqa annotations below are explicit acknowledgements of that
+# fact, not relaxations of the lint surface.
+_CLAIMS_TABLE = "claims"
+
+_UPSERT_CLAIM_SQL = (
+    f"INSERT INTO {_CLAIMS_TABLE} "  # noqa: S608  # nosec B608
+    "(id, project, agent, run_id, category, payload, supersedes, created_at) "
+    "VALUES ($1, $2, $3, $4, $5, $6::jsonb, $7, $8) "
+    "ON CONFLICT (id) DO UPDATE SET "
+    "  project = EXCLUDED.project, agent = EXCLUDED.agent, "
+    "  run_id = EXCLUDED.run_id, category = EXCLUDED.category, "
+    "  payload = EXCLUDED.payload, supersedes = EXCLUDED.supersedes, "
+    "  created_at = EXCLUDED.created_at"
+)
+_SELECT_CLAIM_BY_ID = f"SELECT * FROM {_CLAIMS_TABLE} WHERE id = $1"  # noqa: S608  # nosec B608
+
+
+class PostgresMemoryStore(MemoryStore):
+    """Persistent `MemoryStore` backed by Postgres.
+
+    Use `from_dsn(dsn)` for ergonomic construction; the bare
+    constructor accepts an injected `PostgresRunner` so unit tests can
+    fake asyncpg without spinning up Postgres.
+    """
+
+    def __init__(self, *, runner: PostgresRunner) -> None:
+        self._r = runner
+
+    # ------------------------------------------------------------------
+    # Construction / lifecycle
+    # ------------------------------------------------------------------
+
+    @classmethod
+    async def from_dsn(
+        cls,
+        dsn: str,
+        *,
+        min_size: int = 1,
+        max_size: int = 10,
+    ) -> Self:
+        """Open an asyncpg pool against `dsn` and return a store."""
+        pool = await asyncpg.create_pool(dsn=dsn, min_size=min_size, max_size=max_size)
+        return cls(runner=_AsyncpgPoolRunner(pool))
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.close()
+
+    def migrator(self) -> PostgresMigrator:
+        """Return a `PostgresMigrator` configured against the
+        package's bundled migrations directory (feat-024)."""
+        return PostgresMigrator(self._r)
+
+    async def init_schema(self) -> None:
+        """Apply every bundled migration (idempotent). Opt-in.
+
+        Delegates to the feat-024 migration framework — schema
+        provisioning is now versioned + checksum-tracked. Older
+        deployments that previously called this method continue to
+        work; subsequent calls only apply pending migrations.
+
+        Skip for read-only workloads or when the schema is managed
+        externally; required before first write for full correctness.
+        """
+        await self.migrator().apply_pending()
+
+    async def close(self) -> None:
+        await self._r.close()
+
+    # ------------------------------------------------------------------
+    # MemoryStore contract
+    # ------------------------------------------------------------------
+
+    async def put(self, claim: Claim) -> str:
+        await self._r.execute(
+            _UPSERT_CLAIM_SQL,
+            claim.id,
+            claim.project,
+            claim.agent,
+            claim.run_id,
+            claim.category,
+            json.dumps(claim.payload),
+            claim.supersedes,
+            claim.created_at,
+        )
+        return claim.id
+
+    async def get(self, claim_id: str) -> Claim | None:
+        row = await self._r.fetchrow(_SELECT_CLAIM_BY_ID, claim_id)
+        if row is None:
+            return None
+        return _row_to_claim(row)
+
+    async def query(
+        self,
+        *,
+        project: str | None = None,
+        agent: str | None = None,
+        category: str | None = None,
+        run_id: str | None = None,
+        limit: int = 100,
+    ) -> list[Claim]:
+        sql, params = _build_filter_sql(
+            project=project,
+            agent=agent,
+            category=category,
+            run_id=run_id,
+            limit=limit,
+        )
+        rows = await self._r.fetch(sql, *params)
+        return [_row_to_claim(r) for r in rows]
+
+    async def supersede(self, old_id: str, new_claim: Claim) -> str:
+        existing = await self.get(old_id)
+        if existing is None:
+            msg = f"Cannot supersede unknown claim id: {old_id!r}"
+            raise ModuleError(msg)
+        if new_claim.supersedes is None:
+            new_claim = new_claim.model_copy(update={"supersedes": old_id})
+        elif new_claim.supersedes != old_id:
+            msg = f"new_claim.supersedes={new_claim.supersedes!r} does not match old_id={old_id!r}"
+            raise ModuleError(msg)
+        return await self.put(new_claim)
+
+    def stream(
+        self,
+        *,
+        project: str | None = None,
+        agent: str | None = None,
+        category: str | None = None,
+        run_id: str | None = None,
+    ) -> AsyncIterator[Claim]:
+        sql, params = _build_filter_sql(
+            project=project,
+            agent=agent,
+            category=category,
+            run_id=run_id,
+            limit=None,
+        )
+
+        async def _agen() -> AsyncIterator[Claim]:
+            rows = await self._r.fetch(sql, *params)
+            for r in rows:
+                yield _row_to_claim(r)
+
+        return _agen()
+
+    async def delete(
+        self,
+        *,
+        run_id: str | None = None,
+        older_than: datetime | None = None,
+        category: str | None = None,
+    ) -> int:
+        if run_id is None and older_than is None and category is None:
+            msg = "delete() requires at least one filter; refusing to wipe every claim."
+            raise ModuleError(msg)
+        where: list[str] = []
+        params: list[Any] = []
+        next_idx = 1
+        if run_id is not None:
+            where.append(f"run_id = ${next_idx}")
+            params.append(run_id)
+            next_idx += 1
+        if category is not None:
+            where.append(f"category = ${next_idx}")
+            params.append(category)
+            next_idx += 1
+        if older_than is not None:
+            where.append(f"created_at < ${next_idx}")
+            params.append(older_than)
+            next_idx += 1
+        sql = f"DELETE FROM {_CLAIMS_TABLE} WHERE " + " AND ".join(  # noqa: S608  # nosec B608
+            where,
+        )
+        return await self._r.execute_returning_count(sql, *params)
+
+    def capabilities(self) -> set[str]:
+        return {"transactions"}
+
+
+# ----------------------------------------------------------------------
+# Helpers
+# ----------------------------------------------------------------------
+
+
+def _row_to_claim(row: Any) -> Claim:
+    """Convert an asyncpg row (dict-like) into a `Claim`.
+
+    asyncpg returns `Record` objects which support `row["col"]`. JSONB
+    payloads come back already-parsed when the column is declared
+    `jsonb`; for the dict-codec edge case we fall back to
+    `json.loads`.
+    """
+    payload = row["payload"]
+    if isinstance(payload, str):
+        payload = json.loads(payload)
+    created = row["created_at"]
+    if isinstance(created, str):
+        created = datetime.fromisoformat(created)
+    return Claim(
+        id=row["id"],
+        project=row["project"],
+        agent=row["agent"],
+        run_id=row["run_id"],
+        category=row["category"],
+        payload=payload,
+        supersedes=row["supersedes"],
+        created_at=created,
+    )
+
+
+def _build_filter_sql(
+    *,
+    project: str | None,
+    agent: str | None,
+    category: str | None,
+    run_id: str | None,
+    limit: int | None,
+) -> tuple[str, tuple[Any, ...]]:
+    """Compose a SELECT with conjunctive filters and an optional LIMIT.
+
+    Emits asyncpg's `$1, $2, ...` placeholders (numbered positionally,
+    not the `?` aiosqlite uses).
+    """
+    where: list[str] = []
+    params: list[Any] = []
+    next_idx = 1
+
+    def _add(column: str, value: Any) -> None:
+        nonlocal next_idx
+        where.append(f"{column} = ${next_idx}")
+        params.append(value)
+        next_idx += 1
+
+    if project is not None:
+        _add("project", project)
+    if agent is not None:
+        _add("agent", agent)
+    if category is not None:
+        _add("category", category)
+    if run_id is not None:
+        _add("run_id", run_id)
+
+    sql = f"SELECT * FROM {_CLAIMS_TABLE}"  # noqa: S608  # nosec B608
+    if where:
+        sql += " WHERE " + " AND ".join(where)
+    sql += " ORDER BY created_at"
+    if limit is not None:
+        sql += f" LIMIT ${next_idx}"
+        params.append(limit)
+    return sql, tuple(params)
+
+
+__all__ = ["PostgresMemoryStore"]

agentforge_memory_postgres/migrations/0000_migrations_table.sql

@@ -0,0 +1,6 @@
+CREATE TABLE IF NOT EXISTS agentforge_migrations (
+    id          TEXT PRIMARY KEY,
+    name        TEXT NOT NULL,
+    checksum    TEXT NOT NULL,
+    applied_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);

agentforge_memory_postgres/migrations/0001_initial.sql

@@ -0,0 +1,13 @@
+CREATE TABLE IF NOT EXISTS claims (
+    id         TEXT PRIMARY KEY,
+    project    TEXT NOT NULL,
+    agent      TEXT NOT NULL,
+    run_id     TEXT NOT NULL,
+    category   TEXT NOT NULL,
+    payload    JSONB NOT NULL,
+    supersedes TEXT,
+    created_at TIMESTAMPTZ NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_claims_project_agent ON claims(project, agent);
+CREATE INDEX IF NOT EXISTS idx_claims_run_id ON claims(run_id);
+CREATE INDEX IF NOT EXISTS idx_claims_category ON claims(category);

agentforge_memory_postgres/migrations/vector/0000_migrations_table.sql

@@ -0,0 +1,6 @@
+CREATE TABLE IF NOT EXISTS agentforge_migrations (
+    id          TEXT PRIMARY KEY,
+    name        TEXT NOT NULL,
+    checksum    TEXT NOT NULL,
+    applied_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);

agentforge_memory_postgres/migrations/vector/0100_vectors.sql

@@ -0,0 +1,14 @@
+CREATE EXTENSION IF NOT EXISTS vector;
+CREATE TABLE IF NOT EXISTS vectors (
+    id        TEXT PRIMARY KEY,
+    embedding vector(${dimensions}) NOT NULL,
+    text      TEXT NOT NULL,
+    metadata  JSONB NOT NULL DEFAULT '{}'::jsonb
+);
+CREATE INDEX IF NOT EXISTS idx_vectors_embedding
+    ON vectors USING hnsw (embedding vector_cosine_ops);
+ALTER TABLE vectors
+    ADD COLUMN IF NOT EXISTS embedding_tsv tsvector
+    GENERATED ALWAYS AS (to_tsvector('english', coalesce(text, ''))) STORED;
+CREATE INDEX IF NOT EXISTS idx_vectors_tsv
+    ON vectors USING gin (embedding_tsv);

agentforge_memory_postgres/vector.py

@@ -0,0 +1,293 @@
+"""`PostgresVectorStore` — `VectorStore` over Postgres + pgvector.
+
+Vectors are stored in a `vectors` table with a typed `vector(N)`
+column. With `init_schema()` provisioned, an HNSW index accelerates
+similarity search via pgvector's cosine-distance operator `<=>`;
+without bootstrap the driver still works (sequential cosine scan)
+but doesn't claim `native_ann`.
+
+Score conversion: pgvector's `<=>` returns cosine *distance* in
+`[0, 2]` (0 = identical, 1 = orthogonal, 2 = anti-correlated).
+The locked contract requires similarity in `[0, 1]` (1 = identical,
+0 = orthogonal-or-anti-correlated). We compute
+`GREATEST(0.0, 1.0 - (embedding <=> $1))` at the SQL boundary so
+cross-driver comparisons remain meaningful.
+
+Per ADR-0014 every code path is async (asyncpg, not psycopg).
+"""
+
+from __future__ import annotations
+
+import json
+from types import TracebackType
+from typing import Any, Self
+
+import asyncpg
+from agentforge_core.contracts.vector_store import VectorStore
+from agentforge_core.values.vector import VectorItem, VectorMatch
+
+from agentforge_memory_postgres._migrator import PostgresMigrator
+from agentforge_memory_postgres._runner import PostgresRunner, _AsyncpgPoolRunner
+
+# Table is a framework constant; all SQL composed from it is
+# parameterised via asyncpg's `$1, $2, ...` placeholders. The S608 /
+# B608 noqa annotations below are explicit acknowledgements of that.
+_VECTORS_TABLE = "vectors"
+
+_UPSERT_VECTOR_SQL = (
+    f"INSERT INTO {_VECTORS_TABLE} (id, embedding, text, metadata) "  # noqa: S608  # nosec B608
+    "VALUES ($1, $2, $3, $4::jsonb) "
+    "ON CONFLICT (id) DO UPDATE SET "
+    "  embedding = EXCLUDED.embedding, "
+    "  text = EXCLUDED.text, "
+    "  metadata = EXCLUDED.metadata"
+)
+_SELECT_EXISTING_IDS = f"SELECT id FROM {_VECTORS_TABLE} WHERE id = ANY($1::text[])"  # noqa: S608  # nosec B608
+_DELETE_VECTORS_BY_IDS = f"DELETE FROM {_VECTORS_TABLE} WHERE id = ANY($1::text[])"  # noqa: S608  # nosec B608
+_SEARCH_VECTORS_SQL = (
+    f"SELECT id, text, metadata, "  # noqa: S608  # nosec B608
+    f"       GREATEST(0.0, 1.0 - (embedding <=> $1)) AS score "
+    f"  FROM {_VECTORS_TABLE} "
+    f" WHERE metadata @> $2::jsonb "
+    f" ORDER BY embedding <=> $1 "
+    f" LIMIT $3"
+)
+_LEXICAL_SEARCH_SQL = (
+    f"WITH ranked AS ("  # noqa: S608  # nosec B608
+    f"  SELECT id, text, metadata, "
+    f"         ts_rank_cd(embedding_tsv, plainto_tsquery('english', $1)) AS raw "
+    f"    FROM {_VECTORS_TABLE} "
+    f"   WHERE embedding_tsv @@ plainto_tsquery('english', $1) "
+    f"     AND metadata @> $2::jsonb "
+    f"   ORDER BY raw DESC "
+    f"   LIMIT $3"
+    f") "
+    f"SELECT id, text, metadata, "
+    f"       CASE WHEN MAX(raw) OVER () > 0 "
+    f"            THEN raw / MAX(raw) OVER () "
+    f"            ELSE 0.0 "
+    f"       END AS score "
+    f"  FROM ranked "
+    f" ORDER BY raw DESC"
+)
+
+
+class PostgresVectorStore(VectorStore):
+    """`VectorStore` over Postgres + pgvector. Dimensions pinned at
+    construction.
+
+    Use `from_dsn(dsn, dimensions=N)` for ergonomic construction; the
+    bare constructor accepts an injected `PostgresRunner` so unit tests
+    can fake asyncpg without spinning up Postgres.
+    """
+
+    def __init__(
+        self,
+        *,
+        runner: PostgresRunner,
+        dimensions: int,
+        ann_indexed: bool = False,
+    ) -> None:
+        if dimensions < 1:
+            msg = f"dimensions must be >= 1, got {dimensions}"
+            raise ValueError(msg)
+        self._r = runner
+        self._dim = dimensions
+        self._ann = ann_indexed
+
+    # ------------------------------------------------------------------
+    # Construction / lifecycle
+    # ------------------------------------------------------------------
+
+    @classmethod
+    async def from_dsn(
+        cls,
+        dsn: str,
+        *,
+        dimensions: int,
+        min_size: int = 1,
+        max_size: int = 10,
+    ) -> Self:
+        """Open an asyncpg pool and return a vector store with the
+        pgvector codec registered on every pooled connection."""
+        pool = await asyncpg.create_pool(dsn=dsn, min_size=min_size, max_size=max_size)
+        return cls(
+            runner=_AsyncpgPoolRunner(pool, setup_pgvector=True),
+            dimensions=dimensions,
+        )
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.close()
+
+    def migrator(self) -> PostgresMigrator:
+        """Return a `PostgresMigrator` pre-configured with the
+        ``dimensions`` template variable + the vector-store
+        migrations subdirectory (feat-024 v0.3 follow-up).
+
+        The vector migrations use ``vector(${dimensions})`` placeholders
+        that the migrator renders at apply time. Checksums are
+        computed over the un-substituted template, so re-deploying
+        with a different `dimensions` value doesn't trigger drift
+        detection.
+
+        Migration files live under
+        ``migrations/vector/`` (vector-store specific; id range
+        0100-0199); the shared ``0000_migrations_table`` bootstraps
+        the tracking table the first time any store applies it.
+        """
+        from pathlib import Path  # noqa: PLC0415
+
+        path = Path(__file__).parent / "migrations" / "vector"
+        return PostgresMigrator(
+            self._r,
+            variables={"dimensions": str(self._dim)},
+            migrations_path=path,
+        )
+
+    async def init_schema(self) -> None:
+        """Provision the vectors table + HNSW index + feat-022
+        tsvector column via the migration framework (feat-024).
+        Idempotent.
+
+        After this returns, the store declares the `"native_ann"`
+        and `"hybrid_search"` capabilities — the indexes are in
+        place. Skip this for read-only workloads or when the schema
+        is managed externally.
+        """
+        await self.migrator().apply_pending()
+        self._ann = True
+
+    async def close(self) -> None:
+        await self._r.close()
+
+    def dimensions(self) -> int:
+        return self._dim
+
+    # ------------------------------------------------------------------
+    # VectorStore contract
+    # ------------------------------------------------------------------
+
+    async def upsert(self, items: list[VectorItem]) -> None:
+        for item in items:
+            if len(item.vector) != self._dim:
+                msg = (
+                    f"vector for id={item.id!r} has length {len(item.vector)} "
+                    f"but store dimensions={self._dim}"
+                )
+                raise ValueError(msg)
+            await self._r.execute(
+                _UPSERT_VECTOR_SQL,
+                item.id,
+                list(item.vector),
+                item.text,
+                json.dumps(dict(item.metadata)),
+            )
+
+    async def search(
+        self,
+        query_vector: tuple[float, ...],
+        *,
+        limit: int = 5,
+        filter_metadata: dict[str, Any] | None = None,
+    ) -> list[VectorMatch]:
+        if limit < 1:
+            msg = f"limit must be >= 1, got {limit}"
+            raise ValueError(msg)
+        if len(query_vector) != self._dim:
+            msg = f"query vector has length {len(query_vector)} but store dimensions={self._dim}"
+            raise ValueError(msg)
+
+        # The `metadata @> $2::jsonb` predicate is conjunctive: every
+        # key/value in `filter_metadata` must be present in the row's
+        # JSONB. Empty filter (`{}`) matches everything.
+        rows = await self._r.fetch(
+            _SEARCH_VECTORS_SQL,
+            list(query_vector),
+            json.dumps(dict(filter_metadata or {})),
+            limit,
+        )
+        return [
+            VectorMatch(
+                id=str(row["id"]),
+                text=str(row["text"]),
+                metadata=_ensure_dict(row["metadata"]),
+                score=float(row["score"]),
+            )
+            for row in rows
+        ]
+
+    async def lexical_search(
+        self,
+        query: str,
+        *,
+        limit: int = 5,
+        filter_metadata: dict[str, Any] | None = None,
+    ) -> list[VectorMatch]:
+        if limit < 1:
+            msg = f"limit must be >= 1, got {limit}"
+            raise ValueError(msg)
+        if not self._ann:
+            msg = (
+                "PostgresVectorStore.lexical_search requires init_schema() "
+                "to have run (the embedding_tsv column + GIN index live "
+                "alongside the HNSW vector index)."
+            )
+            raise RuntimeError(msg)
+        rows = await self._r.fetch(
+            _LEXICAL_SEARCH_SQL,
+            query,
+            json.dumps(dict(filter_metadata or {})),
+            limit,
+        )
+        return [
+            VectorMatch(
+                id=str(row["id"]),
+                text=str(row["text"]),
+                metadata=_ensure_dict(row["metadata"]),
+                score=float(row["score"]),
+            )
+            for row in rows
+        ]
+
+    async def delete(self, ids: list[str]) -> int:
+        if not ids:
+            return 0
+        existing_rows = await self._r.fetch(_SELECT_EXISTING_IDS, list(ids))
+        existing = {str(r["id"]) for r in existing_rows}
+        if not existing:
+            return 0
+        await self._r.execute(_DELETE_VECTORS_BY_IDS, list(existing))
+        return len(existing)
+
+    def capabilities(self) -> set[str]:
+        """`native_ann` + `hybrid_search` are both declared **only**
+        after `init_schema()` provisions the HNSW + GIN indexes.
+        Without bootstrap the driver still does cosine search as a
+        brute-force fallback, but lexical search would fail — so the
+        capability vocabulary stays honest per ADR-0009."""
+        caps: set[str] = set()
+        if self._ann:
+            caps.add("native_ann")
+            caps.add("hybrid_search")
+        return caps
+
+
+def _ensure_dict(value: Any) -> dict[str, Any]:
+    """asyncpg returns JSONB as parsed Python objects via its codec;
+    str fallback covers the (uncommon) raw-text path."""
+    if isinstance(value, dict):
+        return value
+    if isinstance(value, str):
+        return dict(json.loads(value)) if value else {}
+    return {}
+
+
+__all__ = ["PostgresVectorStore"]

agentforge_memory_postgres-0.2.3.dist-info/METADATA

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: agentforge-memory-postgres
+Version: 0.2.3
+Summary: Postgres + pgvector-backed MemoryStore and VectorStore for AgentForge
+Project-URL: Homepage, https://github.com/Scaffoldic/agentforge-py
+Project-URL: Repository, https://github.com/Scaffoldic/agentforge-py
+Project-URL: Documentation, https://github.com/Scaffoldic/agentforge-py
+Project-URL: Changelog, https://github.com/Scaffoldic/agentforge-py/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/Scaffoldic/agentforge-py/issues
+Author: The AgentForge Authors
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agent,ai,memory,pgvector,postgres,rag,vector
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: agentforge-core~=0.2.3
+Requires-Dist: asyncpg>=0.30
+Requires-Dist: pgvector>=0.3
+Description-Content-Type: text/markdown
+
+# agentforge-memory-postgres
+
+Postgres + [pgvector](https://github.com/pgvector/pgvector)-backed
+`MemoryStore` and `VectorStore` for the AgentForge framework.
+
+## What this is
+
+Sister package to `agentforge-memory-sqlite`. Same locked contracts,
+same conformance suites — but backed by Postgres with `asyncpg` for
+real-world scale, multi-writer concurrency, and managed-database
+guarantees (RDS, Neon, Supabase, etc.).
+
+- **`PostgresMemoryStore`** — claim audit log over a single `claims`
+  table with composite indices on common filter combinations
+  (`project, agent`, `run_id`, `category`).
+- **`PostgresVectorStore`** — semantic search over a `vectors` table
+  with a pgvector HNSW index (`vector_cosine_ops`). Cosine distance
+  is converted to clamped `[0, 1]` similarity at the SQL boundary
+  per the locked `VectorStore` contract.
+
+Both pass `agentforge_core.testing.run_memory_conformance` and
+`run_vector_conformance` against a real Postgres (gated on
+`RUN_LIVE_POSTGRES=1` in CI; always on locally via docker compose).
+
+## Usage
+
+```python
+from agentforge_memory_postgres import PostgresMemoryStore, PostgresVectorStore
+
+dsn = "postgresql://postgres:postgres@localhost:5432/agentforge"
+
+async with PostgresMemoryStore.from_dsn(dsn) as memory:
+    await memory.init_schema()                # idempotent
+    ...
+
+async with PostgresVectorStore.from_dsn(dsn, dimensions=1024) as vectors:
+    await vectors.init_schema()               # provisions HNSW index
+    ...
+```
+
+`init_schema()` is opt-in (idempotent `CREATE TABLE / EXTENSION /
+INDEX IF NOT EXISTS`). Skip it for read-only workloads or when the
+schema is managed externally; required before first write for full
+correctness.
+
+## Local development
+
+```bash
+docker compose -f docker-compose.dev.yml up -d
+RUN_LIVE_POSTGRES=1 \
+  POSTGRES_URL=postgresql://postgres:postgres@localhost:5432/agentforge \
+  uv run pytest packages/agentforge-memory-postgres/tests/integration -v
+```
+
+The compose file ships `pgvector/pgvector:pg16`, which bundles
+Postgres 16 with the pgvector extension preinstalled.
+
+## Capabilities
+
+- **Memory**: `{"transactions"}` — every `put` / `supersede` runs
+  inside an asyncpg transaction.
+- **Vector**: `{"native_ann"}` is declared **only** after
+  `init_schema()` provisions the HNSW index. Without bootstrap the
+  driver still works (sequential cosine scan), but it doesn't claim
+  ANN — the capability vocabulary is honest per ADR-0009.

agentforge_memory_postgres-0.2.3.dist-info/RECORD

@@ -0,0 +1,15 @@
+agentforge_memory_postgres/__init__.py,sha256=liNKxye7Ytd3JJmOZu3_njqM59UDjSl-9r_2ACK1ASI,676
+agentforge_memory_postgres/_migrator.py,sha256=1IbtqvtUFRWhVX-3tbkAi-Jw8pKcuFfa_zkfVXx0W3o,5374
+agentforge_memory_postgres/_runner.py,sha256=BtFTmDjJelNhfUIcDmVUgu3ojzfv92TGcO49Ea8TjD8,4994
+agentforge_memory_postgres/memory.py,sha256=5rL_wT0Qct8Gl5mmCMXjwQi0Je5S2g1woEX_7t_p7ec,9765
+agentforge_memory_postgres/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agentforge_memory_postgres/vector.py,sha256=vF46PdYENZFYc60LTnVTgOfM1bEmyIZZXyUEq1SgecM,10323
+agentforge_memory_postgres/migrations/0000_migrations_table.sql,sha256=VoCG5tsQp7pBTaLXqshq2NwB-Tf-jh2gjQi8jxx9ec0,201
+agentforge_memory_postgres/migrations/0001_initial.sql,sha256=sjcximXWjCitCTvZcF6asKvq3xIGzig35smioEwcuUM,491
+agentforge_memory_postgres/migrations/vector/0000_migrations_table.sql,sha256=VoCG5tsQp7pBTaLXqshq2NwB-Tf-jh2gjQi8jxx9ec0,201
+agentforge_memory_postgres/migrations/vector/0100_vectors.sql,sha256=exodIYuVSclbmgpZKgBD0HRjHu99sa-OhCYPJdMcIt8,575
+agentforge_memory_postgres-0.2.3.dist-info/METADATA,sha256=mIrXu31h0vEPbdAtr57lI7Fw67ciEviuFTlW8yzbdN8,3643
+agentforge_memory_postgres-0.2.3.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+agentforge_memory_postgres-0.2.3.dist-info/entry_points.txt,sha256=LQBCkv2EKz3L2dsQgTKPbrh7AYq4KjL5HlPPXpvA5O4,178
+agentforge_memory_postgres-0.2.3.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+agentforge_memory_postgres-0.2.3.dist-info/RECORD,,

agentforge_memory_postgres-0.2.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agentforge_memory_postgres-0.2.3.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[agentforge.memory]
+postgres = agentforge_memory_postgres.memory:PostgresMemoryStore
+
+[agentforge.vector_stores]
+postgres = agentforge_memory_postgres.vector:PostgresVectorStore

agentforge_memory_postgres-0.2.3.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.