agent-chat-fastapi-langgraph-assistant-ui 0.2.0__tar.gz → 0.3.3__tar.gz

agent_chat_fastapi_langgraph_assistant_ui-0.3.3/.gitignore

@@ -0,0 +1,5 @@
+/dist/
+/src/agent_chat_minimal/web/*
+!/src/agent_chat_minimal/web/.gitkeep
+/src/agent_chat_minimal/web_full/*
+!/src/agent_chat_minimal/web_full/.gitkeep

{agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-chat-fastapi-langgraph-assistant-ui
-Version: 0.2.0
+Version: 0.3.3
 Summary: Portable FastAPI and LangGraph chat with a bundled static UI
 Requires-Python: >=3.11
 Requires-Dist: assistant-stream-ce>=0.0.2
@@ -45,9 +45,11 @@ python -m pip install packages/agent-chat-minimal/dist/*.whl
 minimal-chat-serve --port 8011
 ```
 
-Open <http://localhost:8011/>. Set `OPENAI_API_KEY` to enable `/assistant`;
-without it, the UI and `/health` still work and `/assistant` returns 503.
-`MINIMAL_WEB_DIR` may override the bundled web directory.
+Open <http://localhost:8011/> (single-prompt chat) or
+<http://localhost:8011/full/> (thread sidebar with previous chats).
+Set `OPENAI_API_KEY` to enable `/assistant`; without it, the UIs and
+`/health` still work and `/assistant` returns 503.
+`MINIMAL_WEB_DIR` / `FULL_WEB_DIR` may override the bundled web directories.
 
 ## Arbitrary agents & providers
 
@@ -70,6 +72,30 @@ app = create_app(graph=make_my_agent("anthropic:claude-sonnet-4-5"))
   `state.thread_id` / `runConfig.thread_id` is forwarded as LangGraph
   `configurable.thread_id` for checkpointer-backed graphs.
 
+## Documentation (in the wheel)
+
+Six guides ship inside the package and are readable at runtime:
+
+```python
+from agent_chat_minimal import docs
+docs.list()           # ['index', 'quickstart', 'agents', ...]
+docs.show("threads")
+```
+
+| Guide | Covers |
+| ----- | ------ |
+| `quickstart` | install → first chat in 2 minutes |
+| `agents` | write + serve + share your own agent |
+| `providers` | OpenAI / Anthropic / Ollama specs & creds |
+| `configuration` | env vars, CLI flags, hooks, 503 semantics |
+| `threads` | multi-thread chats, frontend-full compat |
+
+## Threads (frontend-full compatible)
+
+The server also speaks the full-stack thread protocol (`/threads`,
+`/threads/{id}/messages`, scoped `POST /assistant` with `thread_id`/`user_id`),
+so `frontend-full` works against either backend. See the `threads` guide.
+
 ## Configuration
 
 ```text

{agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.3}/README.md

@@ -28,9 +28,11 @@ python -m pip install packages/agent-chat-minimal/dist/*.whl
 minimal-chat-serve --port 8011
 ```
 
-Open <http://localhost:8011/>. Set `OPENAI_API_KEY` to enable `/assistant`;
-without it, the UI and `/health` still work and `/assistant` returns 503.
-`MINIMAL_WEB_DIR` may override the bundled web directory.
+Open <http://localhost:8011/> (single-prompt chat) or
+<http://localhost:8011/full/> (thread sidebar with previous chats).
+Set `OPENAI_API_KEY` to enable `/assistant`; without it, the UIs and
+`/health` still work and `/assistant` returns 503.
+`MINIMAL_WEB_DIR` / `FULL_WEB_DIR` may override the bundled web directories.
 
 ## Arbitrary agents & providers
 
@@ -53,6 +55,30 @@ app = create_app(graph=make_my_agent("anthropic:claude-sonnet-4-5"))
   `state.thread_id` / `runConfig.thread_id` is forwarded as LangGraph
   `configurable.thread_id` for checkpointer-backed graphs.
 
+## Documentation (in the wheel)
+
+Six guides ship inside the package and are readable at runtime:
+
+```python
+from agent_chat_minimal import docs
+docs.list()           # ['index', 'quickstart', 'agents', ...]
+docs.show("threads")
+```
+
+| Guide | Covers |
+| ----- | ------ |
+| `quickstart` | install → first chat in 2 minutes |
+| `agents` | write + serve + share your own agent |
+| `providers` | OpenAI / Anthropic / Ollama specs & creds |
+| `configuration` | env vars, CLI flags, hooks, 503 semantics |
+| `threads` | multi-thread chats, frontend-full compat |
+
+## Threads (frontend-full compatible)
+
+The server also speaks the full-stack thread protocol (`/threads`,
+`/threads/{id}/messages`, scoped `POST /assistant` with `thread_id`/`user_id`),
+so `frontend-full` works against either backend. See the `threads` guide.
+
 ## Configuration
 
 ```text

{agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agent-chat-fastapi-langgraph-assistant-ui"
-version = "0.2.0"
+version = "0.3.3"
 description = "Portable FastAPI and LangGraph chat with a bundled static UI"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -33,13 +33,20 @@ minimal-chat-serve = "agent_chat_minimal.server:main"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/agent_chat_minimal"]
+# The tracked .gitkeep placeholders would otherwise be collected twice (once
+# via `packages`, once via `force-include`) and fail the build with "A second
+# file is being added to the wheel archive at the same path".
+exclude = ["**/.gitkeep"]
 
 [tool.hatch.build.targets.wheel.force-include]
 "src/agent_chat_minimal/web" = "agent_chat_minimal/web"
+"src/agent_chat_minimal/web_full" = "agent_chat_minimal/web_full"
 
-# The sdist must also bundle the prebuilt static UI (which is gitignored and
-# staged from application/frontend/frontend-minimal/out before building).
+# The sdist file list comes from git, where the staged prebuilt UIs are
+# ignored - so they must be force-included here (staged from
+# application/frontend/{frontend-minimal,frontend-full}/out before building).
 # python -m build builds the wheel from the sdist, so without this the PyPI
-# wheel would ship without the UI.
+# wheel would ship without the UIs.
 [tool.hatch.build.targets.sdist.force-include]
 "src/agent_chat_minimal/web" = "src/agent_chat_minimal/web"
+"src/agent_chat_minimal/web_full" = "src/agent_chat_minimal/web_full"

agent_chat_fastapi_langgraph_assistant_ui-0.3.3/scripts/build_wheel.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
+frontend_minimal="$repo_root/application/frontend/frontend-minimal"
+frontend_full="$repo_root/application/frontend/frontend-full"
+package="$repo_root/packages/agent-chat-minimal"
+web="$package/src/agent_chat_minimal/web"
+web_full="$package/src/agent_chat_minimal/web_full"
+
+cleanup() {
+  rm -rf "$web" "$web_full"
+  mkdir -p "$web" "$web_full"
+  : > "$web/.gitkeep"
+  : > "$web_full/.gitkeep"
+}
+trap cleanup EXIT
+
+pnpm --dir "$frontend_minimal" install --frozen-lockfile
+pnpm --dir "$frontend_minimal" build
+rm -rf "$web"
+cp -R "$frontend_minimal/out" "$web"
+
+# Full UI (thread sidebar) is namespaced under /full and talks same-origin.
+pnpm --dir "$frontend_full" install --frozen-lockfile
+NEXT_PUBLIC_API_BASE="" FULL_UI_BASE_PATH=/full pnpm --dir "$frontend_full" build
+rm -rf "$web_full"
+cp -R "$frontend_full/out" "$web_full"
+
+(
+  cd "$package"
+  uv build --wheel
+)

agent_chat_fastapi_langgraph_assistant_ui-0.3.3/src/agent_chat_minimal/__init__.py

@@ -0,0 +1,51 @@
+"""Portable FastAPI + LangGraph chat with a bundled Assistant UI.
+
+Quick links (also shipped as markdown in ``agent_chat_minimal/docs/``):
+
+- ``docs.list()`` / ``docs.get(name)`` — guides: quickstart, agents,
+  providers, configuration, threads.
+- ``create_app(...)`` — serve one graph, a factory, or an agent registry.
+- ``Settings.from_env()`` — all env vars in one place.
+- ``GET /docs`` on a running server — interactive Swagger UI.
+
+Example:
+    >>> from agent_chat_minimal import create_app
+    >>> app = create_app(agents={"weather": ...})  # doctest: +SKIP
+"""
+
+from . import docs
+from .config import ENV_DOC, Settings
+from .registry import AGENT_REGISTRY, discover_agents
+from .server import (
+    DEFAULT_WEB_DIR,
+    DEFAULT_WEB_FULL_DIR,
+    ChatGraph,
+    ScopedChatRequest,
+    create_app,
+    default_prepare_state,
+    main,
+    resolve_thread_id,
+)
+from .threads import ThreadManager, ThreadMessageStore, ThreadMetadata
+
+__version__ = "0.3.3"
+
+__all__ = [
+    "__version__",
+    "AGENT_REGISTRY",
+    "ENV_DOC",
+    "ChatGraph",
+    "DEFAULT_WEB_DIR",
+    "DEFAULT_WEB_FULL_DIR",
+    "ScopedChatRequest",
+    "Settings",
+    "ThreadManager",
+    "ThreadMessageStore",
+    "ThreadMetadata",
+    "create_app",
+    "default_prepare_state",
+    "discover_agents",
+    "docs",
+    "main",
+    "resolve_thread_id",
+]

{agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.3}/src/agent_chat_minimal/config.py

@@ -16,6 +16,7 @@ class Settings:
     model: str = "openai:gpt-4o-mini"
     default_agent: str = "weather"
     web_dir: str | None = None
+    web_full_dir: str | None = None
 
     @classmethod
     def from_env(cls) -> "Settings":
@@ -30,6 +31,7 @@ class Settings:
             model=os.getenv("MODEL", "openai:gpt-4o-mini"),
             default_agent=os.getenv("DEFAULT_AGENT", "weather"),
             web_dir=os.getenv("MINIMAL_WEB_DIR"),
+            web_full_dir=os.getenv("FULL_WEB_DIR"),
         )
 
     def web_dir_path(self, fallback: Path) -> Path | None:
@@ -44,6 +46,7 @@ PORT=8011                   # uvicorn bind port
 MODEL=openai:gpt-4o-mini    # provider:model spec (anthropic:.., ollama:..)
 DEFAULT_AGENT=weather       # registry id aliased by POST /assistant
 MINIMAL_WEB_DIR=            # override bundled web/ (empty = bundled)
+FULL_WEB_DIR=               # override bundled web_full/ (empty = bundled)
 OPENAI_API_KEY=             # credential for the default openai model
 ANTHROPIC_API_KEY=          # credential when MODEL uses anthropic:
 """

{agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.3}/src/agent_chat_minimal/demo_agent/agent_factory.py

@@ -1,6 +1,6 @@
 """Shared helpers for building provider-agnostic tool agents (#12)."""
 
-from typing import Annotated, TypedDict
+from typing import Annotated, Any, TypedDict
 
 from langchain_core.language_models.chat_models import BaseChatModel
 from langchain_core.messages import BaseMessage
@@ -32,8 +32,19 @@ def make_tool_agent(
     model: str | BaseChatModel,
     tools: list,
     system_prompt: str | None = None,
+    checkpointer: Any | None = None,
 ) -> StateGraph:
-    """Build a compiled ``agent <-> tools`` graph for any tool list."""
+    """Build a compiled ``agent <-> tools`` graph for any tool list.
+
+    Args:
+        model: ``provider:name`` spec (see :mod:`docs/providers`) or a chat
+            model instance.
+        tools: LangChain tools bound to the model and served by a ``ToolNode``.
+        system_prompt: Optional system message prepended at invoke time.
+        checkpointer: Optional LangGraph checkpointer (e.g. ``MemorySaver()``).
+            Compiling with one enables per-``thread_id`` persistence: pass
+            ``config={"configurable": {"thread_id": ...}}`` at invoke time.
+    """
     llm = resolve_llm(model).bind_tools(tools)
     tool_node = ToolNode(tools)
 
@@ -53,4 +64,4 @@ def make_tool_agent(
     workflow.set_entry_point("agent")
     workflow.add_conditional_edges("agent", tools_condition)
     workflow.add_edge("tools", "agent")
-    return workflow.compile()
+    return workflow.compile(checkpointer=checkpointer)

{agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.3}/src/agent_chat_minimal/demo_agent/calculator.py

@@ -44,6 +44,9 @@ CALCULATOR_SYSTEM_PROMPT = (
 
 def make_calculator_agent(
     model: str | BaseChatModel = "openai:gpt-4o-mini",
+    checkpointer=None,
 ) -> StateGraph:
     """Build the calculator agent for any provider model spec/instance."""
-    return make_tool_agent(model, list(CALCULATOR_TOOLS), CALCULATOR_SYSTEM_PROMPT)
+    return make_tool_agent(
+        model, list(CALCULATOR_TOOLS), CALCULATOR_SYSTEM_PROMPT, checkpointer
+    )

{agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.3}/src/agent_chat_minimal/demo_agent/get_graph.py

@@ -19,6 +19,7 @@ def get_weather(city: str):
 
 def make_agent_with_weather_tool(
     model: str | BaseChatModel = "openai:gpt-4o-mini",
+    checkpointer=None,
 ) -> StateGraph:
     """Build the weather demo agent for any provider model spec/instance.
 
@@ -31,4 +32,4 @@ def make_agent_with_weather_tool(
     if model == "gpt-4o-mini":  # backward compat: bare legacy default
         model = "openai:gpt-4o-mini"
     tools = [get_weather, render_graph]
-    return make_tool_agent(model, tools)
+    return make_tool_agent(model, tools, checkpointer=checkpointer)

agent_chat_fastapi_langgraph_assistant_ui-0.3.3/src/agent_chat_minimal/docs/agents.md

@@ -0,0 +1,74 @@
+# Implementing an agent
+
+Any compiled LangGraph graph over `{"messages": [...]}` is servable. The only
+contract (see `ChatGraph` in `server.py`) is:
+
+```python
+graph.astream(input, config=..., stream_mode=[...], subgraphs=True)
+# yields (namespace, event_type, chunk) triples
+```
+
+## Minimal custom agent (5 minutes)
+
+```python
+# my_agent.py
+from langchain_core.tools import tool
+from agent_chat_minimal.demo_agent.agent_factory import make_tool_agent
+
+@tool
+def shout(text: str) -> str:
+    """Uppercase the input."""
+    return text.upper()
+
+def make_shout_agent(model="openai:gpt-4o-mini", checkpointer=None):
+    return make_tool_agent(model, [shout], "Reply ONLY with the tool result.")
+```
+
+Serve it — no server fork needed:
+
+```python
+# serve.py
+from agent_chat_minimal import create_app
+from my_agent import make_shout_agent
+
+app = create_app(graph_factory=make_shout_agent)
+# python -m uvicorn serve:app --port 8011
+```
+
+Prefer an instance? `create_app(graph=make_shout_agent(...))` works too;
+the factory form defers credential errors to startup instead of import.
+
+## Multi-agent serving
+
+```python
+app = create_app(agents={"shout": make_shout_agent})
+# POST /assistant/shout, GET /agents -> ["calculator","shout","weather"]
+```
+
+`POST /assistant` aliases the `default_agent` (`"weather"` unless overridden).
+
+## Reference: calculator agent
+
+`demo_agent/calculator.py` (`add`/`subtract`/`multiply`/`divide` +
+`make_calculator_agent`) is the canonical example: tools, system prompt,
+provider-agnostic model arg, optional `checkpointer` passthrough.
+
+## Sharing via pip (no fork)
+
+Register the `agent_chat.agents` entry-points group:
+
+```toml
+[project.entry-points."agent_chat.agents"]
+shout = "my_package.my_agent:make_shout_agent"
+```
+
+`discover_agents()` picks it up automatically alongside the built-ins.
+
+## Checklist
+
+- [ ] Factory signature `(model=..., checkpointer=None)` so the server can
+      inject the shared checkpointer.
+- [ ] Tools have clear docstrings — the model only sees those.
+- [ ] Offline test with a fake model (see `tests/test_provider_agnostic.py`).
+- [ ] `minimal-chat-serve --agent shout --check` builds without network creds
+      only if the model is fake/local; otherwise expect a credential error.

agent_chat_fastapi_langgraph_assistant_ui-0.3.3/src/agent_chat_minimal/docs/configuration.md

@@ -0,0 +1,60 @@
+# Configuration
+
+Single source of truth: `Settings` in `config.py` (stdlib only, no extra
+dependency). CLI flags override env vars.
+
+## Environment
+
+```text
+HOST=0.0.0.0                # uvicorn bind host
+PORT=8011                   # uvicorn bind port
+MODEL=openai:gpt-4o-mini    # provider:model spec (see providers.md)
+DEFAULT_AGENT=weather       # registry id aliased by POST /assistant
+MINIMAL_WEB_DIR=            # override bundled web/ (empty = bundled)
+OPENAI_API_KEY=             # credential for the default openai model
+ANTHROPIC_API_KEY=          # credential when MODEL uses anthropic:
+```
+
+```python
+from agent_chat_minimal import Settings
+Settings.from_env()  # Settings(host='0.0.0.0', port=8011, ...)
+```
+
+## CLI
+
+```bash
+minimal-chat-serve --host 127.0.0.1 --port 8011 \
+  --model ollama:llama3.1 --agent calculator
+minimal-chat-serve --agent weather --check   # build graph, exit, no server
+```
+
+`--check` is the fast CI smoke test: non-zero exit with the real factory
+error when credentials are missing.
+
+## Hooks (`create_app(...)`)
+
+| Parameter        | Purpose                                            |
+| ---------------- | -------------------------------------------------- |
+| `graph=`         | Serve one prebuilt graph (`/agents == ["default"]`)|
+| `graph_factory=` | Deferred single-graph build (errors at startup)    |
+| `agents=`        | Name → factory map (multi-agent mode)              |
+| `default_agent=` | Id aliased by `POST /assistant`                    |
+| `web_dir=`       | Override the bundled UI directory                  |
+| `prepare_state=` | `(state, request) -> message dicts` reducer        |
+| `checkpointer=`  | Shared checkpointer (`"memory"` default, see below)|
+| `thread_manager=`/`message_store=` | Swap thread storage (tests)          |
+
+## Checkpointer
+
+`"memory"` (default) builds one shared `MemorySaver` and passes it to every
+factory whose signature accepts `checkpointer`. Per-`thread_id` graph state
+then persists across requests (see [threads.md](threads.md)). Pass an explicit
+saver instance for custom backends, or `None` to disable injection.
+
+## `/assistant` 503 semantics
+
+- Default registry + no `OPENAI_API_KEY` → legacy
+  `{"error": "OPENAI_API_KEY not configured", ...}` (backward compatible).
+- Custom graph/factory failure →
+  `{"error": "agent_not_ready", "message": ..., "hint": ...}` with the real
+  factory exception in `hint`.

agent_chat_fastapi_langgraph_assistant_ui-0.3.3/src/agent_chat_minimal/docs/index.md

@@ -0,0 +1,29 @@
+# agent-chat-minimal — documentation index
+
+Portable FastAPI + LangGraph chat server with a bundled Assistant UI.
+Install from PyPI (Python 3.11+, no Node needed) and serve one command:
+
+```bash
+pip install agent-chat-fastapi-langgraph-assistant-ui
+minimal-chat-serve --port 8011
+```
+
+Guides (shipped inside the wheel under `agent_chat_minimal/docs/`):
+
+- [quickstart.md](quickstart.md) — install, serve, first chat (2 minutes).
+- [agents.md](agents.md) — implement and serve your own agent.
+- [providers.md](providers.md) — model specs for OpenAI, Anthropic, Ollama, ….
+- [configuration.md](configuration.md) — env vars, CLI flags, hooks.
+- [threads.md](threads.md) — multi-thread chats, frontend-full compatibility.
+- [index.md](index.md) — this file: architecture overview.
+
+Discoverability: every guide is readable at runtime without unpacking the wheel:
+
+```python
+from agent_chat_minimal import docs
+docs.list()          # ['agents', 'configuration', ...]
+print(docs.get("agents"))
+docs.show("threads") # prints to stdout
+```
+
+FastAPI also serves interactive Swagger UI at `GET /docs` when the server runs.

agent_chat_fastapi_langgraph_assistant_ui-0.3.3/src/agent_chat_minimal/docs/providers.md

@@ -0,0 +1,42 @@
+# Model providers
+
+Factories take either a `provider:name` spec (resolved via LangChain's
+`init_chat_model`) or an already-built chat model instance.
+
+## Specs
+
+| Spec prefix | Example                     | Credential env      | Install extra        |
+| ----------- | --------------------------- | ------------------- | -------------------- |
+| `openai:`   | `openai:gpt-4o-mini`        | `OPENAI_API_KEY`    | `langchain-openai` ✓ |
+| `anthropic:`| `anthropic:claude-sonnet-4-5` | `ANTHROPIC_API_KEY` | `langchain-anthropic`|
+| `ollama:`   | `ollama:llama3.1`           | none (local daemon) | `langchain-ollama`   |
+| `google_genai:` | `google_genai:gemini-2.5-flash` | `GOOGLE_API_KEY`| `langchain-google-genai` |
+
+✓ = bundled with this wheel. Others need their LangChain partner package;
+the import happens lazily, only when that provider is selected.
+
+Bare `gpt-4o-mini` still works (provider inferred as OpenAI) for backward
+compatibility; prefer the explicit `openai:` prefix.
+
+## Selecting the model
+
+```bash
+MODEL=anthropic:claude-sonnet-4-5 minimal-chat-serve
+minimal-chat-serve --model ollama:llama3.1 --agent calculator
+```
+
+## Instances and offline tests
+
+Pass any `BaseChatModel` (streaming or fake) straight in:
+
+```python
+from langchain_core.language_models.fake_chat_models import GenericFakeChatModel
+
+class Bindable(GenericFakeChatModel):
+    def bind_tools(self, *a, **k):
+        return self  # base class raises NotImplementedError
+
+graph = make_calculator_agent(Bindable(messages=iter([...])))
+```
+
+This is how the bundled tests run the full agent loop with no network.

agent_chat_fastapi_langgraph_assistant_ui-0.3.3/src/agent_chat_minimal/docs/quickstart.md

@@ -0,0 +1,45 @@
+# Quickstart
+
+## Install
+
+```bash
+pip install agent-chat-fastapi-langgraph-assistant-ui
+```
+
+Or from this repo (builds the UI + wheel; Node/pnpm needed only here):
+
+```bash
+packages/agent-chat-minimal/scripts/build_wheel.sh
+python -m pip install packages/agent-chat-minimal/dist/*.whl
+```
+
+## Serve
+
+```bash
+export OPENAI_API_KEY=sk-...
+minimal-chat-serve --port 8011
+# open http://localhost:8011/
+```
+
+Without `OPENAI_API_KEY`, the UI and `GET /health` still work; `POST /assistant`
+returns 503 with setup instructions.
+
+## First chat
+
+```bash
+curl -s localhost:8011/health
+# {"status":"ok"}
+
+curl -s localhost:8011/agents
+# {"agents":["calculator","weather"],"default":"weather"}
+```
+
+In the UI, try *"What is 12 × 8?"* (calculator) or *"Weather in London?"*.
+For the sidebar with previous chats, open <http://localhost:8011/full/>.
+
+## Next steps
+
+- Custom agent? → [agents.md](agents.md).
+- Another model provider? → [providers.md](providers.md).
+- Env vars and flags? → [configuration.md](configuration.md).
+- Threaded chats / frontend-full? → [threads.md](threads.md).

agent_chat_fastapi_langgraph_assistant_ui-0.3.3/src/agent_chat_minimal/docs/threads.md

@@ -0,0 +1,72 @@
+# Threads (multi-conversation chats)
+
+The portable server speaks the same thread protocol as the full backend, so
+`frontend-full` (thread list, history, multiple chats) works against either
+server. Single-prompt clients can ignore this page entirely.
+
+## Concepts
+
+- **Thread**: a conversation id. Metadata (title, owner, archived) is kept by
+  `ThreadManager`; content lives in two places:
+  - assistant-ui message objects, stored verbatim per thread (tool UI parts
+    rehydrate on reload);
+  - LangGraph checkpointer state keyed by `thread_id` (graph-side memory).
+- **Scoped request**: `POST /assistant` accepts `thread_id`/`user_id`
+  top-level fields (plus the classic `commands`/`state`). Missing ids are
+  auto-generated and their metadata auto-created — the same behavior as the
+  full backend.
+
+## Endpoints
+
+```text
+GET    /threads[?user_id=&include_archived=]
+POST   /threads                       {localId, user_id?, title?}
+GET    /threads/{id}                  PATCH /threads/{id} {title}
+POST   /threads/{id}/archive|unarchive
+DELETE /threads/{id}                  (also drops stored messages)
+GET    /threads/{id}/messages         (persisted UI messages, else checkpointer fallback)
+POST   /threads/{id}/messages         {message}  (history.append hook)
+POST   /assistant  POST /assistant/{agent_id}    (scoped shape supported)
+```
+
+## Example flow
+
+```bash
+curl -X POST localhost:8011/threads -H 'Content-Type: application/json' \
+  -d '{"localId":"trip","title":"Trip planning"}'
+
+curl -X POST localhost:8011/assistant -H 'Content-Type: application/json' \
+  -d '{"thread_id":"trip","state":{"thread_id":"trip"},"commands":[]}'
+
+curl localhost:8011/threads/trip/messages
+```
+
+## Frontend-full compatibility
+
+## Bundled full UI
+
+The wheel ships the full frontend (thread sidebar) at `/full/` — no separate
+Next.js server needed. It is built with `NEXT_PUBLIC_API_BASE=""` so it talks
+to the same origin (`/assistant`, `/threads`). The minimal single-prompt chat
+stays at `/`. To serve a custom full build instead:
+
+```bash
+FULL_WEB_DIR=/path/to/frontend-full/out minimal-chat-serve
+```
+
+Pointing an external full frontend at the portable server also works
+(`NEXT_PUBLIC_API_URL` without the trailing `/assistant`); thread list,
+switching, rename, archive, and history rehydration all use the endpoints
+above. Responses stream over the Assistant Stream protocol with
+`messages`/`updates`/`custom` events, including `tool_updates` progress
+entries like the full backend.
+
+## Persistence notes
+
+- Default storage is in-memory (`MemorySaver` + dicts): restarts lose it —
+  identical to the full backend's default. Restart-safe backends plug in via
+  `create_app(checkpointer=<saver>)`.
+- History larger than the 500-message store cap (or 200 tool updates) is
+  trimmed oldest-first.
+- AI messages with `tool_calls` but no matching `ToolMessage` are dropped
+  before invoke (invalid-history guard, same as full backend).