agentseek-api 0.2.2__tar.gz → 0.2.3__tar.gz

{agentseek_api-0.2.2 → agentseek_api-0.2.3}/.github/workflows/ci.yml

@@ -91,7 +91,9 @@ jobs:
           tests/unit/test_runtime_environment.py
           tests/unit/test_runtime_entrypoint.py
           tests/unit/test_process_supervisor.py
+          tests/unit/test_sqlite_checkpointer.py
           tests/integration/test_cli_runtime_processes.py
+          tests/integration/test_metadata_db_config.py
           -q
 
       - name: Sync embedded SeekDB extra for serve smoke

{agentseek_api-0.2.2 → agentseek_api-0.2.3}/CHANGELOG.md

@@ -4,6 +4,21 @@ Notable changes to AgentSeek API are documented in this file.
 
 ## Unreleased
 
+## 0.2.3 - 2026-08-17
+
+### Fixed
+
+- When `METADATA_DB_BACKEND=sqlite`, store completed-run snapshots in the
+  configured SQLite metadata database instead of constructing an OceanBase
+  saver and attempting a MySQL-family connection.
+
+### Upgrade notes
+
+- No manual schema or configuration migration is required. The
+  `agentseek_checkpoints` table is created idempotently at startup.
+- This fix covers completed-run snapshots only. LangGraph checkpoint state
+  remains in memory when the metadata backend is SQLite.
+
 ## 0.2.2 - 2026-08-16
 
 ### Highlights

{agentseek_api-0.2.2 → agentseek_api-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentseek-api
-Version: 0.2.2
+Version: 0.2.3
 Summary: AgentSeek API core runtime with OceanBase checkpoints.
 License-File: LICENSE
 Requires-Python: >=3.12
@@ -217,7 +217,7 @@ When the server starts it prints the banner and local URLs:
 ╠═╣│ ┬├┤ │││ │ ╚═╗├┤ ├┤ ├┴┐
 ╩ ╩└─┘└─┘┘└┘ ┴ ╚═╝└─┘└─┘┴ ┴
 
-     AgentSeek v0.2.2
+     AgentSeek v0.2.3
 
 - 🚀 API: http://localhost:2024
 - 📚 Docs: http://localhost:2024/docs
@@ -691,7 +691,12 @@ parent api build --config ./langgraph.json -t my-api:dev
 - `METADATA_DB_BACKEND=auto` normalizes drivers:
   - PostgreSQL: `postgresql+asyncpg://...`
   - OceanBase / MySQL: `mysql+aiomysql://...`
-- Checkpoint persistence defaults to OceanBase / seekdb settings
+  - SQLite: `sqlite+aiosqlite://...`
+- Completed-run snapshots default to OceanBase / seekdb settings. With
+  `METADATA_DB_BACKEND=sqlite`, they are stored in the configured SQLite
+  metadata database without constructing an OceanBase saver.
+- The SQLite metadata path still uses an in-memory LangGraph checkpointer; it
+  does not make LangGraph graph checkpoints durable.
 - Auth: configure via `agentseek.json` `"auth.path"` or `AUTH_MODULE_PATH` env var.
   Uses `langgraph_sdk.Auth` with `@auth.authenticate` and `@auth.on` handlers.
   If not set, all requests pass through as default_user (noop).

{agentseek_api-0.2.2 → agentseek_api-0.2.3}/README.md

@@ -185,7 +185,7 @@ When the server starts it prints the banner and local URLs:
 ╠═╣│ ┬├┤ │││ │ ╚═╗├┤ ├┤ ├┴┐
 ╩ ╩└─┘└─┘┘└┘ ┴ ╚═╝└─┘└─┘┴ ┴
 
-     AgentSeek v0.2.2
+     AgentSeek v0.2.3
 
 - 🚀 API: http://localhost:2024
 - 📚 Docs: http://localhost:2024/docs
@@ -659,7 +659,12 @@ parent api build --config ./langgraph.json -t my-api:dev
 - `METADATA_DB_BACKEND=auto` normalizes drivers:
   - PostgreSQL: `postgresql+asyncpg://...`
   - OceanBase / MySQL: `mysql+aiomysql://...`
-- Checkpoint persistence defaults to OceanBase / seekdb settings
+  - SQLite: `sqlite+aiosqlite://...`
+- Completed-run snapshots default to OceanBase / seekdb settings. With
+  `METADATA_DB_BACKEND=sqlite`, they are stored in the configured SQLite
+  metadata database without constructing an OceanBase saver.
+- The SQLite metadata path still uses an in-memory LangGraph checkpointer; it
+  does not make LangGraph graph checkpoints durable.
 - Auth: configure via `agentseek.json` `"auth.path"` or `AUTH_MODULE_PATH` env var.
   Uses `langgraph_sdk.Auth` with `@auth.authenticate` and `@auth.on` handlers.
   If not set, all requests pass through as default_user (noop).

{agentseek_api-0.2.2 → agentseek_api-0.2.3}/README.zh-CN.md

@@ -181,7 +181,7 @@ uv run agentseek-api dev --config ./langgraph.json
 ╠═╣│ ┬├┤ │││ │ ╚═╗├┤ ├┤ ├┴┐
 ╩ ╩└─┘└─┘┘└┘ ┴ ╚═╝└─┘└─┘┴ ┴
 
-     AgentSeek v0.2.2
+     AgentSeek v0.2.3
 
 - 🚀 API: http://localhost:2024
 - 📚 Docs: http://localhost:2024/docs
@@ -623,7 +623,12 @@ parent api build --config ./langgraph.json -t my-api:dev
 - `METADATA_DB_BACKEND=auto` 会对驱动进行归一化：
   - PostgreSQL：`postgresql+asyncpg://...`
   - OceanBase / MySQL：`mysql+aiomysql://...`
-- Checkpoint 持久化默认使用 OceanBase / seekdb 配置
+  - SQLite：`sqlite+aiosqlite://...`
+- 完成态 run 快照默认使用 OceanBase / seekdb 配置。当
+  `METADATA_DB_BACKEND=sqlite` 时，快照会写入已配置的 SQLite 元数据
+  数据库，且不会构造 OceanBase saver。
+- SQLite 元数据路径仍使用内存中的 LangGraph checkpointer，不提供持久化的
+  LangGraph 图 checkpoint。
 - 鉴权：通过 `agentseek.json` 的 `"auth.path"` 或 `AUTH_MODULE_PATH` 环境变量配置。
   使用 `langgraph_sdk.Auth` 的 `@auth.authenticate` 与 `@auth.on` 处理器风格。
   未配置时所有请求以 default_user 放行（noop）。

{agentseek_api-0.2.2 → agentseek_api-0.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentseek-api"
-version = "0.2.2"
+version = "0.2.3"
 description = "AgentSeek API core runtime with OceanBase checkpoints."
 readme = "README.md"
 requires-python = ">=3.12"

agentseek_api-0.2.3/src/agentseek_api/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.3"

{agentseek_api-0.2.2 → agentseek_api-0.2.3}/src/agentseek_api/core/database.py

@@ -3,7 +3,7 @@ import logging
 import os
 from collections.abc import Callable
 from pathlib import Path
-from typing import Any
+from typing import Any, Protocol
 
 from langgraph.checkpoint.memory import InMemorySaver
 from langchain_oceanbase.checkpointer import OceanBaseCheckpointSaver as LangGraphOceanBaseCheckpointSaver
@@ -14,6 +14,7 @@ from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker
 from agentseek_api.core.oceanbase_checkpointer import OceanBaseCheckpointSaver
 from agentseek_api.core.orm import Base
 from agentseek_api.core.runtime_store import SqliteStore
+from agentseek_api.core.sqlite_checkpointer import SqliteCheckpointSaver
 from agentseek_api.core.store_config import load_store_config
 from agentseek_api.settings import settings
 
@@ -58,6 +59,18 @@ class NullStore:
         return None
 
 
+class RunCheckpointSaver(Protocol):
+    def setup(self) -> None: ...
+
+    def save_checkpoint(
+        self,
+        *,
+        thread_id: str,
+        run_id: str,
+        payload: dict[str, Any],
+    ) -> None: ...
+
+
 def _is_already_exists_error(exc: Exception) -> bool:
     message = str(exc).lower()
     return "already exists" in message
@@ -156,7 +169,7 @@ class DatabaseManager:
     def __init__(self) -> None:
         self.engine: AsyncEngine | None = None
         self.session_factory: async_sessionmaker[AsyncSession] | None = None
-        self._checkpointer: OceanBaseCheckpointSaver | None = None
+        self._checkpointer: RunCheckpointSaver | None = None
         self._langgraph_checkpointer: Any | None = None
         self._store: Any | None = None
         self._setup_lock: asyncio.Lock = asyncio.Lock()
@@ -208,11 +221,8 @@ class DatabaseManager:
             async with self.engine.begin() as conn:
                 await conn.run_sync(Base.metadata.create_all)
                 await conn.run_sync(self._apply_additive_migrations)
-            conn_args = _resolve_connection_args()
-            self._checkpointer = OceanBaseCheckpointSaver(
-                connection_args=conn_args
-            )
             if metadata_backend == "sqlite":
+                self._checkpointer = SqliteCheckpointSaver(url=metadata_db_url)
                 self._langgraph_checkpointer = InMemorySaver()
                 self._store = SqliteStore(
                     url=metadata_db_url,
@@ -220,6 +230,8 @@ class DatabaseManager:
                     ttl_config=runtime_ttl,
                 )
             else:
+                conn_args = _resolve_connection_args()
+                self._checkpointer = OceanBaseCheckpointSaver(connection_args=conn_args)
                 self._langgraph_checkpointer = LangGraphOceanBaseCheckpointSaver(
                     connection_args=conn_args
                 )
@@ -320,6 +332,14 @@ class DatabaseManager:
             self._store_setup_done = True
 
     async def close(self) -> None:
+        run_checkpointer = self._checkpointer
+        self._checkpointer = None
+        close_run_checkpointer = getattr(run_checkpointer, "close", None)
+        if callable(close_run_checkpointer):
+            try:
+                await asyncio.to_thread(close_run_checkpointer)
+            except Exception:  # noqa: BLE001
+                logger.warning("Failed to close run checkpointer", exc_info=True)
         langgraph_checkpointer = self._langgraph_checkpointer
         self._langgraph_checkpointer = None
         close_checkpointer = getattr(langgraph_checkpointer, "close", None)
@@ -336,7 +356,6 @@ class DatabaseManager:
             await asyncio.to_thread(dispose_store_engine)
         self.engine = None
         self.session_factory = None
-        self._checkpointer = None
         self._store = None
         self._checkpointer_setup_done = False
         self._langgraph_checkpointer_setup_done = False
@@ -352,7 +371,7 @@ class DatabaseManager:
             raise RuntimeError("Database not initialized")
         return self.session_factory
 
-    def get_checkpointer(self) -> OceanBaseCheckpointSaver:
+    def get_checkpointer(self) -> RunCheckpointSaver:
         if self._checkpointer is None:
             raise RuntimeError("Database not initialized")
         return self._checkpointer

agentseek_api-0.2.3/src/agentseek_api/core/sqlite_checkpointer.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import threading
+from datetime import UTC, datetime
+from typing import Any
+
+from sqlalchemy import create_engine, text
+from sqlalchemy.engine import Engine, make_url
+from sqlalchemy.pool import StaticPool
+
+from agentseek_api.services.sse import safe_json_dumps
+
+
+class SqliteCheckpointSaver:
+    """Persist completed run snapshots in the configured SQLite database."""
+
+    def __init__(self, *, url: str) -> None:
+        parsed_url = make_url(url)
+        if parsed_url.get_backend_name() != "sqlite":
+            raise ValueError("SqliteCheckpointSaver requires a SQLite URL")
+
+        sqlite_url = parsed_url.set(drivername="sqlite").render_as_string(
+            hide_password=False
+        )
+        engine_options: dict[str, Any] = {"connect_args": {"check_same_thread": False}}
+        if parsed_url.database in {None, "", ":memory:"}:
+            engine_options["poolclass"] = StaticPool
+
+        self._engine: Engine = create_engine(sqlite_url, **engine_options)
+        self._lock = threading.Lock()
+
+    def setup(self) -> None:
+        with self._lock, self._engine.begin() as connection:
+            connection.execute(
+                text(
+                    """
+                    CREATE TABLE IF NOT EXISTS agentseek_checkpoints (
+                        id INTEGER PRIMARY KEY AUTOINCREMENT,
+                        thread_id TEXT NOT NULL,
+                        run_id TEXT NOT NULL,
+                        checkpoint TEXT NOT NULL,
+                        created_at DATETIME NOT NULL
+                    )
+                    """
+                )
+            )
+            connection.execute(
+                text(
+                    """
+                    CREATE INDEX IF NOT EXISTS idx_agentseek_checkpoints_thread_run
+                    ON agentseek_checkpoints (thread_id, run_id)
+                    """
+                )
+            )
+
+    def save_checkpoint(
+        self,
+        *,
+        thread_id: str,
+        run_id: str,
+        payload: dict[str, Any],
+    ) -> None:
+        with self._lock, self._engine.begin() as connection:
+            connection.execute(
+                text(
+                    """
+                    INSERT INTO agentseek_checkpoints
+                        (thread_id, run_id, checkpoint, created_at)
+                    VALUES (:thread_id, :run_id, :checkpoint, :created_at)
+                    """
+                ),
+                {
+                    "thread_id": thread_id,
+                    "run_id": run_id,
+                    "checkpoint": safe_json_dumps(payload),
+                    "created_at": datetime.now(UTC).replace(tzinfo=None).isoformat(),
+                },
+            )
+
+    def close(self) -> None:
+        with self._lock:
+            self._engine.dispose()

{agentseek_api-0.2.2 → agentseek_api-0.2.3}/tests/integration/test_metadata_db_config.py

@@ -1,4 +1,7 @@
+import json
+import sqlite3
 from collections.abc import Callable
+from pathlib import Path
 from typing import Any
 
 import pytest
@@ -123,3 +126,53 @@ def test_health_uses_mysql_async_driver(monkeypatch: pytest.MonkeyPatch) -> None
 
 def test_sqlite_metadata_engine_options_keep_dialect_defaults() -> None:
     assert database_module._metadata_engine_options("sqlite") == {"pool_pre_ping": True}
+
+
+def test_sqlite_runtime_starts_and_saves_checkpoints_without_oceanbase(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    database_path = tmp_path / "agentseek.sqlite3"
+
+    class RejectOceanBaseCheckpointSaver:
+        def __init__(self, *_args: object, **_kwargs: object) -> None:
+            raise AssertionError(
+                "SQLite runtime constructed the OceanBase checkpoint saver"
+            )
+
+    monkeypatch.setattr(
+        "agentseek_api.core.database.OceanBaseCheckpointSaver",
+        RejectOceanBaseCheckpointSaver,
+    )
+    monkeypatch.setattr(
+        "agentseek_api.main.ensure_default_assistants", _noop_ensure_default_assistants
+    )
+    monkeypatch.setattr(settings, "SEEKDB_EMBED", False)
+    monkeypatch.setattr(settings, "METADATA_DB_BACKEND", "sqlite")
+    monkeypatch.setattr(
+        settings,
+        "METADATA_DB_URL",
+        f"sqlite+aiosqlite:///{database_path.as_posix()}",
+    )
+
+    manager = DatabaseManager()
+    monkeypatch.setattr("agentseek_api.main.db_manager", manager)
+
+    with TestClient(create_app()) as client:
+        response = client.get("/health")
+        assert response.status_code == 200
+
+        manager.get_checkpointer().save_checkpoint(
+            thread_id="thread-sqlite",
+            run_id="run-sqlite",
+            payload={"status": "complete"},
+        )
+
+        with sqlite3.connect(database_path) as connection:
+            row = connection.execute(
+                "SELECT thread_id, run_id, checkpoint FROM agentseek_checkpoints"
+            ).fetchone()
+
+    assert row is not None
+    assert row[:2] == ("thread-sqlite", "run-sqlite")
+    assert json.loads(row[2]) == {"status": "complete"}

agentseek_api-0.2.3/tests/unit/test_ci_workflow.py

@@ -0,0 +1,25 @@
+import re
+from pathlib import Path
+
+
+def test_cli_compatibility_step_runs_sqlite_runtime_regressions_on_every_os() -> None:
+    workflow = Path(".github/workflows/ci.yml").read_text(encoding="utf-8")
+    job = re.search(
+        r"(?ms)^  cli-compatibility:\n(?P<body>.*?)(?=^  \S|\Z)",
+        workflow,
+    )
+    assert job is not None
+
+    step = re.search(
+        r"(?ms)^      - name: CLI config, host environment, and process tests\n"
+        r"(?P<body>.*?)(?=^      - name:|\Z)",
+        job.group("body"),
+    )
+    assert step is not None
+
+    command_tokens = set(step.group("body").split())
+    required_tests = {
+        "tests/unit/test_sqlite_checkpointer.py",
+        "tests/integration/test_metadata_db_config.py",
+    }
+    assert required_tests <= command_tokens

{agentseek_api-0.2.2 → agentseek_api-0.2.3}/tests/unit/test_database_manager.py

@@ -12,30 +12,26 @@ from agentseek_api.settings import settings
 async def test_checkpointer_setup_called_once(monkeypatch: pytest.MonkeyPatch) -> None:
     class FakeCheckpointer:
         setup_calls = 0
-        latest_connection_args: dict[str, str] | None = None
+        latest_url: str | None = None
 
-        def __init__(self, connection_args: dict[str, str]) -> None:
-            FakeCheckpointer.latest_connection_args = connection_args
+        def __init__(self, *, url: str) -> None:
+            FakeCheckpointer.latest_url = url
 
         def setup(self) -> None:
             FakeCheckpointer.setup_calls += 1
 
-    monkeypatch.setattr("agentseek_api.core.database.OceanBaseCheckpointSaver", FakeCheckpointer)
-    monkeypatch.setattr(settings, "SEEKDB_URL", "sqlite+aiosqlite:///:memory:")
-    monkeypatch.setattr(settings, "OCEANBASE_HOST", "127.0.0.1")
-    monkeypatch.setattr(settings, "OCEANBASE_PORT", "2881")
-    monkeypatch.setattr(settings, "OCEANBASE_USER", "root@test")
-    monkeypatch.setattr(settings, "OCEANBASE_PASSWORD", "")
-    monkeypatch.setattr(settings, "OCEANBASE_DB_NAME", "test")
+    monkeypatch.setattr(
+        "agentseek_api.core.database.SqliteCheckpointSaver", FakeCheckpointer
+    )
+    monkeypatch.setattr(settings, "METADATA_DB_URL", "sqlite+aiosqlite:///:memory:")
+    monkeypatch.setattr(settings, "METADATA_DB_BACKEND", "sqlite")
 
     manager = DatabaseManager()
     await manager.initialize()
     await manager.initialize()
 
     assert FakeCheckpointer.setup_calls == 1
-    assert FakeCheckpointer.latest_connection_args is not None
-    assert FakeCheckpointer.latest_connection_args["host"] == "127.0.0.1"
-    assert FakeCheckpointer.latest_connection_args["db_name"] == "test"
+    assert FakeCheckpointer.latest_url == "sqlite+aiosqlite:///:memory:"
     assert isinstance(manager.get_store(), SqliteStore)
 
     await manager.close()
@@ -60,6 +56,24 @@ async def test_close_cleans_up_langgraph_checkpointer() -> None:
     engine.dispose.assert_awaited_once()
 
 
+@pytest.mark.asyncio
+async def test_close_cleans_up_run_checkpointer() -> None:
+    manager = DatabaseManager()
+    checkpointer = Mock()
+    close_thread_ids: list[int] = []
+    checkpointer.close.side_effect = lambda: close_thread_ids.append(
+        threading.get_ident()
+    )
+    manager._checkpointer = checkpointer
+    event_loop_thread_id = threading.get_ident()
+
+    await manager.close()
+    await manager.close()
+
+    checkpointer.close.assert_called_once()
+    assert close_thread_ids[0] != event_loop_thread_id
+
+
 @pytest.mark.asyncio
 async def test_close_continues_after_checkpointer_cleanup_fails(
     caplog: pytest.LogCaptureFixture,

agentseek_api-0.2.3/tests/unit/test_sqlite_checkpointer.py

@@ -0,0 +1,51 @@
+import json
+import sqlite3
+from pathlib import Path
+
+import pytest
+
+from agentseek_api.core.sqlite_checkpointer import SqliteCheckpointSaver
+
+
+def test_setup_is_idempotent_and_save_checkpoint_persists_json(tmp_path: Path) -> None:
+    database_path = tmp_path / "checkpoints.sqlite3"
+    saver = SqliteCheckpointSaver(url=f"sqlite+aiosqlite:///{database_path.as_posix()}")
+
+    try:
+        saver.setup()
+        saver.setup()
+        saver.save_checkpoint(
+            thread_id="thread-unit",
+            run_id="run-unit",
+            payload={"messages": ["hello"], "complete": True},
+        )
+
+        with sqlite3.connect(database_path) as connection:
+            row = connection.execute(
+                "SELECT thread_id, run_id, checkpoint FROM agentseek_checkpoints"
+            ).fetchone()
+            indexes = connection.execute(
+                "PRAGMA index_list(agentseek_checkpoints)"
+            ).fetchall()
+    finally:
+        saver.close()
+
+    assert row is not None
+    assert row[:2] == ("thread-unit", "run-unit")
+    assert json.loads(row[2]) == {"messages": ["hello"], "complete": True}
+    assert "idx_agentseek_checkpoints_thread_run" in {index[1] for index in indexes}
+
+
+def test_rejects_non_sqlite_url() -> None:
+    with pytest.raises(ValueError, match="requires a SQLite URL"):
+        SqliteCheckpointSaver(url="mysql+aiomysql://root@localhost/agentseek")
+
+
+def test_normalizes_windows_drive_path_without_opening_database() -> None:
+    saver = SqliteCheckpointSaver(url="sqlite+aiosqlite:///C:/agentseek/runtime.db")
+
+    try:
+        assert saver._engine.url.drivername == "sqlite"
+        assert saver._engine.url.database == "C:/agentseek/runtime.db"
+    finally:
+        saver.close()

{agentseek_api-0.2.2 → agentseek_api-0.2.3}/uv.lock

@@ -29,7 +29,7 @@ wheels = [
 
 [[package]]
 name = "agentseek-api"
-version = "0.2.2"
+version = "0.2.3"
 source = { editable = "." }
 dependencies = [
     { name = "aiomysql" },

agentseek_api-0.2.2/src/agentseek_api/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.2.2"