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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (65) hide show
  1. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/PKG-INFO +25 -1
  2. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/README.md +24 -0
  3. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/pyproject.toml +1 -1
  4. agent_chat_fastapi_langgraph_assistant_ui-0.3.1/src/agent_chat_minimal/__init__.py +47 -0
  5. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/src/agent_chat_minimal/demo_agent/agent_factory.py +14 -3
  6. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/src/agent_chat_minimal/demo_agent/calculator.py +4 -1
  7. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/src/agent_chat_minimal/demo_agent/get_graph.py +2 -1
  8. agent_chat_fastapi_langgraph_assistant_ui-0.3.1/src/agent_chat_minimal/docs/agents.md +74 -0
  9. agent_chat_fastapi_langgraph_assistant_ui-0.3.1/src/agent_chat_minimal/docs/configuration.md +60 -0
  10. agent_chat_fastapi_langgraph_assistant_ui-0.3.1/src/agent_chat_minimal/docs/index.md +29 -0
  11. agent_chat_fastapi_langgraph_assistant_ui-0.3.1/src/agent_chat_minimal/docs/providers.md +42 -0
  12. agent_chat_fastapi_langgraph_assistant_ui-0.3.1/src/agent_chat_minimal/docs/quickstart.md +44 -0
  13. agent_chat_fastapi_langgraph_assistant_ui-0.3.1/src/agent_chat_minimal/docs/threads.md +60 -0
  14. agent_chat_fastapi_langgraph_assistant_ui-0.3.1/src/agent_chat_minimal/docs.py +35 -0
  15. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/src/agent_chat_minimal/registry.py +8 -4
  16. agent_chat_fastapi_langgraph_assistant_ui-0.3.1/src/agent_chat_minimal/server.py +611 -0
  17. agent_chat_fastapi_langgraph_assistant_ui-0.3.1/src/agent_chat_minimal/threads.py +111 -0
  18. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/src/agent_chat_minimal/web/404/index.html +1 -1
  19. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/src/agent_chat_minimal/web/404.html +1 -1
  20. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/src/agent_chat_minimal/web/__next.__PAGE__.txt +1 -1
  21. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/src/agent_chat_minimal/web/__next._full.txt +1 -1
  22. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/src/agent_chat_minimal/web/__next._head.txt +1 -1
  23. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/src/agent_chat_minimal/web/__next._index.txt +1 -1
  24. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/src/agent_chat_minimal/web/__next._tree.txt +1 -1
  25. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/src/agent_chat_minimal/web/_not-found/__next._full.txt +1 -1
  26. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/src/agent_chat_minimal/web/_not-found/__next._head.txt +1 -1
  27. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/src/agent_chat_minimal/web/_not-found/__next._index.txt +1 -1
  28. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/src/agent_chat_minimal/web/_not-found/__next._not-found.__PAGE__.txt +1 -1
  29. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/src/agent_chat_minimal/web/_not-found/__next._not-found.txt +1 -1
  30. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/src/agent_chat_minimal/web/_not-found/__next._tree.txt +1 -1
  31. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/src/agent_chat_minimal/web/_not-found/index.html +1 -1
  32. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/src/agent_chat_minimal/web/_not-found/index.txt +1 -1
  33. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/src/agent_chat_minimal/web/index.html +1 -1
  34. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/src/agent_chat_minimal/web/index.txt +1 -1
  35. agent_chat_fastapi_langgraph_assistant_ui-0.3.1/tests/test_docs.py +25 -0
  36. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/tests/test_provider_agnostic.py +1 -1
  37. agent_chat_fastapi_langgraph_assistant_ui-0.3.1/tests/test_threads.py +143 -0
  38. agent_chat_fastapi_langgraph_assistant_ui-0.2.0/src/agent_chat_minimal/__init__.py +0 -24
  39. agent_chat_fastapi_langgraph_assistant_ui-0.2.0/src/agent_chat_minimal/server.py +0 -336
  40. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/.gitignore +0 -0
  41. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/Dockerfile +0 -0
  42. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/scripts/build_wheel.sh +0 -0
  43. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/scripts/smoke_test_wheel.sh +0 -0
  44. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/src/agent_chat_minimal/config.py +0 -0
  45. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/src/agent_chat_minimal/demo_agent/__init__.py +0 -0
  46. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/src/agent_chat_minimal/demo_agent/tools/__init__.py +0 -0
  47. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/src/agent_chat_minimal/demo_agent/tools/graph_tool.py +0 -0
  48. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0/src/agent_chat_minimal/web/_next/static/HvflKuXozGvVNVw4d_lvG → agent_chat_fastapi_langgraph_assistant_ui-0.3.1/src/agent_chat_minimal/web/_next/static/BzWZ954gzLDjEf0nOKNVt}/_buildManifest.js +0 -0
  49. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0/src/agent_chat_minimal/web/_next/static/HvflKuXozGvVNVw4d_lvG → agent_chat_fastapi_langgraph_assistant_ui-0.3.1/src/agent_chat_minimal/web/_next/static/BzWZ954gzLDjEf0nOKNVt}/_clientMiddlewareManifest.json +0 -0
  50. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0/src/agent_chat_minimal/web/_next/static/HvflKuXozGvVNVw4d_lvG → agent_chat_fastapi_langgraph_assistant_ui-0.3.1/src/agent_chat_minimal/web/_next/static/BzWZ954gzLDjEf0nOKNVt}/_ssgManifest.js +0 -0
  51. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/src/agent_chat_minimal/web/_next/static/chunks/01753452ac5baafa.js +0 -0
  52. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/src/agent_chat_minimal/web/_next/static/chunks/30d8e87dcbdddc4d.js +0 -0
  53. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/src/agent_chat_minimal/web/_next/static/chunks/339892169798c284.js +0 -0
  54. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/src/agent_chat_minimal/web/_next/static/chunks/4a95dc46ade64fde.js +0 -0
  55. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/src/agent_chat_minimal/web/_next/static/chunks/8c25bd17dcc24038.css +0 -0
  56. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/src/agent_chat_minimal/web/_next/static/chunks/a09b0e81b13178b3.css +0 -0
  57. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/src/agent_chat_minimal/web/_next/static/chunks/a6dad97d9634a72d.js +0 -0
  58. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/src/agent_chat_minimal/web/_next/static/chunks/a6dad97d9634a72d.js.map +0 -0
  59. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/src/agent_chat_minimal/web/_next/static/chunks/c1f433e6da65e45d.js +0 -0
  60. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/src/agent_chat_minimal/web/_next/static/chunks/e54de45640ef90a8.js +0 -0
  61. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/src/agent_chat_minimal/web/_next/static/chunks/turbopack-6a8c15a03bc4b465.js +0 -0
  62. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/tests/test_config_state.py +0 -0
  63. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/tests/test_injectable_graph.py +0 -0
  64. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/tests/test_registry.py +0 -0
  65. {agent_chat_fastapi_langgraph_assistant_ui-0.2.0 → agent_chat_fastapi_langgraph_assistant_ui-0.3.1}/tests/test_serving.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: agent-chat-fastapi-langgraph-assistant-ui
3
- Version: 0.2.0
3
+ Version: 0.3.1
4
4
  Summary: Portable FastAPI and LangGraph chat with a bundled static UI
5
5
  Requires-Python: >=3.11
6
6
  Requires-Dist: assistant-stream-ce>=0.0.2
@@ -70,6 +70,30 @@ app = create_app(graph=make_my_agent("anthropic:claude-sonnet-4-5"))
70
70
  `state.thread_id` / `runConfig.thread_id` is forwarded as LangGraph
71
71
  `configurable.thread_id` for checkpointer-backed graphs.
72
72
 
73
+ ## Documentation (in the wheel)
74
+
75
+ Six guides ship inside the package and are readable at runtime:
76
+
77
+ ```python
78
+ from agent_chat_minimal import docs
79
+ docs.list() # ['index', 'quickstart', 'agents', ...]
80
+ docs.show("threads")
81
+ ```
82
+
83
+ | Guide | Covers |
84
+ | ----- | ------ |
85
+ | `quickstart` | install → first chat in 2 minutes |
86
+ | `agents` | write + serve + share your own agent |
87
+ | `providers` | OpenAI / Anthropic / Ollama specs & creds |
88
+ | `configuration` | env vars, CLI flags, hooks, 503 semantics |
89
+ | `threads` | multi-thread chats, frontend-full compat |
90
+
91
+ ## Threads (frontend-full compatible)
92
+
93
+ The server also speaks the full-stack thread protocol (`/threads`,
94
+ `/threads/{id}/messages`, scoped `POST /assistant` with `thread_id`/`user_id`),
95
+ so `frontend-full` works against either backend. See the `threads` guide.
96
+
73
97
  ## Configuration
74
98
 
75
99
  ```text
@@ -53,6 +53,30 @@ app = create_app(graph=make_my_agent("anthropic:claude-sonnet-4-5"))
53
53
  `state.thread_id` / `runConfig.thread_id` is forwarded as LangGraph
54
54
  `configurable.thread_id` for checkpointer-backed graphs.
55
55
 
56
+ ## Documentation (in the wheel)
57
+
58
+ Six guides ship inside the package and are readable at runtime:
59
+
60
+ ```python
61
+ from agent_chat_minimal import docs
62
+ docs.list() # ['index', 'quickstart', 'agents', ...]
63
+ docs.show("threads")
64
+ ```
65
+
66
+ | Guide | Covers |
67
+ | ----- | ------ |
68
+ | `quickstart` | install → first chat in 2 minutes |
69
+ | `agents` | write + serve + share your own agent |
70
+ | `providers` | OpenAI / Anthropic / Ollama specs & creds |
71
+ | `configuration` | env vars, CLI flags, hooks, 503 semantics |
72
+ | `threads` | multi-thread chats, frontend-full compat |
73
+
74
+ ## Threads (frontend-full compatible)
75
+
76
+ The server also speaks the full-stack thread protocol (`/threads`,
77
+ `/threads/{id}/messages`, scoped `POST /assistant` with `thread_id`/`user_id`),
78
+ so `frontend-full` works against either backend. See the `threads` guide.
79
+
56
80
  ## Configuration
57
81
 
58
82
  ```text
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "agent-chat-fastapi-langgraph-assistant-ui"
7
- version = "0.2.0"
7
+ version = "0.3.1"
8
8
  description = "Portable FastAPI and LangGraph chat with a bundled static UI"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.11"
@@ -0,0 +1,47 @@
1
+ """Portable FastAPI + LangGraph chat with a bundled Assistant UI.
2
+
3
+ Quick links (also shipped as markdown in ``agent_chat_minimal/docs/``):
4
+
5
+ - ``docs.list()`` / ``docs.get(name)`` — guides: quickstart, agents,
6
+ providers, configuration, threads.
7
+ - ``create_app(...)`` — serve one graph, a factory, or an agent registry.
8
+ - ``Settings.from_env()`` — all env vars in one place.
9
+ - ``GET /docs`` on a running server — interactive Swagger UI.
10
+
11
+ Example:
12
+ >>> from agent_chat_minimal import create_app
13
+ >>> app = create_app(agents={"weather": ...}) # doctest: +SKIP
14
+ """
15
+
16
+ from . import docs
17
+ from .config import ENV_DOC, Settings
18
+ from .registry import AGENT_REGISTRY, discover_agents
19
+ from .server import (
20
+ ChatGraph,
21
+ ScopedChatRequest,
22
+ create_app,
23
+ default_prepare_state,
24
+ main,
25
+ resolve_thread_id,
26
+ )
27
+ from .threads import ThreadManager, ThreadMessageStore, ThreadMetadata
28
+
29
+ __version__ = "0.3.1"
30
+
31
+ __all__ = [
32
+ "__version__",
33
+ "AGENT_REGISTRY",
34
+ "ENV_DOC",
35
+ "ChatGraph",
36
+ "ScopedChatRequest",
37
+ "Settings",
38
+ "ThreadManager",
39
+ "ThreadMessageStore",
40
+ "ThreadMetadata",
41
+ "create_app",
42
+ "default_prepare_state",
43
+ "discover_agents",
44
+ "docs",
45
+ "main",
46
+ "resolve_thread_id",
47
+ ]
@@ -1,6 +1,6 @@
1
1
  """Shared helpers for building provider-agnostic tool agents (#12)."""
2
2
 
3
- from typing import Annotated, TypedDict
3
+ from typing import Annotated, Any, TypedDict
4
4
 
5
5
  from langchain_core.language_models.chat_models import BaseChatModel
6
6
  from langchain_core.messages import BaseMessage
@@ -32,8 +32,19 @@ def make_tool_agent(
32
32
  model: str | BaseChatModel,
33
33
  tools: list,
34
34
  system_prompt: str | None = None,
35
+ checkpointer: Any | None = None,
35
36
  ) -> StateGraph:
36
- """Build a compiled ``agent <-> tools`` graph for any tool list."""
37
+ """Build a compiled ``agent <-> tools`` graph for any tool list.
38
+
39
+ Args:
40
+ model: ``provider:name`` spec (see :mod:`docs/providers`) or a chat
41
+ model instance.
42
+ tools: LangChain tools bound to the model and served by a ``ToolNode``.
43
+ system_prompt: Optional system message prepended at invoke time.
44
+ checkpointer: Optional LangGraph checkpointer (e.g. ``MemorySaver()``).
45
+ Compiling with one enables per-``thread_id`` persistence: pass
46
+ ``config={"configurable": {"thread_id": ...}}`` at invoke time.
47
+ """
37
48
  llm = resolve_llm(model).bind_tools(tools)
38
49
  tool_node = ToolNode(tools)
39
50
 
@@ -53,4 +64,4 @@ def make_tool_agent(
53
64
  workflow.set_entry_point("agent")
54
65
  workflow.add_conditional_edges("agent", tools_condition)
55
66
  workflow.add_edge("tools", "agent")
56
- return workflow.compile()
67
+ return workflow.compile(checkpointer=checkpointer)
@@ -44,6 +44,9 @@ CALCULATOR_SYSTEM_PROMPT = (
44
44
 
45
45
  def make_calculator_agent(
46
46
  model: str | BaseChatModel = "openai:gpt-4o-mini",
47
+ checkpointer=None,
47
48
  ) -> StateGraph:
48
49
  """Build the calculator agent for any provider model spec/instance."""
49
- return make_tool_agent(model, list(CALCULATOR_TOOLS), CALCULATOR_SYSTEM_PROMPT)
50
+ return make_tool_agent(
51
+ model, list(CALCULATOR_TOOLS), CALCULATOR_SYSTEM_PROMPT, checkpointer
52
+ )
@@ -19,6 +19,7 @@ def get_weather(city: str):
19
19
 
20
20
  def make_agent_with_weather_tool(
21
21
  model: str | BaseChatModel = "openai:gpt-4o-mini",
22
+ checkpointer=None,
22
23
  ) -> StateGraph:
23
24
  """Build the weather demo agent for any provider model spec/instance.
24
25
 
@@ -31,4 +32,4 @@ def make_agent_with_weather_tool(
31
32
  if model == "gpt-4o-mini": # backward compat: bare legacy default
32
33
  model = "openai:gpt-4o-mini"
33
34
  tools = [get_weather, render_graph]
34
- return make_tool_agent(model, tools)
35
+ return make_tool_agent(model, tools, checkpointer=checkpointer)
@@ -0,0 +1,74 @@
1
+ # Implementing an agent
2
+
3
+ Any compiled LangGraph graph over `{"messages": [...]}` is servable. The only
4
+ contract (see `ChatGraph` in `server.py`) is:
5
+
6
+ ```python
7
+ graph.astream(input, config=..., stream_mode=[...], subgraphs=True)
8
+ # yields (namespace, event_type, chunk) triples
9
+ ```
10
+
11
+ ## Minimal custom agent (5 minutes)
12
+
13
+ ```python
14
+ # my_agent.py
15
+ from langchain_core.tools import tool
16
+ from agent_chat_minimal.demo_agent.agent_factory import make_tool_agent
17
+
18
+ @tool
19
+ def shout(text: str) -> str:
20
+ """Uppercase the input."""
21
+ return text.upper()
22
+
23
+ def make_shout_agent(model="openai:gpt-4o-mini", checkpointer=None):
24
+ return make_tool_agent(model, [shout], "Reply ONLY with the tool result.")
25
+ ```
26
+
27
+ Serve it — no server fork needed:
28
+
29
+ ```python
30
+ # serve.py
31
+ from agent_chat_minimal import create_app
32
+ from my_agent import make_shout_agent
33
+
34
+ app = create_app(graph_factory=make_shout_agent)
35
+ # python -m uvicorn serve:app --port 8011
36
+ ```
37
+
38
+ Prefer an instance? `create_app(graph=make_shout_agent(...))` works too;
39
+ the factory form defers credential errors to startup instead of import.
40
+
41
+ ## Multi-agent serving
42
+
43
+ ```python
44
+ app = create_app(agents={"shout": make_shout_agent})
45
+ # POST /assistant/shout, GET /agents -> ["calculator","shout","weather"]
46
+ ```
47
+
48
+ `POST /assistant` aliases the `default_agent` (`"weather"` unless overridden).
49
+
50
+ ## Reference: calculator agent
51
+
52
+ `demo_agent/calculator.py` (`add`/`subtract`/`multiply`/`divide` +
53
+ `make_calculator_agent`) is the canonical example: tools, system prompt,
54
+ provider-agnostic model arg, optional `checkpointer` passthrough.
55
+
56
+ ## Sharing via pip (no fork)
57
+
58
+ Register the `agent_chat.agents` entry-points group:
59
+
60
+ ```toml
61
+ [project.entry-points."agent_chat.agents"]
62
+ shout = "my_package.my_agent:make_shout_agent"
63
+ ```
64
+
65
+ `discover_agents()` picks it up automatically alongside the built-ins.
66
+
67
+ ## Checklist
68
+
69
+ - [ ] Factory signature `(model=..., checkpointer=None)` so the server can
70
+ inject the shared checkpointer.
71
+ - [ ] Tools have clear docstrings — the model only sees those.
72
+ - [ ] Offline test with a fake model (see `tests/test_provider_agnostic.py`).
73
+ - [ ] `minimal-chat-serve --agent shout --check` builds without network creds
74
+ only if the model is fake/local; otherwise expect a credential error.
@@ -0,0 +1,60 @@
1
+ # Configuration
2
+
3
+ Single source of truth: `Settings` in `config.py` (stdlib only, no extra
4
+ dependency). CLI flags override env vars.
5
+
6
+ ## Environment
7
+
8
+ ```text
9
+ HOST=0.0.0.0 # uvicorn bind host
10
+ PORT=8011 # uvicorn bind port
11
+ MODEL=openai:gpt-4o-mini # provider:model spec (see providers.md)
12
+ DEFAULT_AGENT=weather # registry id aliased by POST /assistant
13
+ MINIMAL_WEB_DIR= # override bundled web/ (empty = bundled)
14
+ OPENAI_API_KEY= # credential for the default openai model
15
+ ANTHROPIC_API_KEY= # credential when MODEL uses anthropic:
16
+ ```
17
+
18
+ ```python
19
+ from agent_chat_minimal import Settings
20
+ Settings.from_env() # Settings(host='0.0.0.0', port=8011, ...)
21
+ ```
22
+
23
+ ## CLI
24
+
25
+ ```bash
26
+ minimal-chat-serve --host 127.0.0.1 --port 8011 \
27
+ --model ollama:llama3.1 --agent calculator
28
+ minimal-chat-serve --agent weather --check # build graph, exit, no server
29
+ ```
30
+
31
+ `--check` is the fast CI smoke test: non-zero exit with the real factory
32
+ error when credentials are missing.
33
+
34
+ ## Hooks (`create_app(...)`)
35
+
36
+ | Parameter | Purpose |
37
+ | ---------------- | -------------------------------------------------- |
38
+ | `graph=` | Serve one prebuilt graph (`/agents == ["default"]`)|
39
+ | `graph_factory=` | Deferred single-graph build (errors at startup) |
40
+ | `agents=` | Name → factory map (multi-agent mode) |
41
+ | `default_agent=` | Id aliased by `POST /assistant` |
42
+ | `web_dir=` | Override the bundled UI directory |
43
+ | `prepare_state=` | `(state, request) -> message dicts` reducer |
44
+ | `checkpointer=` | Shared checkpointer (`"memory"` default, see below)|
45
+ | `thread_manager=`/`message_store=` | Swap thread storage (tests) |
46
+
47
+ ## Checkpointer
48
+
49
+ `"memory"` (default) builds one shared `MemorySaver` and passes it to every
50
+ factory whose signature accepts `checkpointer`. Per-`thread_id` graph state
51
+ then persists across requests (see [threads.md](threads.md)). Pass an explicit
52
+ saver instance for custom backends, or `None` to disable injection.
53
+
54
+ ## `/assistant` 503 semantics
55
+
56
+ - Default registry + no `OPENAI_API_KEY` → legacy
57
+ `{"error": "OPENAI_API_KEY not configured", ...}` (backward compatible).
58
+ - Custom graph/factory failure →
59
+ `{"error": "agent_not_ready", "message": ..., "hint": ...}` with the real
60
+ factory exception in `hint`.
@@ -0,0 +1,29 @@
1
+ # agent-chat-minimal — documentation index
2
+
3
+ Portable FastAPI + LangGraph chat server with a bundled Assistant UI.
4
+ Install from PyPI (Python 3.11+, no Node needed) and serve one command:
5
+
6
+ ```bash
7
+ pip install agent-chat-fastapi-langgraph-assistant-ui
8
+ minimal-chat-serve --port 8011
9
+ ```
10
+
11
+ Guides (shipped inside the wheel under `agent_chat_minimal/docs/`):
12
+
13
+ - [quickstart.md](quickstart.md) — install, serve, first chat (2 minutes).
14
+ - [agents.md](agents.md) — implement and serve your own agent.
15
+ - [providers.md](providers.md) — model specs for OpenAI, Anthropic, Ollama, ….
16
+ - [configuration.md](configuration.md) — env vars, CLI flags, hooks.
17
+ - [threads.md](threads.md) — multi-thread chats, frontend-full compatibility.
18
+ - [index.md](index.md) — this file: architecture overview.
19
+
20
+ Discoverability: every guide is readable at runtime without unpacking the wheel:
21
+
22
+ ```python
23
+ from agent_chat_minimal import docs
24
+ docs.list() # ['agents', 'configuration', ...]
25
+ print(docs.get("agents"))
26
+ docs.show("threads") # prints to stdout
27
+ ```
28
+
29
+ FastAPI also serves interactive Swagger UI at `GET /docs` when the server runs.
@@ -0,0 +1,42 @@
1
+ # Model providers
2
+
3
+ Factories take either a `provider:name` spec (resolved via LangChain's
4
+ `init_chat_model`) or an already-built chat model instance.
5
+
6
+ ## Specs
7
+
8
+ | Spec prefix | Example | Credential env | Install extra |
9
+ | ----------- | --------------------------- | ------------------- | -------------------- |
10
+ | `openai:` | `openai:gpt-4o-mini` | `OPENAI_API_KEY` | `langchain-openai` ✓ |
11
+ | `anthropic:`| `anthropic:claude-sonnet-4-5` | `ANTHROPIC_API_KEY` | `langchain-anthropic`|
12
+ | `ollama:` | `ollama:llama3.1` | none (local daemon) | `langchain-ollama` |
13
+ | `google_genai:` | `google_genai:gemini-2.5-flash` | `GOOGLE_API_KEY`| `langchain-google-genai` |
14
+
15
+ ✓ = bundled with this wheel. Others need their LangChain partner package;
16
+ the import happens lazily, only when that provider is selected.
17
+
18
+ Bare `gpt-4o-mini` still works (provider inferred as OpenAI) for backward
19
+ compatibility; prefer the explicit `openai:` prefix.
20
+
21
+ ## Selecting the model
22
+
23
+ ```bash
24
+ MODEL=anthropic:claude-sonnet-4-5 minimal-chat-serve
25
+ minimal-chat-serve --model ollama:llama3.1 --agent calculator
26
+ ```
27
+
28
+ ## Instances and offline tests
29
+
30
+ Pass any `BaseChatModel` (streaming or fake) straight in:
31
+
32
+ ```python
33
+ from langchain_core.language_models.fake_chat_models import GenericFakeChatModel
34
+
35
+ class Bindable(GenericFakeChatModel):
36
+ def bind_tools(self, *a, **k):
37
+ return self # base class raises NotImplementedError
38
+
39
+ graph = make_calculator_agent(Bindable(messages=iter([...])))
40
+ ```
41
+
42
+ This is how the bundled tests run the full agent loop with no network.
@@ -0,0 +1,44 @@
1
+ # Quickstart
2
+
3
+ ## Install
4
+
5
+ ```bash
6
+ pip install agent-chat-fastapi-langgraph-assistant-ui
7
+ ```
8
+
9
+ Or from this repo (builds the UI + wheel; Node/pnpm needed only here):
10
+
11
+ ```bash
12
+ packages/agent-chat-minimal/scripts/build_wheel.sh
13
+ python -m pip install packages/agent-chat-minimal/dist/*.whl
14
+ ```
15
+
16
+ ## Serve
17
+
18
+ ```bash
19
+ export OPENAI_API_KEY=sk-...
20
+ minimal-chat-serve --port 8011
21
+ # open http://localhost:8011/
22
+ ```
23
+
24
+ Without `OPENAI_API_KEY`, the UI and `GET /health` still work; `POST /assistant`
25
+ returns 503 with setup instructions.
26
+
27
+ ## First chat
28
+
29
+ ```bash
30
+ curl -s localhost:8011/health
31
+ # {"status":"ok"}
32
+
33
+ curl -s localhost:8011/agents
34
+ # {"agents":["calculator","weather"],"default":"weather"}
35
+ ```
36
+
37
+ In the UI, try *"What is 12 × 8?"* (calculator) or *"Weather in London?"*.
38
+
39
+ ## Next steps
40
+
41
+ - Custom agent? → [agents.md](agents.md).
42
+ - Another model provider? → [providers.md](providers.md).
43
+ - Env vars and flags? → [configuration.md](configuration.md).
44
+ - Threaded chats / frontend-full? → [threads.md](threads.md).
@@ -0,0 +1,60 @@
1
+ # Threads (multi-conversation chats)
2
+
3
+ The portable server speaks the same thread protocol as the full backend, so
4
+ `frontend-full` (thread list, history, multiple chats) works against either
5
+ server. Single-prompt clients can ignore this page entirely.
6
+
7
+ ## Concepts
8
+
9
+ - **Thread**: a conversation id. Metadata (title, owner, archived) is kept by
10
+ `ThreadManager`; content lives in two places:
11
+ - assistant-ui message objects, stored verbatim per thread (tool UI parts
12
+ rehydrate on reload);
13
+ - LangGraph checkpointer state keyed by `thread_id` (graph-side memory).
14
+ - **Scoped request**: `POST /assistant` accepts `thread_id`/`user_id`
15
+ top-level fields (plus the classic `commands`/`state`). Missing ids are
16
+ auto-generated and their metadata auto-created — the same behavior as the
17
+ full backend.
18
+
19
+ ## Endpoints
20
+
21
+ ```text
22
+ GET /threads[?user_id=&include_archived=]
23
+ POST /threads {localId, user_id?, title?}
24
+ GET /threads/{id} PATCH /threads/{id} {title}
25
+ POST /threads/{id}/archive|unarchive
26
+ DELETE /threads/{id} (also drops stored messages)
27
+ GET /threads/{id}/messages (persisted UI messages, else checkpointer fallback)
28
+ POST /threads/{id}/messages {message} (history.append hook)
29
+ POST /assistant POST /assistant/{agent_id} (scoped shape supported)
30
+ ```
31
+
32
+ ## Example flow
33
+
34
+ ```bash
35
+ curl -X POST localhost:8011/threads -H 'Content-Type: application/json' \
36
+ -d '{"localId":"trip","title":"Trip planning"}'
37
+
38
+ curl -X POST localhost:8011/assistant -H 'Content-Type: application/json' \
39
+ -d '{"thread_id":"trip","state":{"thread_id":"trip"},"commands":[]}'
40
+
41
+ curl localhost:8011/threads/trip/messages
42
+ ```
43
+
44
+ ## Frontend-full compatibility
45
+
46
+ Point the full frontend at the portable server (`NEXT_PUBLIC_API_URL` without
47
+ the trailing `/assistant`); thread list, switching, rename, archive, and
48
+ history rehydration all use the endpoints above. Responses stream over the
49
+ Assistant Stream protocol with `messages`/`updates`/`custom` events, including
50
+ `tool_updates` progress entries like the full backend.
51
+
52
+ ## Persistence notes
53
+
54
+ - Default storage is in-memory (`MemorySaver` + dicts): restarts lose it —
55
+ identical to the full backend's default. Restart-safe backends plug in via
56
+ `create_app(checkpointer=<saver>)`.
57
+ - History larger than the 500-message store cap (or 200 tool updates) is
58
+ trimmed oldest-first.
59
+ - AI messages with `tool_calls` but no matching `ToolMessage` are dropped
60
+ before invoke (invalid-history guard, same as full backend).
@@ -0,0 +1,35 @@
1
+ """Runtime access to the bundled guides (see ``docs/*.md``).
2
+
3
+ ```python
4
+ from agent_chat_minimal import docs
5
+ docs.list() # ['agents', 'configuration', 'index', ...]
6
+ print(docs.get("threads"))
7
+ docs.show("quickstart")
8
+ ```
9
+ """
10
+
11
+ GUIDES = ("index", "quickstart", "agents", "providers", "configuration", "threads")
12
+
13
+
14
+ def _read(name: str) -> str:
15
+ from importlib.resources import files
16
+
17
+ return (files(__package__) / "docs" / f"{name}.md").read_text(encoding="utf-8")
18
+
19
+
20
+ def list() -> list[str]: # noqa: A001 - intentional `docs.list()` API
21
+ """Return available guide names."""
22
+ return [g for g in GUIDES]
23
+
24
+
25
+ def get(name: str) -> str:
26
+ """Return a guide's markdown, e.g. ``docs.get("agents")``."""
27
+ key = name.removesuffix(".md").lower()
28
+ if key not in GUIDES:
29
+ raise KeyError(f"unknown guide {name!r}; available: {', '.join(GUIDES)}")
30
+ return _read(key)
31
+
32
+
33
+ def show(name: str) -> None:
34
+ """Print a guide to stdout."""
35
+ print(get(name))
@@ -18,16 +18,20 @@ logger = logging.getLogger(__name__)
18
18
  ENTRY_POINTS_GROUP = "agent_chat.agents"
19
19
 
20
20
 
21
- def _weather_factory() -> Any:
21
+ def _weather_factory(checkpointer: Any = None) -> Any:
22
22
  from .demo_agent.get_graph import make_agent_with_weather_tool
23
23
 
24
- return make_agent_with_weather_tool(os.getenv("MODEL", "openai:gpt-4o-mini"))
24
+ return make_agent_with_weather_tool(
25
+ os.getenv("MODEL", "openai:gpt-4o-mini"), checkpointer=checkpointer
26
+ )
25
27
 
26
28
 
27
- def _calculator_factory() -> Any:
29
+ def _calculator_factory(checkpointer: Any = None) -> Any:
28
30
  from .demo_agent.calculator import make_calculator_agent
29
31
 
30
- return make_calculator_agent(os.getenv("MODEL", "openai:gpt-4o-mini"))
32
+ return make_calculator_agent(
33
+ os.getenv("MODEL", "openai:gpt-4o-mini"), checkpointer=checkpointer
34
+ )
31
35
 
32
36
 
33
37
  AGENT_REGISTRY: dict[str, Callable[[], Any]] = {