agentseek-api 0.0.2__tar.gz → 0.1.0__tar.gz

agentseek_api-0.1.0/.env.example

@@ -0,0 +1,20 @@
+METADATA_DB_URL=
+METADATA_DB_BACKEND=auto
+SEEKDB_URL=mysql+aiomysql://root%40test:@localhost:2881/seekdb
+AGENTSEEK_GRAPHS=
+# Auth: configure via agentseek.json "auth.path" or set AUTH_MODULE_PATH directly.
+# Format: "./path/to/auth.py:auth" (langgraph_sdk.Auth object)
+# If not set, all requests pass through as default_user (noop).
+AUTH_MODULE_PATH=
+
+# Embedded SeekDB — set to true for a zero-config local backend.
+# Data stored in SEEKDB_EMBED_DIR (default: ~/.agentseek/seekdb_data).
+# Requires: uv sync --dev --extra embedded
+# SEEKDB_EMBED=true
+# SEEKDB_EMBED_DIR=
+
+OCEANBASE_HOST=localhost
+OCEANBASE_PORT=2881
+OCEANBASE_USER=root@test
+OCEANBASE_PASSWORD=
+OCEANBASE_DB_NAME=seekdb

{agentseek_api-0.0.2 → agentseek_api-0.1.0}/.github/workflows/ci.yml

@@ -90,6 +90,27 @@ jobs:
       - name: CLI config and Docker planning tests
         run: uv run pytest tests/unit/test_cli.py tests/unit/test_graph_manifest.py -q
 
+  embedded-seekdb-smoke:
+    name: Embedded SeekDB Smoke
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup UV
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          enable-cache: true
+          cache-python: true
+          python-version: "3.12"
+
+      - name: Sync with embedded extra
+        run: uv sync --dev --extra embedded
+
+      - name: Embedded seekdb serve smoke (SEEKDB_EMBED=true)
+        run: uv run python scripts/test_cli_embed_serve_smoke.py
+
   cli-docker-runtime:
     name: CLI Docker Runtime
     runs-on: ubuntu-latest

agentseek_api-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+.DS_Store
+.vscode/
+.coverage
+.agentseek/
+.pytest_cache/
+.ruff_cache/
+.tmp/
+.venv/
+__pycache__/
+*.pyc
+*.cover
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.claude
+docs/superpowers/

{agentseek_api-0.0.2 → agentseek_api-0.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentseek-api
-Version: 0.0.2
+Version: 0.1.0
 Summary: AgentSeek API core runtime with OceanBase checkpoints.
 License-File: LICENSE
 Requires-Python: >=3.12
@@ -12,7 +12,7 @@ Requires-Dist: fastapi>=0.110.1
 Requires-Dist: greenlet>=3.1.0
 Requires-Dist: langchain-anthropic>=1.0.0
 Requires-Dist: langchain-core>=1.0.0
-Requires-Dist: langchain-oceanbase==0.5.0
+Requires-Dist: langchain-oceanbase==0.5.2
 Requires-Dist: langchain-openai>=1.0.0
 Requires-Dist: langchain>=0.3.9
 Requires-Dist: langgraph-sdk>=0.3.5
@@ -22,33 +22,41 @@ Requires-Dist: pydantic-settings>=2.4.0
 Requires-Dist: pydantic>=2.8.0
 Requires-Dist: pymysql>=1.1.0
 Requires-Dist: redis>=5.0.0
+Requires-Dist: scalar-fastapi>=1.0.3
 Requires-Dist: sqlalchemy>=2.0.0
 Requires-Dist: uvicorn>=0.30.0
 Provides-Extra: embedded
-Requires-Dist: langchain-oceanbase[pyseekdb]==0.5.0; extra == 'embedded'
+Requires-Dist: langchain-oceanbase[pyseekdb]==0.5.2; extra == 'embedded'
 Description-Content-Type: text/markdown
 
 # AgentSeek API
 
+**English** | [中文](README.zh-CN.md)
+
+> [!WARNING]
+> This project is under active development and is **not production-ready**.
+> Pull requests for bug fixes and enhancements are warmly welcomed!
+
 Run LangGraph and LangChain apps behind a FastAPI runtime with a standalone
 `agentseek-api` CLI.
 
 > [!NOTE]
 > AgentSeek API uses
 > [Agent Protocol](https://github.com/langchain-ai/agent-protocol) as the main
-> external compatibility reference. The current runtime already covers the core
-> thread, run, cron, streaming, and protocol-v2 event flows. Some protocol surfaces
-> are still pending, and agent resources are exposed through `/assistants`,
-> direct `/agents` aliases, Streamable HTTP MCP, and LangSmith-style A2A
-> endpoints. This is workable OSS parity for the core agent-server surfaces,
-> not full LangSmith Agent Server parity.
+> external compatibility reference. The current runtime covers the core
+> thread, run, cron, streaming (including subgraph and expanded stream modes),
+> and protocol-v2 event flows. Auth uses the `langgraph_sdk.Auth` pattern with
+> `@auth.authenticate` and `@auth.on` handlers. Agent resources are exposed
+> through `/assistants`, direct `/agents` aliases, Streamable HTTP MCP, and
+> LangSmith-style A2A endpoints. This is workable OSS parity for the core
+> agent-server surfaces, not full LangSmith Agent Server parity.
 
 Current release boundary:
 
-- Implemented: assistants, threads, runs, crons, streaming, Store API, MCP,
-  and A2A
-- Explicitly not implemented: distributed runtime parity, assistant
-  subgraph inspection, and assistant version-promotion workflows
+- Implemented: assistants, threads, runs, crons, streaming (including subgraph
+  and expanded stream modes), Store API, MCP, and A2A
+- Explicitly not implemented: distributed runtime parity and assistant
+  version-promotion workflows
 
 ## 🚀 Quickstart
 
@@ -62,19 +70,110 @@ Current release boundary:
 | Workflow | Use it when | Recommended command |
 | --- | --- | --- |
 | `langgraph dev` | You want the fastest mocked or in-memory local API loop for graph prototyping or Studio experimentation. | `langgraph dev` |
-| `agentseek-api dev` | You want the real AgentSeek API surface with your actual MySQL-family / SeekDB / OceanBase-style persistence, auth, and Docker/runtime behavior. | `uv run agentseek-api dev` |
+| `agentseek-api dev` | You want the real AgentSeek API surface with your actual MySQL-family / seekdb / OceanBase-style persistence, auth, and Docker/runtime behavior. | `uv run agentseek-api dev` |
 
 Use `langgraph dev` when you do not need real backend validation. Use
 `agentseek-api dev` when you want to exercise the actual API contract this repo
 ships.
 
-### 1. Install dependencies
+### 1. Install
+
+**Install as a project dependency** (recommended):
+
+```bash
+# In your project directory
+uv add agentseek-api
+
+# With embedded seekdb backend (no Docker needed)
+uv add agentseek-api[embedded]
+```
+
+**Global install** (if you prefer a system-wide command):
+
+```bash
+pip install agentseek-api
+
+# Then install your graph's dependencies into the same environment
+pip install ...
+```
+
+> [!WARNING]
+> Global install only supports `pip install`. **Do NOT use `uv tool install`**.
+
+**Install from source** (for contributors):
 
 ```bash
 uv sync
+
+# With embedded seekdb backend
+uv sync --extra embedded
 ```
 
-### 2. Create a config file
+### 2. Configure seekdb embed as the default backend (recommended)
+
+The fastest way to get a real backend running locally is **seekdb embed** — an
+in-process SeekDB instance, no Docker or separate process required:
+
+```bash
+SEEKDB_EMBED=true agentseek-api dev
+```
+
+Data is stored in `~/.agentseek/seekdb_data` by default. Set `SEEKDB_EMBED_DIR`
+to change the location.
+
+<details>
+<summary>Using a seekdb Docker container instead</summary>
+
+```bash
+docker run -d --name seekdb-dev \
+  -p 2881:2881 -p 2886:2886 \
+  oceanbase/seekdb:latest
+```
+
+Wait for the container to become healthy, then export:
+
+```bash
+export OCEANBASE_HOST=127.0.0.1
+export OCEANBASE_PORT=2881
+export OCEANBASE_USER=root
+export OCEANBASE_PASSWORD=
+export OCEANBASE_DB_NAME=seekdb
+```
+
+</details>
+
+<details>
+<summary>Using an OceanBase instance instead</summary>
+
+Start an OceanBase-CE container in mini mode:
+
+```bash
+docker run -d --name ob-dev \
+  -e MODE=mini \
+  -p 2881:2881 \
+  oceanbase/oceanbase-ce:latest
+```
+
+OceanBase-CE in mini mode takes a few minutes to initialize. Wait for readiness,
+then export:
+
+```bash
+export OCEANBASE_HOST=127.0.0.1
+export OCEANBASE_PORT=2881
+export OCEANBASE_USER=root@test
+export OCEANBASE_PASSWORD=
+export OCEANBASE_DB_NAME=seekdb
+```
+
+Create the database:
+
+```bash
+mysql -h 127.0.0.1 -P 2881 -u root@test -e "CREATE DATABASE IF NOT EXISTS seekdb"
+```
+
+</details>
+
+### 3. Create a config file
 
 `agentseek-api` looks for config in this order:
 
@@ -94,7 +193,7 @@ Minimal `langgraph.json`:
 }
 ```
 
-### 3. Start the local API
+### 4. Start the local API
 
 ```bash
 uv run agentseek-api dev
@@ -106,19 +205,24 @@ Run with an explicit config when needed:
 uv run agentseek-api dev --config ./langgraph.json
 ```
 
-When the server is ready it prints the local API, docs, and Studio URLs:
+When the server starts it prints the banner and local URLs:
 
 ```text
-> Ready!
->
-> - API: http://localhost:2024
->
-> - Docs: http://localhost:2024/docs
->
-> - LangSmith Studio Web UI: https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024
+        Welcome to
+
+╔═╗┌─┐┌─┐┌┐┌┌┬┐╔═╗┌─┐┌─┐┬┌─
+╠═╣│ ┬├┤ │││ │ ╚═╗├┤ ├┤ ├┴┐
+╩ ╩└─┘└─┘┘└┘ ┴ ╚═╝└─┘└─┘┴ ┴
+
+     AgentSeek v0.1.0
+
+- 🚀 API: http://localhost:2024
+- 📚 Docs: http://localhost:2024/docs
+- 🎨 Studio UI: https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024
+
 ```
 
-### 4. Check that it is up
+### 5. Check that it is up
 
 ```bash
 curl http://127.0.0.1:2024/health
@@ -126,6 +230,37 @@ curl http://127.0.0.1:2024/info
 curl http://127.0.0.1:2024/openapi.json
 ```
 
+### 6. Test by using LangGraph SDK
+
+```python
+from langgraph_sdk import get_client
+
+client = get_client(url="http://localhost:2024/")
+
+async def main():
+    # List all assistants
+    assistants = await client.assistants.search(graph_id="agent")
+
+    # We auto-create an assistant for each graph you register in config.
+    agent = assistants[0]
+
+    # Start a new thread
+    thread = await client.threads.create()
+
+    # Start a streaming run
+    input = {"messages": [{"role": "human", "content": "hello?"}]}
+    async for chunk in client.runs.stream(
+        thread["thread_id"], agent["assistant_id"], input=input
+    ):
+        print(chunk)
+
+
+if __name__ == "__main__":
+    import asyncio
+
+    asyncio.run(main())
+```
+
 ## 🧰 CLI
 
 The package installs `agentseek-api` as the standalone executable. It does not
@@ -202,7 +337,8 @@ in-memory, or tunneled local workflows, prefer `langgraph dev`.
 - ⚙️ Standalone CLI plus embeddable subcommand registration for parent CLIs
 - 🔌 Manifest-driven graph loading through `agentseek.json`, `langgraph.json`,
   or `AGENTSEEK_GRAPHS`
-- 🌊 SSE streaming with `message_chunk` events
+- 🌊 SSE streaming with subgraph support and expanded stream modes
+  (values, updates, messages, messages-tuple, events, tasks, checkpoints, custom, debug)
 - 🧰 MCP tool exposure for registered graphs over Streamable HTTP
 - 🤝 A2A assistant endpoints with agent-card discovery, streaming, and task lookup/cancel
 - 🧵 Thread, run, wait, cancel, history, state, and protocol-v2 stream flows
@@ -210,13 +346,14 @@ in-memory, or tunneled local workflows, prefer `langgraph dev`.
 - 🤖 Agent resources exposed through both `/assistants` and `/agents`
 - 🧑‍💻 Human-in-the-loop resume through
   `POST /threads/{thread_id}/runs/{run_id}/resume`
-- 🗄️ SeekDB / OceanBase-first checkpoint persistence via
+- 🗄️ seekdb / OceanBase-first checkpoint persistence via
   `langchain-oceanbase`
 - 📦 Redis-backed durable execution with a dedicated worker process
 - ♻️ Persisted run and thread stream replay for resume-after-restart flows
-- 🔐 `noop` and custom auth backends
+- 🔐 `langgraph_sdk.Auth`-based authentication with `@auth.authenticate` and
+  `@auth.on` handlers; noop fallback when unconfigured
 - 🐳 Dockerfile generation, image build, and local Docker runtime helpers
-- 🧪 Real backend CI coverage across MySQL, SeekDB, OceanBase, and Redis runtime paths
+- 🧪 Real backend CI coverage across MySQL, seekdb, OceanBase, and Redis runtime paths
 - 🧪 Manual provider-backed streaming checks for live SSE proof
 
 ## 🎯 Compatibility Scope
@@ -224,12 +361,13 @@ in-memory, or tunneled local workflows, prefer `langgraph dev`.
 Treat AgentSeek API as a practical OSS-compatible core for Agent Server-style
 apps.
 
-- Shipped: assistant CRUD, thread/run lifecycle APIs, resumable SSE streams,
-  cron APIs and scheduler dispatch, Store API, MCP, A2A, Redis-backed durable
-  execution, and Docker/runtime helpers
+- Shipped: assistant CRUD, thread/run lifecycle APIs, resumable SSE streams
+  with subgraph and expanded stream modes, cron APIs and scheduler dispatch,
+  Store API, MCP, A2A, Redis-backed durable execution, and Docker/runtime
+  helpers
 - Intentionally missing: distributed runtime orchestration parity, full
-  assistant version management, assistant subgraph inspection, and full
-  assistant helper parity beyond the core CRUD and schema flows
+  assistant version management, and full assistant helper parity beyond the
+  core CRUD and schema flows
 
 ## 🚚 Deployment Roles
 
@@ -271,7 +409,7 @@ Useful config fields:
 Endpoint-level LangGraph config keys such as `http` and `api_version` are
 tolerated by the CLI layer where possible. Store config is used by the HTTP
 Store API and the injected LangGraph `BaseStore` runtime for TTL and semantic
-search. This repo uses the published `langchain-oceanbase==0.5.0` package from
+search. This repo uses the published `langchain-oceanbase==0.5.2` package from
 PyPI.
 
 Config-driven custom auth can live in `agentseek.json` or `langgraph.json`:
@@ -518,14 +656,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
-- Auth modes:
-  - `AUTH_TYPE=noop`
-  - `AUTH_TYPE=custom` with `AUTH_MODULE_PATH=module:backend_symbol`
-  - `AUTH_TYPE=api_key` with `AUTH_API_KEYS=key=user_id[,key2=user2]`
-  - `AUTH_TYPE=jwt` with `AUTH_JWT_SECRET`, optional
-    `AUTH_JWT_ALGORITHM=HS256`, and `sub` as the user identity
+- Checkpoint persistence defaults to OceanBase / seekdb settings
+- 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).
 - Assistant management, thread, and run endpoints enforce configured auth.
+  Resource-level filtering is supported via `@auth.on` handlers.
 
 ### Durable execution
 
@@ -540,6 +676,9 @@ parent api build --config ./langgraph.json -t my-api:dev
 
 - `examples/minimal_agentseek/agentseek.json`: minimal first-time config
 - `examples/assistant_config/`: assistant config/context/metadata starter
+- `examples/auth/api_key_auth.py`: API key authentication using `langgraph_sdk.Auth`
+- `examples/auth/bearer_token_auth.py`: bearer token authentication
+- `examples/auth/jwt_auth.py`: JWT authentication with JWKS validation
 - `examples/auth/custom_backend.py`: custom auth backend
 - `examples/auth/jwt.md`: JWT auth environment contract
 - `examples/custom_routes/app.py`: mounting custom FastAPI routes around the
@@ -577,10 +716,10 @@ make test-redis-docker
 ```
 
 GitHub Actions also runs the Docker-backed backend matrix against MySQL,
-SeekDB, and OceanBase, including the dedicated `Redis Durable Execution`
+seekdb, and OceanBase, including the dedicated `Redis Durable Execution`
 workflow jobs.
 
-For local embedded SeekDB smoke coverage, install the optional extra first:
+For local embedded seekdb smoke coverage, install the optional extra first:
 
 ```bash
 uv sync --dev --extra embedded
@@ -616,7 +755,7 @@ The live-provider workflow is the canonical proof for real SSE
 `message_chunk` events from provider-backed graphs, and it now also covers
 provider-backed Store, MCP, and HITL flows in a tiered backend matrix:
 
-- SeekDB: full Streaming + Store + MCP + HITL acceptance
+- seekdb: full Streaming + Store + MCP + HITL acceptance
 - OceanBase: full Streaming + Store + MCP + HITL acceptance
 - MySQL: Streaming + HITL compatibility
 - PostgreSQL metadata: Streaming + MCP compatibility while runtime
@@ -636,11 +775,66 @@ Use `ci.yml` for the normal development signal, and use
 `live-provider-streaming.yml` when you need explicit proof that real providers
 still satisfy the intended streaming, Store, MCP, and HITL contracts.
 
-## 🗺️ Future Work
-
-1. [x] Add Redis-backed task queue and worker handoff for durable run execution
-2. [ ] Deepen Agent Protocol schema parity beyond the current alias coverage
-3. [x] Add crons and scheduler support
-4. [ ] Add distributed runtime parity beyond the current single-worker Redis flow
-5. [ ] Add assistant version history and subgraph inspection support
-6. [x] Add MCP and A2A endpoint parity
+## 🧱 Built On
+
+AgentSeek API is glue around a small set of upstream projects and infra.
+
+**Core pillars**
+
+- [LangGraph](https://github.com/langchain-ai/langgraph) — graph runtime that
+  executes registered assistants
+- [langchain-oceanbase](https://pypi.org/project/langchain-oceanbase/) —
+  checkpointer and store implementation, the primary path for graph state
+- [OceanBase](https://github.com/oceanbase/oceanbase) /
+  [seekdb](https://github.com/oceanbase/seekdb) — first-class supported
+  databases for checkpoint and store persistence
+- [Redis](https://github.com/redis/redis) — run queue, worker lease, and
+  stream-event persistence when `EXECUTOR_BACKEND=redis`
+- [FastAPI](https://github.com/tiangolo/fastapi) — HTTP framework for every
+  `/assistants`, `/threads`, `/runs`, `/mcp`, `/a2a` surface
+- [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol/python-sdk)
+  — registered graphs exposed as MCP tools over Streamable HTTP at `/mcp`
+- [A2A SDK](https://github.com/a2aproject/a2a-python) — assistant-to-assistant
+  RPC and agent-card discovery shape under `/a2a`
+
+<details>
+<summary>Full dependency list</summary>
+
+**Runtime & API**
+- [Uvicorn](https://github.com/encode/uvicorn) — ASGI server used by
+  `agentseek-api dev` and `serve`
+- [Pydantic](https://github.com/pydantic/pydantic) and pydantic-settings —
+  request/response models and env-driven configuration
+- [scalar-fastapi](https://github.com/scalar/scalar) — alternate API docs
+  rendering at `/scalar`
+
+**LangChain / LangGraph stack**
+- [LangChain Core](https://github.com/langchain-ai/langchain) and
+  [langgraph-sdk](https://github.com/langchain-ai/langgraph) — message,
+  tool, and SDK contracts the API speaks
+- [langchain-openai](https://github.com/langchain-ai/langchain) /
+  [langchain-anthropic](https://github.com/langchain-ai/langchain) —
+  provider integrations used by sample graphs and live-provider CI
+- [Agent Protocol](https://github.com/langchain-ai/agent-protocol) —
+  external compatibility reference for the assistants/threads/runs surface
+
+**Database drivers**
+- [SQLAlchemy](https://github.com/sqlalchemy/sqlalchemy) (async) plus
+  [asyncpg](https://github.com/MagicStack/asyncpg) (PostgreSQL),
+  [aiomysql](https://github.com/aio-libs/aiomysql) and
+  [PyMySQL](https://github.com/PyMySQL/PyMySQL) (MySQL family),
+  [aiosqlite](https://github.com/omnilib/aiosqlite) (SQLite)
+- [redis-py](https://github.com/redis/redis-py) — async Redis client
+
+**Interop**
+- [LangSmith Studio](https://smith.langchain.com/) — external UI that
+  connects to the local API for graph inspection and runs
+
+**Packaging & runtime delivery**
+- [uv](https://github.com/astral-sh/uv) — dependency resolution and the
+  recommended way to run the CLI
+- [Hatchling](https://github.com/pypa/hatch) — wheel build backend
+- [Docker](https://www.docker.com/) — `dockerfile`, `build`, and `up`
+  commands generate and run a containerized API
+
+</details>