orchid-storage-postgres 1.0.0__tar.gz

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

@@ -0,0 +1,156 @@
+# orchid-storage-postgres — CI + Semantic Release + PyPI Publish
+
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  # ── Lint ────────────────────────────────────────────────────
+
+  ruff:
+    name: Ruff lint & format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install ruff
+      - run: ruff check orchid_storage_postgres/
+      - run: ruff format --check orchid_storage_postgres/
+
+  # ── Test ────────────────────────────────────────────────────
+
+  test:
+    name: Tests + coverage
+    runs-on: ubuntu-latest
+    needs: [ruff]
+    permissions:
+      contents: read
+      pull-requests: write
+    strategy:
+      matrix:
+        python-version: ['3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - run: pip install -e ".[dev]" pytest-cov
+      - name: Run tests
+        run: |
+          pytest tests/ \
+            --cov=orchid_storage_postgres \
+            --cov-report=term-missing \
+            --cov-report=xml:coverage.xml \
+            --junitxml=report.xml \
+            -x
+      - name: Upload coverage
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage
+          path: coverage.xml
+          if-no-files-found: ignore
+      - name: Upload test report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-report
+          path: report.xml
+          if-no-files-found: ignore
+      - name: Coverage summary
+        if: hashFiles('coverage.xml') != ''
+        uses: irongut/CodeCoverageSummary@v1.3.0
+        with:
+          filename: "**/coverage.xml"
+          format: markdown
+          output: both
+          badge: true
+          fail_below_min: false
+          thresholds: "50 75"
+      - name: Add coverage PR comment
+        if: github.event_name == 'pull_request' && hashFiles('code-coverage-results.md') != ''
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          header: coverage
+          path: code-coverage-results.md
+
+  # ── Build ───────────────────────────────────────────────────
+
+  build:
+    name: Build wheel
+    runs-on: ubuntu-latest
+    needs: [ruff, test]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 7
+
+  # ── Release + PyPI Publish (on main push) ───────────────────
+
+  release:
+    name: Release & publish
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    needs: [ruff, test, build]
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install python-semantic-release build
+      - name: Configure git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+      - name: Bump version & tag
+        id: version
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          before=$(python -c "import re,pathlib; c=pathlib.Path('orchid_storage_postgres/__init__.py').read_text(); m=re.search(r'__version__\s*=\s*\"([^\"]+)\"', c); print(m.group(1))")
+          semantic-release version --push --tag --commit || true
+          after=$(python -c "import re,pathlib; c=pathlib.Path('orchid_storage_postgres/__init__.py').read_text(); m=re.search(r'__version__\s*=\s*\"([^\"]+)\"', c); print(m.group(1))")
+          echo "before=$before"
+          echo "after=$after"
+          if [ "$before" = "$after" ]; then
+            echo "No version bump — skipping publish steps."
+            echo "released=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "Bumped $before → $after."
+            echo "released=true" >> "$GITHUB_OUTPUT"
+          fi
+      - name: Build distribution
+        if: steps.version.outputs.released == 'true'
+        run: python -m build
+      - name: Publish GitHub Release
+        if: steps.version.outputs.released == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: semantic-release publish
+      - name: Publish to PyPI
+        if: steps.version.outputs.released == 'true'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

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

@@ -0,0 +1,11 @@
+# Pre-commit hooks — run automatically before each commit
+# Install: pip install pre-commit && pre-commit install
+# Manual:  pre-commit run --all-files
+
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.10
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format

orchid_storage_postgres-1.0.0/AGENTS.md

@@ -0,0 +1,59 @@
+# orchid-storage-postgres — AI Context
+
+## What This Package Is
+
+`orchid-storage-postgres` is the PostgreSQL storage plugin for the Orchid AI
+framework. It provides:
+
+- `OrchidPostgresChatStorage` — implements `OrchidChatStorage` backed by asyncpg
+- PostgreSQL schema migration (v001) with all framework-owned tables
+- PostgreSQL visibility fragment for `build_run_filter_clause` ($1..$N params)
+
+## Auto-Registration
+
+The package registers itself via Python `importlib.metadata` entry points:
+
+```toml
+[project.entry-points."orchid.visibility_fragments"]
+postgres = "orchid_storage_postgres:_register"
+```
+
+No manual `register_visibility_fragment()` calls are needed by integrators.
+
+The chat storage is NOT auto-registered — consumers reference it via
+dotted class path in their YAML config:
+
+```yaml
+storage:
+  class: orchid_storage_postgres.chat_storage.OrchidPostgresChatStorage
+  dsn: postgresql://...
+```
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `chat_storage.py` | `OrchidPostgresChatStorage` + row mappers |
+| `migrations.py` | `PostgresMigrationRunner` + v001 DDL |
+| `visibility.py` | `_build_postgres_filter` (asyncpg $1..$N params) |
+| `__init__.py` | Entry-point `_register()` callable |
+
+## Testing
+
+Tests require `asyncpg` but do **not** require a live PostgreSQL server —
+all unit tests mock `asyncpg.create_pool`.
+
+```bash
+cd orchid-storage-postgres
+pip install -e ".[dev]"
+pytest tests/ -x
+```
+
+## Common Pitfalls
+
+- `asyncpg` uses `$1..$N` positional parameters, NOT `%s` or `:name` style.
+- `agents_used` and `metadata` columns in `chat_messages` are stored as
+  `JSONB` objects in PostgreSQL.  The row mapper handles both string and
+  already-parsed representations.
+- The plugin schema migration creates ALL framework-owned tables
+  (chat, MCP, events), not just chat tables.

orchid_storage_postgres-1.0.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## [Unreleased]
+
+## [1.0.0] - TBD
+
+### Added
+
+- `OrchidPostgresChatStorage` extracted from `orchid-ai` core.
+- PostgreSQL schema migration (v001) with all framework-owned tables.
+- PostgreSQL visibility fragment for `build_run_filter_clause`.
+- Auto-registration for `orchid.visibility_fragments` entry-point group.

orchid_storage_postgres-1.0.0/LICENSE

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

orchid_storage_postgres-1.0.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: orchid-storage-postgres
+Version: 1.0.0
+Summary: PostgreSQL storage backend plugin for the Orchid AI framework
+Project-URL: Homepage, https://github.com/gadz82/orchid-storage-postgres
+Project-URL: Issues, https://github.com/gadz82/orchid-storage-postgres/issues
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,asyncpg,postgresql,storage
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: asyncpg>=0.29.0
+Requires-Dist: langgraph-checkpoint-postgres>=2.0.0
+Requires-Dist: orchid-ai>=1.8.2
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.25.0; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# orchid-storage-postgres
+
+PostgreSQL storage backend plugin for the [Orchid AI](https://github.com/gadz82/orchid) framework.
+
+## What it provides
+
+- `OrchidPostgresChatStorage` — implements `OrchidChatStorage` backed by PostgreSQL (asyncpg)
+- PostgreSQL visibility fragment for `build_run_filter_clause`
+- PostgreSQL schema migration (v001)
+
+## Installation
+
+```bash
+pip install orchid-storage-postgres
+```
+
+## Usage
+
+Reference in your `orchid.yml`:
+
+```yaml
+storage:
+  class: orchid_storage_postgres.chat_storage.OrchidPostgresChatStorage
+  dsn: postgresql://user:pass@localhost:5432/orchid
+```
+
+Or build it programmatically:
+
+```python
+from orchid_storage_postgres import OrchidPostgresChatStorage
+
+storage = OrchidPostgresChatStorage(dsn="postgresql://user:pass@localhost:5432/orchid")
+await storage.init_db()
+```
+
+## Development
+
+```bash
+cd orchid-storage-postgres
+pip install -e ".[dev]"
+pytest tests/ -x
+ruff check orchid_storage_postgres/
+```
+
+## License
+
+MIT

orchid_storage_postgres-1.0.0/README.md

@@ -0,0 +1,47 @@
+# orchid-storage-postgres
+
+PostgreSQL storage backend plugin for the [Orchid AI](https://github.com/gadz82/orchid) framework.
+
+## What it provides
+
+- `OrchidPostgresChatStorage` — implements `OrchidChatStorage` backed by PostgreSQL (asyncpg)
+- PostgreSQL visibility fragment for `build_run_filter_clause`
+- PostgreSQL schema migration (v001)
+
+## Installation
+
+```bash
+pip install orchid-storage-postgres
+```
+
+## Usage
+
+Reference in your `orchid.yml`:
+
+```yaml
+storage:
+  class: orchid_storage_postgres.chat_storage.OrchidPostgresChatStorage
+  dsn: postgresql://user:pass@localhost:5432/orchid
+```
+
+Or build it programmatically:
+
+```python
+from orchid_storage_postgres import OrchidPostgresChatStorage
+
+storage = OrchidPostgresChatStorage(dsn="postgresql://user:pass@localhost:5432/orchid")
+await storage.init_db()
+```
+
+## Development
+
+```bash
+cd orchid-storage-postgres
+pip install -e ".[dev]"
+pytest tests/ -x
+ruff check orchid_storage_postgres/
+```
+
+## License
+
+MIT

orchid_storage_postgres-1.0.0/orchid_storage_postgres/__init__.py

@@ -0,0 +1,48 @@
+"""PostgreSQL storage plugin for the Orchid AI framework.
+
+Provides ``OrchidPostgresChatStorage``, a PostgreSQL visibility
+fragment, and a PostgreSQL checkpointer.  Auto-registers via
+``importlib.metadata`` entry points.
+"""
+
+from __future__ import annotations
+
+import logging
+
+__version__ = "1.0.0"
+
+from .chat_storage import OrchidPostgresChatStorage
+from .visibility import _build_postgres_filter
+
+__all__ = ["OrchidPostgresChatStorage"]
+
+logger = logging.getLogger(__name__)
+
+
+async def _build_postgres_checkpointer(dsn: str):
+    """Build an async PostgreSQL checkpointer from a DSN."""
+    from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver
+
+    checkpointer = AsyncPostgresSaver.from_conn_string(dsn)
+    await checkpointer.setup()
+    logger.info("[orchid-storage-postgres] Checkpointer ready")
+    return checkpointer
+
+
+def _register() -> None:
+    """Entry-point callable — registers the postgres visibility fragment and checkpointer."""
+    try:
+        from orchid_ai.events.visibility import register_visibility_fragment
+
+        register_visibility_fragment("postgres", _build_postgres_filter)
+        logger.debug("[orchid-storage-postgres] Registered visibility fragment")
+    except ImportError:
+        logger.debug("[orchid-storage-postgres] Skipping visibility fragment (not in this orchid-ai version)")
+
+    try:
+        from orchid_ai.checkpointing.factory import register_checkpointer
+
+        register_checkpointer("postgres", _build_postgres_checkpointer)
+        logger.debug("[orchid-storage-postgres] Registered checkpointer")
+    except ImportError:
+        logger.debug("[orchid-storage-postgres] Skipping checkpointer (not in this orchid-ai version)")

orchid_storage_postgres-1.0.0/orchid_storage_postgres/chat_storage.py

@@ -0,0 +1,249 @@
+"""
+PostgreSQL chat storage — production-grade :class:`OrchidChatStorage` backend.
+
+Backed by ``asyncpg`` with connection pooling.  Implements every
+:class:`OrchidChatStorage` method using ``$1..$N`` placeholders.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import uuid
+from datetime import datetime
+from typing import Any
+
+from orchid_ai.persistence.base import OrchidChatStorage
+from orchid_ai.persistence.models import OrchidChatMessage, OrchidChatSession, utcnow
+
+from .migrations import PostgresMigrationRunner
+
+logger = logging.getLogger(__name__)
+
+
+class OrchidPostgresChatStorage(OrchidChatStorage):
+    """Async PostgreSQL storage for chat sessions and messages.
+
+    Constructor accepts the DSN via ``dsn`` and an optional
+    ``extra_migrations_package`` (dotted import path) so integrators
+    can append their own migrations after the framework's.
+    """
+
+    def __init__(self, *, dsn: str, extra_migrations_package: str | None = None):
+        self._dsn = dsn
+        self._pool: Any = None
+        self._migrator = PostgresMigrationRunner(
+            extra_migrations_package=extra_migrations_package,
+        )
+
+    # ── Lifecycle ────────────────────────────────────────────
+
+    async def init_db(self) -> None:
+        import asyncpg
+
+        self._pool = await asyncpg.create_pool(self._dsn, min_size=1, max_size=10)
+        async with self._pool.acquire() as conn:
+            await self._migrator.run_up(conn)
+        logger.info("[OrchidChatStorage:postgres] Initialised")
+
+    async def close(self) -> None:
+        if self._pool:
+            await self._pool.close()
+            self._pool = None
+
+    async def _conn(self):
+        if self._pool is None:
+            raise RuntimeError("OrchidPostgresChatStorage: init_db() not called")
+        return await self._pool.acquire()
+
+    # ── Sessions ─────────────────────────────────────────────
+
+    async def create_chat(
+        self,
+        tenant_id: str,
+        user_id: str,
+        title: str = "",
+    ) -> OrchidChatSession:
+        now = utcnow()
+        chat = OrchidChatSession(
+            id=str(uuid.uuid4()),
+            tenant_id=tenant_id,
+            user_id=user_id,
+            title=title or "New chat",
+            created_at=now,
+            updated_at=now,
+        )
+        async with self._pool.acquire() as conn:
+            await conn.execute(
+                "INSERT INTO chat_sessions (id, tenant_id, user_id, title, created_at, updated_at) "
+                "VALUES ($1, $2, $3, $4, $5, $6)",
+                chat.id,
+                chat.tenant_id,
+                chat.user_id,
+                chat.title,
+                now,
+                now,
+            )
+        return chat
+
+    async def list_chats(
+        self,
+        tenant_id: str,
+        user_id: str,
+    ) -> list[OrchidChatSession]:
+        async with self._pool.acquire() as conn:
+            rows = await conn.fetch(
+                "SELECT * FROM chat_sessions WHERE tenant_id = $1 AND user_id = $2 ORDER BY updated_at DESC",
+                tenant_id,
+                user_id,
+            )
+        return [_row_to_session(r) for r in rows]
+
+    async def get_chat(self, chat_id: str) -> OrchidChatSession | None:
+        async with self._pool.acquire() as conn:
+            row = await conn.fetchrow(
+                "SELECT * FROM chat_sessions WHERE id = $1",
+                chat_id,
+            )
+        return _row_to_session(row) if row else None
+
+    async def delete_chat(self, chat_id: str) -> None:
+        async with self._pool.acquire() as conn:
+            await conn.execute("DELETE FROM chat_sessions WHERE id = $1", chat_id)
+
+    async def update_title(self, chat_id: str, title: str) -> None:
+        async with self._pool.acquire() as conn:
+            await conn.execute(
+                "UPDATE chat_sessions SET title = $1, updated_at = $2 WHERE id = $3",
+                title,
+                utcnow(),
+                chat_id,
+            )
+
+    async def mark_shared(self, chat_id: str) -> None:
+        async with self._pool.acquire() as conn:
+            await conn.execute(
+                "UPDATE chat_sessions SET is_shared = TRUE, updated_at = $1 WHERE id = $2",
+                utcnow(),
+                chat_id,
+            )
+
+    # ── Messages ─────────────────────────────────────────────
+
+    async def add_message(
+        self,
+        chat_id: str,
+        role: str,
+        content: str,
+        agents_used: list[str] | None = None,
+        metadata: dict | None = None,
+    ) -> OrchidChatMessage:
+        now = utcnow()
+        msg = OrchidChatMessage(
+            id=str(uuid.uuid4()),
+            chat_id=chat_id,
+            role=role,
+            content=content,
+            agents_used=agents_used or [],
+            created_at=now,
+            metadata=metadata or {},
+        )
+        async with self._pool.acquire() as conn:
+            await conn.execute(
+                "INSERT INTO chat_messages (id, chat_id, role, content, agents_used, created_at, metadata) "
+                "VALUES ($1, $2, $3, $4, $5, $6, $7)",
+                msg.id,
+                msg.chat_id,
+                msg.role,
+                msg.content,
+                json.dumps(msg.agents_used),
+                now,
+                json.dumps(msg.metadata),
+            )
+            await conn.execute(
+                "UPDATE chat_sessions SET updated_at = $1 WHERE id = $2",
+                now,
+                chat_id,
+            )
+        return msg
+
+    async def get_messages(
+        self,
+        chat_id: str,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> list[OrchidChatMessage]:
+        async with self._pool.acquire() as conn:
+            rows = await conn.fetch(
+                "SELECT * FROM chat_messages WHERE chat_id = $1 ORDER BY created_at ASC LIMIT $2 OFFSET $3",
+                chat_id,
+                limit,
+                offset,
+            )
+        return [_row_to_message(r) for r in rows]
+
+    # ── Conversation summaries ───────────────────────────────
+
+    async def get_conversation_summary(self, chat_id: str) -> str | None:
+        async with self._pool.acquire() as conn:
+            row = await conn.fetchrow(
+                "SELECT summary_text FROM conversation_summaries WHERE chat_id = $1",
+                chat_id,
+            )
+        return row["summary_text"] if row else None
+
+    async def save_conversation_summary(self, chat_id: str, summary: str, turn_number: int) -> None:
+        async with self._pool.acquire() as conn:
+            await conn.execute(
+                "INSERT INTO conversation_summaries (chat_id, summary_text, turn_number, updated_at) "
+                "VALUES ($1, $2, $3, $4) "
+                "ON CONFLICT (chat_id) DO UPDATE SET summary_text = $2, turn_number = $3, updated_at = $4",
+                chat_id,
+                summary,
+                turn_number,
+                utcnow(),
+            )
+
+
+# ── Row mappers ──────────────────────────────────────────────
+
+
+def _parse_dt(val: Any) -> datetime:
+    if isinstance(val, datetime):
+        return val
+    if isinstance(val, str):
+        try:
+            return datetime.fromisoformat(val)
+        except (ValueError, TypeError):
+            return utcnow()
+    return utcnow()
+
+
+def _row_to_session(row: Any) -> OrchidChatSession:
+    return OrchidChatSession(
+        id=row["id"],
+        tenant_id=row["tenant_id"],
+        user_id=row["user_id"],
+        title=row["title"],
+        created_at=_parse_dt(row["created_at"]),
+        updated_at=_parse_dt(row["updated_at"]),
+        is_shared=bool(row["is_shared"]),
+    )
+
+
+def _row_to_message(row: Any) -> OrchidChatMessage:
+    agents_used = row["agents_used"]
+    if isinstance(agents_used, str):
+        agents_used = json.loads(agents_used)
+    meta = row["metadata"]
+    if isinstance(meta, str):
+        meta = json.loads(meta)
+    return OrchidChatMessage(
+        id=row["id"],
+        chat_id=row["chat_id"],
+        role=row["role"],
+        content=row["content"],
+        agents_used=agents_used or [],
+        created_at=_parse_dt(row["created_at"]),
+        metadata=meta or {},
+    )

orchid_storage_postgres-1.0.0/orchid_storage_postgres/migrations/__init__.py

@@ -0,0 +1,44 @@
+"""
+PostgreSQL migration runner.
+
+The runner discovers migrations in ``orchid_storage_postgres.migrations``
+and tracks applied versions in a ``_migrations`` table.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from orchid_ai.persistence.migrations.runner import OrchidMigrationRunner
+
+MIGRATIONS_PACKAGE = "orchid_storage_postgres.migrations"
+
+
+class PostgresMigrationRunner(OrchidMigrationRunner):
+    """PostgreSQL-specific migration tracking."""
+
+    dialect = "postgres"
+    migrations_package = MIGRATIONS_PACKAGE
+
+    async def ensure_migrations_table(self, conn: Any) -> None:
+        await conn.execute("""
+            CREATE TABLE IF NOT EXISTS _migrations (
+                version TEXT PRIMARY KEY,
+                description TEXT NOT NULL DEFAULT '',
+                applied_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+            )
+        """)
+
+    async def get_applied_versions(self, conn: Any) -> set[str]:
+        rows = await conn.fetch("SELECT version FROM _migrations")
+        return {r["version"] for r in rows}
+
+    async def record_version(self, conn: Any, version: str, description: str) -> None:
+        await conn.execute(
+            "INSERT INTO _migrations (version, description) VALUES ($1, $2)",
+            version,
+            description,
+        )
+
+    async def remove_version(self, conn: Any, version: str) -> None:
+        await conn.execute("DELETE FROM _migrations WHERE version = $1", version)

orchid_storage_postgres-1.0.0/orchid_storage_postgres/migrations/v001_initial_schema.py

@@ -0,0 +1,48 @@
+"""
+Migration v001 — PostgreSQL initial schema.
+
+Creates every framework-owned table in a single pass.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from orchid_ai.persistence.migrations._schema_ddl import PG_UP
+
+logger = logging.getLogger(__name__)
+
+VERSION = "001"
+DESCRIPTION = "PostgreSQL initial schema (chat, MCP outbound, MCP inbound gateway, events)"
+
+_PG_DOWN = [
+    "DROP TABLE IF EXISTS signal_sources CASCADE",
+    "DROP TABLE IF EXISTS job_runs CASCADE",
+    "DROP TABLE IF EXISTS schedules CASCADE",
+    "DROP TABLE IF EXISTS triggers CASCADE",
+    "DROP TABLE IF EXISTS signal_queue_dead_letter CASCADE",
+    "DROP TABLE IF EXISTS signal_queue CASCADE",
+    "DROP TABLE IF EXISTS signals CASCADE",
+    "DROP TABLE IF EXISTS mcp_gateway_tokens CASCADE",
+    "DROP TABLE IF EXISTS mcp_gateway_auth_codes CASCADE",
+    "DROP TABLE IF EXISTS mcp_gateway_clients CASCADE",
+    "DROP TABLE IF EXISTS mcp_client_registrations CASCADE",
+    "DROP TABLE IF EXISTS mcp_oauth_tokens CASCADE",
+    "DROP TABLE IF EXISTS agent_configs CASCADE",
+    "DROP TABLE IF EXISTS conversation_summaries CASCADE",
+    "DROP TABLE IF EXISTS chat_messages CASCADE",
+    "DROP TABLE IF EXISTS chat_sessions CASCADE",
+]
+
+
+async def up(conn, *, dialect: str = "postgres") -> None:
+    """Apply the PostgreSQL initial schema."""
+    for sql in PG_UP:
+        await conn.execute(sql)
+    logger.info("[orchid-storage-postgres] Migration v001 applied (%d statements)", len(PG_UP))
+
+
+async def down(conn, *, dialect: str = "postgres") -> None:
+    """Roll back the PostgreSQL initial schema."""
+    for sql in _PG_DOWN:
+        await conn.execute(sql)

orchid_storage_postgres-1.0.0/orchid_storage_postgres/visibility.py

@@ -0,0 +1,35 @@
+"""
+PostgreSQL run-visibility filter fragment.
+
+Registers a ``build_run_filter_clause`` implementation for the ``postgres``
+dialect that uses ``$1..$N`` positional parameters (asyncpg convention).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from orchid_ai.events.visibility import _Filter  # noqa: PLC2701
+
+
+def _build_postgres_filter(auth: Any) -> _Filter:
+    """Return a ``WHERE`` fragment + positional bind params for PostgreSQL."""
+    tenant_key = getattr(auth, "tenant_key", "default")
+    user_id = getattr(auth, "user_id", "")
+    roles = getattr(auth, "roles", frozenset())
+
+    if "admin" in roles:
+        return _Filter(
+            where="tenant_key = $1",
+            params={"tenant_key": tenant_key},
+        )
+    return _Filter(
+        where=(
+            "tenant_key = $1 AND ("
+            "visibility = 'tenant' "
+            "OR (visibility IN ('actor', 'addressed') "
+            "    AND visibility_user_id = $2)"
+            ")"
+        ),
+        params={"tenant_key": tenant_key, "user_id": user_id},
+    )

orchid_storage_postgres-1.0.0/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "orchid-storage-postgres"
+description = "PostgreSQL storage backend plugin for the Orchid AI framework"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+keywords = ["ai", "agents", "storage", "postgresql", "asyncpg"]
+dependencies = [
+    "orchid-ai>=1.8.2",
+    "asyncpg>=0.29.0",
+    "langgraph-checkpoint-postgres>=2.0.0",
+]
+dynamic = ["version"]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.25.0",
+    "pytest-cov>=6.0",
+    "ruff>=0.9.0",
+]
+
+[project.entry-points."orchid.visibility_fragments"]
+postgres = "orchid_storage_postgres:_register"
+
+[project.entry-points."orchid.checkpointers"]
+postgres = "orchid_storage_postgres:_register"
+
+[project.urls]
+Homepage = "https://github.com/gadz82/orchid-storage-postgres"
+Issues = "https://github.com/gadz82/orchid-storage-postgres/issues"
+
+[tool.hatch.version]
+path = "orchid_storage_postgres/__init__.py"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+
+[tool.pytest.ini_options]
+asyncio_mode = "strict"
+testpaths = ["tests"]
+
+[tool.semantic_release]
+version_variables = ["orchid_storage_postgres/__init__.py:__version__"]
+branch = "main"
+commit_message = "chore(release): v{version} [skip ci]"
+build_command = "pip install build && python -m build"
+tag_format = "v{version}"
+
+[tool.semantic_release.publish]
+upload_to_vcs_release = true
+dist_glob_patterns = ["dist/*"]
+
+[tool.semantic_release.changelog]
+changelog_file = "CHANGELOG.md"
+
+[tool.semantic_release.commit_parser_options]
+allowed_tags = ["feat", "fix", "perf", "refactor", "docs", "style", "test", "build", "ci", "chore"]
+minor_tags = ["feat"]
+patch_tags = ["fix", "perf"]

orchid_storage_postgres-1.0.0/tests/test_chat_storage.py

@@ -0,0 +1,226 @@
+"""Tests for ``OrchidPostgresChatStorage`` against a mocked ``asyncpg`` pool."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from orchid_ai.persistence.models import OrchidChatMessage, OrchidChatSession
+
+from orchid_storage_postgres.chat_storage import OrchidPostgresChatStorage, _row_to_message, _row_to_session
+
+
+# ── Helpers ─────────────────────────────────────────────────
+
+
+def _mock_pool() -> MagicMock:
+    pool = MagicMock()
+    conn = AsyncMock()
+    conn.execute = AsyncMock()
+    conn.fetch = AsyncMock(return_value=[])
+    conn.fetchrow = AsyncMock(return_value=None)
+
+    # Support ``async with pool.acquire() as conn``
+    async def _acquire():
+        return conn
+
+    pool.acquire.return_value.__aenter__ = AsyncMock(side_effect=_acquire)
+    pool.acquire.return_value.__aexit__ = AsyncMock(return_value=False)
+    pool.execute = AsyncMock()
+    return pool
+
+
+async def _init_store(store: OrchidPostgresChatStorage, pool: MagicMock) -> OrchidPostgresChatStorage:
+    with patch.object(store, "init_db", AsyncMock()) as mock_init:
+        mock_init.side_effect = None  # real init_db would set _pool
+        store._pool = pool
+    return store
+
+
+# ── Construction ──────────────────────────────────────────────
+
+
+class TestConstruction:
+    @pytest.mark.asyncio
+    async def test_missing_driver_raises_import_error(self):
+        with patch.dict("sys.modules", {"asyncpg": None}):
+            store = OrchidPostgresChatStorage(dsn="postgresql://localhost/db")
+            with pytest.raises(ImportError):
+                await store.init_db()
+
+    @pytest.mark.asyncio
+    async def test_init_db_creates_pool(self):
+        mock_asyncpg = MagicMock()
+        mock_pool = MagicMock()
+        mock_asyncpg.create_pool = AsyncMock(return_value=mock_pool)
+        mock_pool.acquire.return_value.__aenter__ = AsyncMock(return_value=AsyncMock())
+        mock_pool.acquire.return_value.__aexit__ = AsyncMock(return_value=False)
+        with patch.dict("sys.modules", {"asyncpg": mock_asyncpg}):
+            store = OrchidPostgresChatStorage(dsn="postgresql://localhost/db")
+            await store.init_db()
+            mock_asyncpg.create_pool.assert_awaited_once()
+
+
+# ── CRUD ─────────────────────────────────────────────────────
+
+
+class TestChatCRUD:
+    @pytest.mark.asyncio
+    async def test_create_chat(self):
+        store = OrchidPostgresChatStorage(dsn="postgresql://localhost/db")
+        store._pool = _mock_pool()
+        conn = await store._pool.acquire().__aenter__()
+
+        chat = await store.create_chat("t1", "u1", "Hello")
+        assert chat.tenant_id == "t1"
+        assert chat.user_id == "u1"
+        assert chat.title == "Hello"
+        conn.execute.assert_awaited()
+
+    @pytest.mark.asyncio
+    async def test_list_chats(self):
+        store = OrchidPostgresChatStorage(dsn="postgresql://localhost/db")
+        store._pool = _mock_pool()
+        conn = await store._pool.acquire().__aenter__()
+        conn.fetch = AsyncMock(return_value=[])
+
+        chats = await store.list_chats("t1", "u1")
+        assert chats == []
+
+    @pytest.mark.asyncio
+    async def test_get_chat_returns_none_for_missing(self):
+        store = OrchidPostgresChatStorage(dsn="postgresql://localhost/db")
+        store._pool = _mock_pool()
+        conn = await store._pool.acquire().__aenter__()
+        conn.fetchrow = AsyncMock(return_value=None)
+
+        chat = await store.get_chat("missing")
+        assert chat is None
+
+    @pytest.mark.asyncio
+    async def test_delete_chat(self):
+        store = OrchidPostgresChatStorage(dsn="postgresql://localhost/db")
+        store._pool = _mock_pool()
+        conn = await store._pool.acquire().__aenter__()
+
+        await store.delete_chat("c1")
+        conn.execute.assert_awaited()
+
+    @pytest.mark.asyncio
+    async def test_update_title(self):
+        store = OrchidPostgresChatStorage(dsn="postgresql://localhost/db")
+        store._pool = _mock_pool()
+        conn = await store._pool.acquire().__aenter__()
+
+        await store.update_title("c1", "New Title")
+        conn.execute.assert_awaited()
+
+    @pytest.mark.asyncio
+    async def test_mark_shared(self):
+        store = OrchidPostgresChatStorage(dsn="postgresql://localhost/db")
+        store._pool = _mock_pool()
+        conn = await store._pool.acquire().__aenter__()
+
+        await store.mark_shared("c1")
+        conn.execute.assert_awaited()
+
+
+# ── Messages ─────────────────────────────────────────────────
+
+
+class TestMessages:
+    @pytest.mark.asyncio
+    async def test_add_message(self):
+        store = OrchidPostgresChatStorage(dsn="postgresql://localhost/db")
+        store._pool = _mock_pool()
+        conn = await store._pool.acquire().__aenter__()
+
+        msg = await store.add_message("c1", "user", "hello")
+        assert msg.chat_id == "c1"
+        assert msg.role == "user"
+        assert msg.content == "hello"
+        assert conn.execute.await_count >= 2  # INSERT + UPDATE
+
+    @pytest.mark.asyncio
+    async def test_get_messages(self):
+        store = OrchidPostgresChatStorage(dsn="postgresql://localhost/db")
+        store._pool = _mock_pool()
+        conn = await store._pool.acquire().__aenter__()
+        conn.fetch = AsyncMock(return_value=[])
+
+        msgs = await store.get_messages("c1", limit=10)
+        assert msgs == []
+
+
+# ── Conversation summaries ───────────────────────────────────
+
+
+class TestConversationSummaries:
+    @pytest.mark.asyncio
+    async def test_get_summary_returns_none(self):
+        store = OrchidPostgresChatStorage(dsn="postgresql://localhost/db")
+        store._pool = _mock_pool()
+        conn = await store._pool.acquire().__aenter__()
+        conn.fetchrow = AsyncMock(return_value=None)
+
+        result = await store.get_conversation_summary("c1")
+        assert result is None
+
+    @pytest.mark.asyncio
+    async def test_save_summary(self):
+        store = OrchidPostgresChatStorage(dsn="postgresql://localhost/db")
+        store._pool = _mock_pool()
+        conn = await store._pool.acquire().__aenter__()
+
+        await store.save_conversation_summary("c1", "Summary text", 3)
+        conn.execute.assert_awaited()
+
+
+# ── Row mappers ──────────────────────────────────────────────
+
+
+class TestRowMappers:
+    def test_row_to_session(self):
+        row = {
+            "id": "s1",
+            "tenant_id": "t1",
+            "user_id": "u1",
+            "title": "Test",
+            "created_at": datetime(2026, 1, 1),
+            "updated_at": datetime(2026, 1, 2),
+            "is_shared": True,
+        }
+        session = _row_to_session(row)
+        assert session.id == "s1"
+        assert session.is_shared is True
+
+    def test_row_to_message_jsonb_parsed(self):
+        row = {
+            "id": "m1",
+            "chat_id": "c1",
+            "role": "assistant",
+            "content": "Hi there",
+            "agents_used": json.dumps(["agent-a"]),
+            "created_at": datetime(2026, 1, 1),
+            "metadata": json.dumps({"k": "v"}),
+        }
+        msg = _row_to_message(row)
+        assert msg.agents_used == ["agent-a"]
+        assert msg.metadata == {"k": "v"}
+
+    def test_row_to_message_already_parsed(self):
+        row = {
+            "id": "m1",
+            "chat_id": "c1",
+            "role": "assistant",
+            "content": "Hi",
+            "agents_used": ["agent-a"],
+            "created_at": datetime(2026, 1, 1),
+            "metadata": {"k": "v"},
+        }
+        msg = _row_to_message(row)
+        assert msg.agents_used == ["agent-a"]
+        assert msg.metadata == {"k": "v"}

orchid_storage_postgres-1.0.0/tests/test_checkpointer.py

@@ -0,0 +1,30 @@
+"""Tests for the PostgreSQL checkpointer (bundled in orchid-storage-postgres)."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+
+class TestBuildPostgresCheckpointer:
+    @pytest.mark.asyncio
+    async def test_factory_in_module(self):
+        from orchid_storage_postgres import _build_postgres_checkpointer
+
+        assert callable(_build_postgres_checkpointer)
+
+    @pytest.mark.asyncio
+    async def test_missing_package_raises_import_error(self):
+        with patch.dict("sys.modules", {"langgraph.checkpoint.postgres": None}):
+            with pytest.raises(ImportError):
+                from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver  # noqa: F401
+
+
+class TestRegistration:
+    def test_register_adds_to_registry(self):
+        from orchid_ai.checkpointing.factory import _CHECKPOINTER_REGISTRY
+        from orchid_storage_postgres import _register
+
+        _register()
+        assert "postgres" in _CHECKPOINTER_REGISTRY

orchid_storage_postgres-1.0.0/tests/test_migration.py

@@ -0,0 +1,54 @@
+"""Tests for the PostgreSQL migration runner and v001 migration."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock
+
+import pytest
+
+from orchid_storage_postgres.migrations import PostgresMigrationRunner
+from orchid_storage_postgres.migrations.v001_initial_schema import VERSION, up
+
+
+class TestPostgresMigrationRunner:
+    @pytest.mark.asyncio
+    async def test_ensure_migrations_table(self):
+        runner = PostgresMigrationRunner()
+        conn = AsyncMock()
+        await runner.ensure_migrations_table(conn)
+        conn.execute.assert_awaited_once()
+
+    @pytest.mark.asyncio
+    async def test_get_applied_versions(self):
+        runner = PostgresMigrationRunner()
+        conn = AsyncMock()
+        conn.fetch = AsyncMock(return_value=[])
+        versions = await runner.get_applied_versions(conn)
+        assert versions == set()
+
+    @pytest.mark.asyncio
+    async def test_record_version(self):
+        runner = PostgresMigrationRunner()
+        conn = AsyncMock()
+        await runner.record_version(conn, "001", "test")
+        conn.execute.assert_awaited_once()
+
+    @pytest.mark.asyncio
+    async def test_remove_version(self):
+        runner = PostgresMigrationRunner()
+        conn = AsyncMock()
+        await runner.remove_version(conn, "001")
+        conn.execute.assert_awaited_once()
+
+
+class TestV001Migration:
+    @pytest.mark.asyncio
+    async def test_up_executes_statements(self):
+        conn = AsyncMock()
+        await up(conn)
+        # PG_UP has many statements — verify at least some executed
+        assert conn.execute.await_count > 0
+
+    @pytest.mark.asyncio
+    async def test_has_version(self):
+        assert VERSION == "001"

orchid_storage_postgres-1.0.0/tests/test_postgres_queue.py

@@ -0,0 +1,24 @@
+"""Postgres-backed queue + event-store tests.
+
+These tests require a live Postgres reachable at the DSN supplied via
+``ORCHID_TEST_PG_DSN``.  They're skipped when the variable is unset
+so CI can stay hermetic; the docker-compose Postgres is what wires
+them up locally::
+
+    export ORCHID_TEST_PG_DSN=postgresql://orchid:orchid@localhost:5432/orchid_test
+    cd orchid && .venv/bin/python -m pytest tests/events/test_postgres_queue.py
+
+The fixture isolates each test in a fresh schema and rolls back at
+teardown so tests don't leak rows across runs.
+
+.. note::
+
+    ``PostgresEventStorage`` and ``PostgresSignalQueue`` are not yet
+    available in the orchid-storage-postgres plugin.  These tests are
+    skipped unconditionally until the postgres events plugin ships.
+"""
+from __future__ import annotations
+
+import pytest
+
+pytestmark = pytest.mark.skip(reason="PostgresEventStorage / PostgresSignalQueue not yet available in orchid-storage-postgres plugin")

orchid_storage_postgres-1.0.0/tests/test_visibility.py

@@ -0,0 +1,30 @@
+"""Tests for the PostgreSQL visibility fragment."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+from orchid_storage_postgres.visibility import _build_postgres_filter
+
+
+class TestPostgresVisibilityFilter:
+    def test_admin_short_circuits_to_tenant_only(self):
+        auth = SimpleNamespace(tenant_key="t1", user_id="u1", roles=frozenset(["admin"]))
+        f = _build_postgres_filter(auth)
+        assert "tenant_key = $1" in f.where
+        assert f.params["tenant_key"] == "t1"
+
+    def test_non_admin_gets_visibility_clauses(self):
+        auth = SimpleNamespace(tenant_key="t1", user_id="u1", roles=frozenset())
+        f = _build_postgres_filter(auth)
+        assert "tenant_key = $1" in f.where
+        assert "visibility = 'tenant'" in f.where
+        assert "visibility_user_id = $2" in f.where
+        assert f.params["tenant_key"] == "t1"
+        assert f.params["user_id"] == "u1"
+
+    def test_uses_positional_params(self):
+        auth = SimpleNamespace(tenant_key="t1", user_id="u1", roles=frozenset())
+        f = _build_postgres_filter(auth)
+        assert "$1" in f.where
+        assert "$2" in f.where