@damiangilgonzalez/copypasta 0.0.0-stage → 0.1.0

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 (255) hide show
  1. package/README.md +227 -2
  2. package/catalog.yaml +140 -0
  3. package/cli/copypasta.js +4 -0
  4. package/cli/lib/catalog.js +131 -0
  5. package/cli/lib/commands.js +162 -0
  6. package/cli/lib/index.js +4 -0
  7. package/cli/lib/main.js +130 -0
  8. package/package.json +38 -4
  9. package/recipes/agents/agent-memory/RECIPE.md +75 -0
  10. package/recipes/agents/agent-memory/files/agentic/memory/__init__.py +25 -0
  11. package/recipes/agents/agent-memory/files/agentic/memory/base.py +101 -0
  12. package/recipes/agents/agent-memory/files/agentic/memory/factory.py +33 -0
  13. package/recipes/agents/agent-memory/files/agentic/memory/in_memory.py +59 -0
  14. package/recipes/agents/agent-memory/files/agentic/memory/models.py +66 -0
  15. package/recipes/agents/agent-memory/files/agentic/memory/settings.py +24 -0
  16. package/recipes/agents/agent-memory/files/agentic/memory/sql.py +177 -0
  17. package/recipes/agents/agent-memory/files/pytest.ini +5 -0
  18. package/recipes/agents/agent-memory/files/tests/__init__.py +0 -0
  19. package/recipes/agents/agent-memory/files/tests/memory_conformance.py +158 -0
  20. package/recipes/agents/agent-memory/files/tests/test_memory.py +74 -0
  21. package/recipes/agents/langchain-agent/RECIPE.md +101 -0
  22. package/recipes/agents/langchain-agent/files/agentic/__init__.py +10 -0
  23. package/recipes/agents/langchain-agent/files/agentic/agents/__init__.py +13 -0
  24. package/recipes/agents/langchain-agent/files/agentic/agents/agents.py +43 -0
  25. package/recipes/agents/langchain-agent/files/agentic/agents/base_agent.py +126 -0
  26. package/recipes/agents/langchain-agent/files/agentic/agents/models.py +46 -0
  27. package/recipes/agents/langchain-agent/files/agentic/context.py +21 -0
  28. package/recipes/agents/langchain-agent/files/agentic/llm/__init__.py +5 -0
  29. package/recipes/agents/langchain-agent/files/agentic/llm/models.py +45 -0
  30. package/recipes/agents/langchain-agent/files/agentic/llm/provider.py +78 -0
  31. package/recipes/agents/langchain-agent/files/agentic/llm/settings.py +62 -0
  32. package/recipes/agents/langchain-agent/files/agentic/middleware/__init__.py +3 -0
  33. package/recipes/agents/langchain-agent/files/agentic/middleware/language.py +28 -0
  34. package/recipes/agents/langchain-agent/files/agentic/prompts/__init__.py +3 -0
  35. package/recipes/agents/langchain-agent/files/agentic/prompts/assistant.en.yaml +15 -0
  36. package/recipes/agents/langchain-agent/files/agentic/prompts/assistant.es.yaml +15 -0
  37. package/recipes/agents/langchain-agent/files/agentic/prompts/loader.py +69 -0
  38. package/recipes/agents/langchain-agent/files/agentic/tools/__init__.py +25 -0
  39. package/recipes/agents/langchain-agent/files/agentic/tools/base_tool.py +62 -0
  40. package/recipes/agents/langchain-agent/files/agentic/tools/search_documents.py +42 -0
  41. package/recipes/agents/langchain-agent/files/pytest.ini +5 -0
  42. package/recipes/agents/langchain-agent/files/tests/__init__.py +0 -0
  43. package/recipes/agents/langchain-agent/files/tests/fakes.py +30 -0
  44. package/recipes/agents/langchain-agent/files/tests/test_agents.py +151 -0
  45. package/recipes/agents/langgraph-graph/RECIPE.md +63 -0
  46. package/recipes/agents/langgraph-graph/files/agentic/conversation.py +73 -0
  47. package/recipes/agents/langgraph-graph/files/agentic/graph/__init__.py +17 -0
  48. package/recipes/agents/langgraph-graph/files/agentic/graph/builder.py +37 -0
  49. package/recipes/agents/langgraph-graph/files/agentic/graph/edges.py +8 -0
  50. package/recipes/agents/langgraph-graph/files/agentic/graph/event_processor.py +48 -0
  51. package/recipes/agents/langgraph-graph/files/agentic/graph/events.py +30 -0
  52. package/recipes/agents/langgraph-graph/files/agentic/graph/graph.py +60 -0
  53. package/recipes/agents/langgraph-graph/files/agentic/graph/nodes.py +63 -0
  54. package/recipes/agents/langgraph-graph/files/agentic/graph/state.py +31 -0
  55. package/recipes/agents/langgraph-graph/files/agentic/registry.py +85 -0
  56. package/recipes/agents/langgraph-graph/files/tests/test_graph.py +145 -0
  57. package/recipes/backend/.gitkeep +0 -0
  58. package/recipes/backend/agent-chat-api/RECIPE.md +69 -0
  59. package/recipes/backend/agent-chat-api/files/api/agent/guards.py +35 -0
  60. package/recipes/backend/agent-chat-api/files/api/agent/router.py +86 -0
  61. package/recipes/backend/agent-chat-api/files/api/agent/sanitize.py +22 -0
  62. package/recipes/backend/agent-chat-api/files/api/agent/schemas.py +26 -0
  63. package/recipes/backend/agent-chat-api/files/api/agent/settings.py +14 -0
  64. package/recipes/backend/agent-chat-api/files/api/agent/tracing.py +38 -0
  65. package/recipes/backend/agent-chat-api/files/api/app.py +67 -0
  66. package/recipes/backend/agent-chat-api/files/api/auth.py +73 -0
  67. package/recipes/backend/agent-chat-api/files/pytest.ini +5 -0
  68. package/recipes/backend/agent-chat-api/files/tests/test_agent_api.py +237 -0
  69. package/recipes/backend/agent-feedback/RECIPE.md +63 -0
  70. package/recipes/backend/agent-feedback/files/api/feedback/__init__.py +0 -0
  71. package/recipes/backend/agent-feedback/files/api/feedback/router.py +72 -0
  72. package/recipes/backend/agent-feedback/files/api/feedback/schemas.py +44 -0
  73. package/recipes/backend/agent-feedback/files/feedback/__init__.py +25 -0
  74. package/recipes/backend/agent-feedback/files/feedback/base.py +53 -0
  75. package/recipes/backend/agent-feedback/files/feedback/factory.py +30 -0
  76. package/recipes/backend/agent-feedback/files/feedback/in_memory.py +29 -0
  77. package/recipes/backend/agent-feedback/files/feedback/models.py +48 -0
  78. package/recipes/backend/agent-feedback/files/feedback/settings.py +17 -0
  79. package/recipes/backend/agent-feedback/files/feedback/sql.py +102 -0
  80. package/recipes/backend/agent-feedback/files/pytest.ini +5 -0
  81. package/recipes/backend/agent-feedback/files/tests/feedback_conformance.py +89 -0
  82. package/recipes/backend/agent-feedback/files/tests/test_feedback.py +63 -0
  83. package/recipes/backend/agent-feedback/files/tests/test_feedback_api.py +95 -0
  84. package/recipes/backend/auth-verifier/RECIPE.md +63 -0
  85. package/recipes/backend/auth-verifier/files/api/auth.py +73 -0
  86. package/recipes/backend/auth-verifier/files/auth/__init__.py +23 -0
  87. package/recipes/backend/auth-verifier/files/auth/factory.py +28 -0
  88. package/recipes/backend/auth-verifier/files/auth/jwt_verifier.py +101 -0
  89. package/recipes/backend/auth-verifier/files/auth/models.py +29 -0
  90. package/recipes/backend/auth-verifier/files/auth/settings.py +45 -0
  91. package/recipes/backend/auth-verifier/files/auth/supabase.py +80 -0
  92. package/recipes/backend/auth-verifier/files/pytest.ini +5 -0
  93. package/recipes/backend/auth-verifier/files/tests/__init__.py +0 -0
  94. package/recipes/backend/auth-verifier/files/tests/test_auth.py +229 -0
  95. package/recipes/backend/conversation-history/RECIPE.md +49 -0
  96. package/recipes/backend/conversation-history/files/api/conversations/__init__.py +0 -0
  97. package/recipes/backend/conversation-history/files/api/conversations/router.py +55 -0
  98. package/recipes/backend/conversation-history/files/api/conversations/schemas.py +57 -0
  99. package/recipes/backend/conversation-history/files/pytest.ini +5 -0
  100. package/recipes/backend/conversation-history/files/tests/test_conversations_api.py +127 -0
  101. package/recipes/backend/fastapi-base/RECIPE.md +57 -0
  102. package/recipes/backend/fastapi-base/files/api/app.py +37 -0
  103. package/recipes/backend/fastapi-base/files/api/base.py +54 -0
  104. package/recipes/backend/fastapi-base/files/api/errors.py +31 -0
  105. package/recipes/backend/fastapi-base/files/api/health.py +19 -0
  106. package/recipes/backend/fastapi-base/files/api/logging_setup.py +26 -0
  107. package/recipes/backend/fastapi-base/files/api/request_id.py +62 -0
  108. package/recipes/backend/fastapi-base/files/api/settings.py +32 -0
  109. package/recipes/backend/fastapi-base/files/pytest.ini +5 -0
  110. package/recipes/backend/fastapi-base/files/tests/__init__.py +0 -0
  111. package/recipes/backend/fastapi-base/files/tests/test_api_base.py +136 -0
  112. package/recipes/backend/observability/RECIPE.md +68 -0
  113. package/recipes/backend/observability/files/observability/__init__.py +34 -0
  114. package/recipes/backend/observability/files/observability/factory.py +73 -0
  115. package/recipes/backend/observability/files/observability/langfuse_tracer.py +29 -0
  116. package/recipes/backend/observability/files/observability/langsmith_tracer.py +23 -0
  117. package/recipes/backend/observability/files/observability/models.py +90 -0
  118. package/recipes/backend/observability/files/observability/opik_tracer.py +30 -0
  119. package/recipes/backend/observability/files/observability/settings.py +58 -0
  120. package/recipes/backend/observability/files/observability/tracer.py +142 -0
  121. package/recipes/backend/observability/files/observability/usage.py +61 -0
  122. package/recipes/backend/observability/files/pytest.ini +5 -0
  123. package/recipes/backend/observability/files/tests/__init__.py +0 -0
  124. package/recipes/backend/observability/files/tests/test_observability.py +219 -0
  125. package/recipes/backend/project-settings/RECIPE.md +40 -0
  126. package/recipes/backend/project-settings/files/.env.example +7 -0
  127. package/recipes/backend/project-settings/files/core/__init__.py +0 -0
  128. package/recipes/backend/project-settings/files/core/config.py +41 -0
  129. package/recipes/backend/project-settings/files/pytest.ini +3 -0
  130. package/recipes/backend/project-settings/files/tests/__init__.py +0 -0
  131. package/recipes/backend/project-settings/files/tests/test_settings.py +44 -0
  132. package/recipes/backend/rag-retriever/RECIPE.md +79 -0
  133. package/recipes/backend/rag-retriever/files/pytest.ini +5 -0
  134. package/recipes/backend/rag-retriever/files/rag/__init__.py +53 -0
  135. package/recipes/backend/rag-retriever/files/rag/base.py +106 -0
  136. package/recipes/backend/rag-retriever/files/rag/chunking.py +84 -0
  137. package/recipes/backend/rag-retriever/files/rag/document_search.py +60 -0
  138. package/recipes/backend/rag-retriever/files/rag/embeddings.py +91 -0
  139. package/recipes/backend/rag-retriever/files/rag/factory.py +82 -0
  140. package/recipes/backend/rag-retriever/files/rag/in_memory.py +52 -0
  141. package/recipes/backend/rag-retriever/files/rag/models.py +107 -0
  142. package/recipes/backend/rag-retriever/files/rag/pgvector.py +138 -0
  143. package/recipes/backend/rag-retriever/files/rag/qdrant.py +96 -0
  144. package/recipes/backend/rag-retriever/files/rag/settings.py +48 -0
  145. package/recipes/backend/rag-retriever/files/tests/__init__.py +0 -0
  146. package/recipes/backend/rag-retriever/files/tests/rag_conformance.py +95 -0
  147. package/recipes/backend/rag-retriever/files/tests/test_rag.py +270 -0
  148. package/recipes/backend/rate-limit-quota/RECIPE.md +77 -0
  149. package/recipes/backend/rate-limit-quota/files/api/agent/guards.py +62 -0
  150. package/recipes/backend/rate-limit-quota/files/api/limits/__init__.py +0 -0
  151. package/recipes/backend/rate-limit-quota/files/api/limits/router.py +38 -0
  152. package/recipes/backend/rate-limit-quota/files/limits/__init__.py +43 -0
  153. package/recipes/backend/rate-limit-quota/files/limits/base.py +161 -0
  154. package/recipes/backend/rate-limit-quota/files/limits/factory.py +69 -0
  155. package/recipes/backend/rate-limit-quota/files/limits/in_memory.py +36 -0
  156. package/recipes/backend/rate-limit-quota/files/limits/models.py +108 -0
  157. package/recipes/backend/rate-limit-quota/files/limits/settings.py +32 -0
  158. package/recipes/backend/rate-limit-quota/files/limits/sql.py +94 -0
  159. package/recipes/backend/rate-limit-quota/files/pytest.ini +5 -0
  160. package/recipes/backend/rate-limit-quota/files/tests/limits_conformance.py +146 -0
  161. package/recipes/backend/rate-limit-quota/files/tests/test_limits.py +167 -0
  162. package/recipes/backend/rate-limit-quota/files/tests/test_limits_api.py +100 -0
  163. package/recipes/backend/voice-providers/RECIPE.md +73 -0
  164. package/recipes/backend/voice-providers/files/api/__init__.py +0 -0
  165. package/recipes/backend/voice-providers/files/api/voice/__init__.py +0 -0
  166. package/recipes/backend/voice-providers/files/api/voice/router.py +113 -0
  167. package/recipes/backend/voice-providers/files/pytest.ini +5 -0
  168. package/recipes/backend/voice-providers/files/tests/__init__.py +0 -0
  169. package/recipes/backend/voice-providers/files/tests/fake_openai.py +44 -0
  170. package/recipes/backend/voice-providers/files/tests/test_voice.py +164 -0
  171. package/recipes/backend/voice-providers/files/tests/test_voice_api.py +106 -0
  172. package/recipes/backend/voice-providers/files/tests/voice_conformance.py +80 -0
  173. package/recipes/backend/voice-providers/files/voice/__init__.py +29 -0
  174. package/recipes/backend/voice-providers/files/voice/base.py +116 -0
  175. package/recipes/backend/voice-providers/files/voice/factory.py +48 -0
  176. package/recipes/backend/voice-providers/files/voice/fake.py +51 -0
  177. package/recipes/backend/voice-providers/files/voice/models.py +85 -0
  178. package/recipes/backend/voice-providers/files/voice/openai_provider.py +116 -0
  179. package/recipes/backend/voice-providers/files/voice/settings.py +48 -0
  180. package/recipes/frontend/.gitkeep +0 -0
  181. package/recipes/frontend/playwright-e2e/RECIPE.md +48 -0
  182. package/recipes/frontend/playwright-e2e/files/.github/workflows/frontend.yml +35 -0
  183. package/recipes/frontend/playwright-e2e/files/e2e/helpers.ts +25 -0
  184. package/recipes/frontend/playwright-e2e/files/e2e/home.spec.ts +10 -0
  185. package/recipes/frontend/playwright-e2e/files/e2e/login.spec.ts +26 -0
  186. package/recipes/frontend/playwright-e2e/files/e2e/navigation.spec.ts +27 -0
  187. package/recipes/frontend/playwright-e2e/files/playwright.config.ts +35 -0
  188. package/recipes/frontend/react-agent-chat/RECIPE.md +69 -0
  189. package/recipes/frontend/react-agent-chat/files/src/features/chat/chat-api.ts +27 -0
  190. package/recipes/frontend/react-agent-chat/files/src/features/chat/chat.css +18 -0
  191. package/recipes/frontend/react-agent-chat/files/src/features/chat/chat.test.tsx +139 -0
  192. package/recipes/frontend/react-agent-chat/files/src/features/chat/components/ChatView.tsx +22 -0
  193. package/recipes/frontend/react-agent-chat/files/src/features/chat/components/Composer.tsx +40 -0
  194. package/recipes/frontend/react-agent-chat/files/src/features/chat/components/Markdown.tsx +20 -0
  195. package/recipes/frontend/react-agent-chat/files/src/features/chat/components/MessageList.tsx +42 -0
  196. package/recipes/frontend/react-agent-chat/files/src/features/chat/events.ts +42 -0
  197. package/recipes/frontend/react-agent-chat/files/src/features/chat/fake-chat-api.ts +44 -0
  198. package/recipes/frontend/react-agent-chat/files/src/features/chat/index.ts +6 -0
  199. package/recipes/frontend/react-agent-chat/files/src/features/chat/sse-parser.test.ts +97 -0
  200. package/recipes/frontend/react-agent-chat/files/src/features/chat/sse-parser.ts +85 -0
  201. package/recipes/frontend/react-agent-chat/files/src/features/chat/use-chat.ts +136 -0
  202. package/recipes/frontend/react-app-router/RECIPE.md +58 -0
  203. package/recipes/frontend/react-app-router/files/src/App.test.tsx +54 -0
  204. package/recipes/frontend/react-app-router/files/src/App.tsx +14 -0
  205. package/recipes/frontend/react-app-router/files/src/router/ErrorScreen.tsx +21 -0
  206. package/recipes/frontend/react-app-router/files/src/router/Layout.tsx +28 -0
  207. package/recipes/frontend/react-app-router/files/src/router/NotFoundScreen.tsx +12 -0
  208. package/recipes/frontend/react-app-router/files/src/router/index.ts +1 -0
  209. package/recipes/frontend/react-app-router/files/src/router/router.css +29 -0
  210. package/recipes/frontend/react-app-router/files/src/router/router.test.tsx +65 -0
  211. package/recipes/frontend/react-app-router/files/src/router/routes.tsx +59 -0
  212. package/recipes/frontend/react-app-router/files/src/screens/SettingsScreen.tsx +10 -0
  213. package/recipes/frontend/react-supabase-auth/RECIPE.md +77 -0
  214. package/recipes/frontend/react-supabase-auth/files/src/auth/LoginScreen.tsx +64 -0
  215. package/recipes/frontend/react-supabase-auth/files/src/auth/SignOutButton.tsx +12 -0
  216. package/recipes/frontend/react-supabase-auth/files/src/auth/auth.css +33 -0
  217. package/recipes/frontend/react-supabase-auth/files/src/auth/auth.test.ts +149 -0
  218. package/recipes/frontend/react-supabase-auth/files/src/auth/auth.ts +59 -0
  219. package/recipes/frontend/react-supabase-auth/files/src/auth/fake-auth.ts +87 -0
  220. package/recipes/frontend/react-supabase-auth/files/src/auth/fake-gotrue.ts +85 -0
  221. package/recipes/frontend/react-supabase-auth/files/src/auth/index.ts +7 -0
  222. package/recipes/frontend/react-supabase-auth/files/src/auth/make-auth.ts +20 -0
  223. package/recipes/frontend/react-supabase-auth/files/src/auth/session-context.tsx +35 -0
  224. package/recipes/frontend/react-supabase-auth/files/src/auth/session-store.ts +63 -0
  225. package/recipes/frontend/react-supabase-auth/files/src/auth/session.test.tsx +56 -0
  226. package/recipes/frontend/react-supabase-auth/files/src/auth/settings.ts +30 -0
  227. package/recipes/frontend/react-supabase-auth/files/src/auth/supabase-auth.ts +85 -0
  228. package/recipes/frontend/vite-react-base/RECIPE.md +69 -0
  229. package/recipes/frontend/vite-react-base/files/.env +6 -0
  230. package/recipes/frontend/vite-react-base/files/.env.fake +2 -0
  231. package/recipes/frontend/vite-react-base/files/index.html +12 -0
  232. package/recipes/frontend/vite-react-base/files/package.json +30 -0
  233. package/recipes/frontend/vite-react-base/files/src/App.test.tsx +49 -0
  234. package/recipes/frontend/vite-react-base/files/src/App.tsx +13 -0
  235. package/recipes/frontend/vite-react-base/files/src/api/api.ts +37 -0
  236. package/recipes/frontend/vite-react-base/files/src/api/fake/fake-api.ts +29 -0
  237. package/recipes/frontend/vite-react-base/files/src/api/http-api.ts +16 -0
  238. package/recipes/frontend/vite-react-base/files/src/api/http-client.test.ts +84 -0
  239. package/recipes/frontend/vite-react-base/files/src/api/http-client.ts +94 -0
  240. package/recipes/frontend/vite-react-base/files/src/api/make-api.ts +30 -0
  241. package/recipes/frontend/vite-react-base/files/src/api/types.ts +7 -0
  242. package/recipes/frontend/vite-react-base/files/src/app-context.tsx +24 -0
  243. package/recipes/frontend/vite-react-base/files/src/auth/token-provider.ts +27 -0
  244. package/recipes/frontend/vite-react-base/files/src/config.ts +18 -0
  245. package/recipes/frontend/vite-react-base/files/src/hooks/use-load.ts +46 -0
  246. package/recipes/frontend/vite-react-base/files/src/main.tsx +27 -0
  247. package/recipes/frontend/vite-react-base/files/src/screens/HomeScreen.tsx +28 -0
  248. package/recipes/frontend/vite-react-base/files/src/styles/global.css +25 -0
  249. package/recipes/frontend/vite-react-base/files/src/styles/tokens.css +33 -0
  250. package/recipes/frontend/vite-react-base/files/src/styles/tokens.test.ts +45 -0
  251. package/recipes/frontend/vite-react-base/files/src/test-setup.ts +8 -0
  252. package/recipes/frontend/vite-react-base/files/src/vite-env.d.ts +11 -0
  253. package/recipes/frontend/vite-react-base/files/tsconfig.json +18 -0
  254. package/recipes/frontend/vite-react-base/files/vite.config.ts +19 -0
  255. package/unpacked-files.json +3 -0
@@ -0,0 +1,31 @@
1
+ """Graph state: the data contract between nodes.
2
+
3
+ Pydantic, with a description per field. Nodes return a dict with ONLY the keys they write.
4
+ Add a reducer (`Annotated[list[X], operator.add]`) only to keys that several nodes write in
5
+ the same step (parallel branches); everything else is last-write-wins.
6
+
7
+ Security data (tenant, user) does NOT live here: it is in `AgentContext` (`runtime.context`).
8
+ """
9
+
10
+ from langchain_core.messages import BaseMessage
11
+ from pydantic import BaseModel, ConfigDict, Field
12
+
13
+ from ..agents import Classification
14
+
15
+
16
+ class GraphState(BaseModel):
17
+ model_config = ConfigDict(arbitrary_types_allowed=True)
18
+
19
+ # Input
20
+ question: str = Field(description="The user's question for this turn.")
21
+ history: list[BaseMessage] = Field(default_factory=list, description="Previous turns read from memory.")
22
+
23
+ # Written by router_node
24
+ classification: Classification | None = Field(default=None, description="Router verdict; None if it failed.")
25
+ blocked: bool = Field(default=False, description="True if the question is out of scope.")
26
+
27
+ # Written by agent_node / reject_node
28
+ answer: str | None = Field(default=None, description="Final answer shown to the user.")
29
+ new_messages: list[BaseMessage] = Field(
30
+ default_factory=list, description="Messages produced this turn, to persist in memory."
31
+ )
@@ -0,0 +1,85 @@
1
+ """Wiring boundary: the only module that knows how to build agents with the app's services.
2
+
3
+ Graph nodes are `@staticmethod`s, so they get their agents from here instead of a constructor.
4
+ Models and API keys come from the project settings (`get_llm_settings()`); the app only injects
5
+ services with `registry.configure(...)` once at startup (FastAPI `lifespan`). Tests call
6
+ `registry.override(...)` with agents built on fake LLMs.
7
+
8
+ Agents are built lazily and cached (per language for the assistant), guarded by an asyncio.Lock
9
+ with a double check so concurrent first requests build each agent once.
10
+ """
11
+
12
+ import asyncio
13
+ from typing import Any
14
+
15
+ from .agents import AssistantAgent, ClassifierAgent
16
+ from .llm import LLMModel, LLMSettings, get_llm_settings
17
+ from .tools import ToolSet
18
+
19
+
20
+ class AgentRegistry:
21
+ def __init__(self) -> None:
22
+ self._settings: LLMSettings | None = None
23
+ self._services: dict[str, Any] | None = None
24
+ self._assistants: dict[str, AssistantAgent] = {}
25
+ self._classifier: ClassifierAgent | None = None
26
+ self._lock = asyncio.Lock()
27
+
28
+ def configure(
29
+ self,
30
+ *,
31
+ document_search: Any,
32
+ settings: LLMSettings | None = None,
33
+ ) -> None:
34
+ """`settings=None` -> `get_llm_settings()`. Pass one only in tests."""
35
+ self._settings = settings or get_llm_settings()
36
+ self._services = {"document_search": document_search}
37
+ self.reset()
38
+
39
+ def override(
40
+ self, *, assistant: AssistantAgent | None = None, classifier: ClassifierAgent | None = None, language: str = "es"
41
+ ) -> None:
42
+ """Tests: inject ready-made agents."""
43
+ if assistant is not None:
44
+ self._assistants[language] = assistant
45
+ if classifier is not None:
46
+ self._classifier = classifier
47
+
48
+ def reset(self) -> None:
49
+ self._assistants.clear()
50
+ self._classifier = None
51
+
52
+ def _require_configured(self) -> tuple[LLMSettings, dict[str, Any]]:
53
+ if self._settings is None or self._services is None:
54
+ raise RuntimeError("AgentRegistry not configured: call registry.configure(...) at startup")
55
+ return self._settings, self._services
56
+
57
+ async def get_assistant(self, language: str) -> AssistantAgent:
58
+ if (agent := self._assistants.get(language)) is not None:
59
+ return agent
60
+ async with self._lock:
61
+ if (agent := self._assistants.get(language)) is None:
62
+ settings, services = self._require_configured()
63
+ agent = AssistantAgent(
64
+ LLMModel.from_id(settings.assistant_model),
65
+ settings,
66
+ language=language,
67
+ tools=ToolSet.default(**services),
68
+ )
69
+ await agent.initialize()
70
+ self._assistants[language] = agent
71
+ return agent
72
+
73
+ async def get_classifier(self) -> ClassifierAgent:
74
+ if self._classifier is not None:
75
+ return self._classifier
76
+ async with self._lock:
77
+ if self._classifier is None:
78
+ settings, _ = self._require_configured()
79
+ agent = ClassifierAgent(LLMModel.from_id(settings.classifier_model), settings)
80
+ await agent.initialize()
81
+ self._classifier = agent
82
+ return self._classifier
83
+
84
+
85
+ registry = AgentRegistry()
@@ -0,0 +1,145 @@
1
+ """Graph tests. Need the langchain-agent and agent-memory recipes in the same `agentic/` (and tests/fakes.py)."""
2
+
3
+ from typing import Any
4
+
5
+ import pytest
6
+ from langchain_core.language_models.fake_chat_models import GenericFakeChatModel
7
+ from langchain_core.messages import AIMessage, ToolMessage
8
+
9
+ from agentic.agents import AssistantAgent, ClassifierAgent
10
+ from agentic.context import AgentContext
11
+ from agentic.conversation import answer_question, stream_answer
12
+ from agentic.graph import EventType, ainvoke_graph
13
+ from agentic.memory import InMemoryMemory, MemoryKey
14
+ from agentic.registry import registry
15
+ from agentic.tools import ToolSet
16
+
17
+ from .fakes import FakeDocumentSearch, ScriptedChatModel, tool_call
18
+
19
+ CONTEXT = AgentContext(tenant_id="tenant-1", user_id="user-1", language="es")
20
+ KEY = MemoryKey(tenant_id="tenant-1", user_id="user-1", conversation_id="conv-1")
21
+
22
+
23
+ def classifier_answering(category: str) -> ClassifierAgent:
24
+ args = {"category": category, "needs_search": True, "confidence": 0.9}
25
+ return ClassifierAgent(llm=ScriptedChatModel(responses=[tool_call("Classification", args, "c_router")]))
26
+
27
+
28
+ class StreamingChatModel(GenericFakeChatModel):
29
+ def bind_tools(self, tools: Any, **kwargs: Any) -> "StreamingChatModel":
30
+ return self
31
+
32
+
33
+ @pytest.fixture(autouse=True)
34
+ def clean_registry():
35
+ registry.reset()
36
+ yield
37
+ registry.reset()
38
+
39
+
40
+ async def test_allowed_question_goes_to_agent_with_tools():
41
+ service = FakeDocumentSearch(hits=[{"title": "Factura", "snippet": "IVA 21%"}])
42
+ registry.override(
43
+ classifier=classifier_answering("billing"),
44
+ assistant=AssistantAgent(
45
+ llm=ScriptedChatModel(responses=[tool_call("search_documents", {"query": "iva"}), AIMessage("El IVA es 21%")]),
46
+ tools=ToolSet.default(document_search=service),
47
+ ),
48
+ )
49
+
50
+ state = await ainvoke_graph("¿Qué IVA lleva?", context=CONTEXT)
51
+
52
+ assert state.blocked is False
53
+ assert state.classification.category == "billing"
54
+ assert state.answer == "El IVA es 21%"
55
+ assert service.calls[0][0] == "tenant-1"
56
+ assert any(isinstance(m, ToolMessage) for m in state.new_messages)
57
+
58
+
59
+ async def test_out_of_scope_question_is_rejected_without_calling_agent():
60
+ registry.override(classifier=classifier_answering("other")) # no assistant: calling it would fail
61
+
62
+ state = await ainvoke_graph("¿Quién ganó la liga?", context=CONTEXT)
63
+
64
+ assert state.blocked is True
65
+ assert state.answer.startswith("Solo puedo ayudarte")
66
+
67
+
68
+ async def test_router_failure_fails_open():
69
+ broken = ClassifierAgent(llm=ScriptedChatModel(responses=[AIMessage("x")]))
70
+
71
+ async def boom(*args, **kwargs):
72
+ raise RuntimeError("classifier down")
73
+
74
+ broken.process = boom
75
+ registry.override(
76
+ classifier=broken,
77
+ assistant=AssistantAgent(llm=ScriptedChatModel(responses=[AIMessage("respuesta")]), tools=[]),
78
+ )
79
+
80
+ state = await ainvoke_graph("hola", context=CONTEXT)
81
+
82
+ assert state.classification is None
83
+ assert state.answer == "respuesta"
84
+
85
+
86
+ async def test_conversation_persists_and_reuses_history():
87
+ memory = InMemoryMemory()
88
+ registry.override(
89
+ classifier=ClassifierAgent(
90
+ llm=ScriptedChatModel(
91
+ responses=[
92
+ tool_call("Classification", {"category": "technical", "needs_search": False, "confidence": 1}, "r1"),
93
+ tool_call("Classification", {"category": "technical", "needs_search": False, "confidence": 1}, "r2"),
94
+ ]
95
+ )
96
+ ),
97
+ assistant=AssistantAgent(llm=ScriptedChatModel(responses=[AIMessage("uno"), AIMessage("dos")]), tools=[]),
98
+ )
99
+
100
+ assert (await answer_question("primera", key=KEY, context=CONTEXT, memory=memory)).answer == "uno"
101
+ second = await answer_question("segunda", key=KEY, context=CONTEXT, memory=memory)
102
+ assert second.answer == "dos" and second.conversation_id == "conv-1"
103
+
104
+ history = await memory.get_messages(KEY)
105
+ assert [m.content for m in history] == ["primera", "uno", "segunda", "dos"]
106
+ assert await memory.get_messages(KEY, turns=1) == history[2:]
107
+ other_tenant = MemoryKey(tenant_id="tenant-2", user_id="user-1", conversation_id="conv-1")
108
+ assert await memory.get_messages(other_tenant) == []
109
+
110
+
111
+ async def test_stream_emits_routing_tokens_and_done():
112
+ memory = InMemoryMemory()
113
+ registry.override(
114
+ classifier=classifier_answering("technical"),
115
+ assistant=AssistantAgent(llm=StreamingChatModel(messages=iter([AIMessage("hola que tal")])), tools=[]),
116
+ )
117
+
118
+ events = [e async for e in stream_answer("hola", key=KEY, context=CONTEXT, memory=memory)]
119
+ types = [e.type for e in events]
120
+
121
+ assert types[0] is EventType.ROUTING
122
+ tokens = "".join(e.data["text"] for e in events if e.type is EventType.TOKEN)
123
+ assert tokens == "hola que tal"
124
+ assert types[-1] is EventType.DONE and events[-1].data["answer"] == "hola que tal"
125
+ assert events[-1].data["conversation_id"] == "conv-1"
126
+ assert len(await memory.get_messages(KEY)) == 2
127
+
128
+
129
+ async def test_stream_error_yields_error_event_without_details():
130
+ async def boom(*args, **kwargs):
131
+ raise RuntimeError("secret detail")
132
+
133
+ assistant = AssistantAgent(llm=ScriptedChatModel(responses=[AIMessage("x")]), tools=[])
134
+ assistant.process = boom
135
+ registry.override(classifier=classifier_answering("technical"), assistant=assistant)
136
+
137
+ events = [e async for e in stream_answer("x", key=KEY, context=CONTEXT, memory=InMemoryMemory())]
138
+
139
+ assert events[-1].type is EventType.ERROR
140
+ assert "secret" not in str(events[-1].data)
141
+
142
+
143
+ def test_registry_requires_configuration():
144
+ with pytest.raises(RuntimeError):
145
+ registry._require_configured()
File without changes
@@ -0,0 +1,69 @@
1
+ # agent-chat-api
2
+
3
+ ## Cuándo usarla
4
+
5
+ Para **exponer el agente por HTTP**: el endpoint de chat que consume la interfaz (`react-agent-chat`) o cualquier cliente. Dos rutas sobre el mismo turno: `POST /agent/chat` devuelve JSON y `POST /agent/stream` devuelve SSE.
6
+
7
+ **Requiere `fastapi-base`** (`create_app` parte de su `build_app`: request id, 500 sin internals, CORS, `/health`) **y `langgraph-graph`** (y con ella `langchain-agent` y `agent-memory`): el router llama a `answer_question` y `stream_answer`. Usa `project-settings` para el bloque `AgentApiSettings`. La auth y las cuotas tienen aquí su costura: `rate-limit-quota` la rellena (sustituye `guards.py`) y `auth-verifier` trae los verificadores reales (Supabase, JWT) con su factory.
8
+
9
+ ## Qué incluye
10
+
11
+ ```
12
+ api/
13
+ app.py create_app(settings, token_verifier, memory, document_search, tracer?, cors_origins): build_app + lifespan + router (sustituye al de fastapi-base)
14
+ auth.py CurrentUser · TokenVerifier (ABC) · StaticTokenVerifier (tests) · get_current_user (401/503); el mismo archivo que auth-verifier
15
+ agent/
16
+ router.py POST /agent/chat (JSON) · POST /agent/stream (SSE) · Turn (clave + contexto)
17
+ schemas.py ChatRequest{question, conversation_id?, language?} · ChatResponse{answer, conversation_id, message_id}
18
+ guards.py require_agent_enabled (404) · ensure_turn_allowed (403/429: punto de extensión)
19
+ sanitize.py sanitize_question: trim, longitud, caracteres de control, etiquetas HTML → 400
20
+ tracing.py traced_turn(tracer, key): begin_turn → config del run → finish (tracer opcional en app.state, receta observability)
21
+ settings.py AgentApiSettings: AGENT_ENDPOINT_ENABLED, CHAT_MAX_QUESTION_LENGTH
22
+ tests/test_agent_api.py 11 tests: 401, 404 con el flag, 400, ids, aislamiento por tenant, guard 429, SSE, error sin detalle, idioma, health y request id, turnos dentro del tracer
23
+ pytest.ini
24
+ ```
25
+
26
+ ## Decisiones
27
+
28
+ - **El mismo turno, dos respuestas.** Las dos rutas construyen el mismo `Turn` (pregunta limpia, `MemoryKey`, `AgentContext`) y solo cambia cómo se entrega.
29
+ - **Los tres ids.** El cliente solo elige `conversation_id` (y si no lo manda, lo genera el servidor con `uuid4`). `tenant_id` y `user_id` salen del token. Pedir el `conversation_id` de otro no abre su hilo.
30
+ - **Guards en orden y antes de abrir el stream:** flag apagado → 404 (que no se note que hay algo detrás), sin token → 401, `ensure_turn_allowed` → 403 o 429, pregunta vacía → 400. Una vez enviado el primer byte del SSE ya no se puede cambiar el status.
31
+ - **`ensure_turn_allowed` es el punto de extensión** para rol, cuota y rate limit. Por defecto deja pasar. Se sustituye con `app.dependency_overrides` o editándolo. Nada que bloquee dentro de él sin `run_in_threadpool`.
32
+ - **La auth es una clase base.** `TokenVerifier.verify(token) -> CurrentUser` vive en `app.state`, así que el proveedor se decide al construir la app y los tests usan `StaticTokenVerifier`. `auth-verifier` trae Supabase y JWT propio con `AuthFactory`; `AuthUnavailable` (proveedor caído) es un 503, no un 401.
33
+ - **`done` lleva `conversation_id` y `message_id`.** `message_id` es la respuesta guardada en `agent-memory`: lo que el cliente manda al votar (`agent-feedback`). `ChatResponse` tiene los mismos campos.
34
+ - **Persistir antes de responder.** `answer_question` y `stream_answer` escriben en memoria antes de devolver o de emitir `done`. En background abriría una carrera con varios workers, un problema visto en producción.
35
+ - **Errores en el stream sin detalle.** El grafo ya convierte sus fallos en `error{error_id}`; el router hace lo mismo con lo que falle fuera del grafo (memoria, red). El detalle solo va al log, con el `error_id` y el `thread_id`.
36
+ - **`create_app` con todo inyectado**, encima de `build_app` (`fastapi-base`). No lee el entorno: `main.py` construye las piezas desde el `Settings` del proyecto y las pasa, incluidos `cors_origins`. `/docs` oculto salvo `docs=True`. Los 429 con `detail={"code": ...}` siguen la convención de errores de `fastapi-base`.
37
+ - **Trazas opcionales y por fuera del core.** Si `create_app` recibe un `tracer` (receta `observability`), cada turno corre dentro de `traced_turn`: `begin_turn(thread_id, tenant_id, user_id, request_id)` da el `config` que `answer_question`/`stream_answer` pasan al grafo y `finish()` resume tokens, coste y duración. Sin tracer, el `config` es el de siempre. El tracer es duck-typed: esta receta no importa `observability`.
38
+ - **Sin imágenes ni adjuntos.** Algunos proyectos mandan imágenes en base64 dentro del body; es una extensión de `ChatRequest` y de `AgentContext`, no de esta receta.
39
+
40
+ ## Cómo adaptarla
41
+
42
+ 1. Copia `files/` al backend, encima de las recetas requeridas (`api/app.py` sustituye al de `fastapi-base`). Sustituye `{{app_name}}` en `api/app.py`.
43
+ 2. **Settings:** añade `AgentApiSettings` a la herencia de tu `Settings` (`core/config.py`). Variables: `AGENT_ENDPOINT_ENABLED=true`, `CHAT_MAX_QUESTION_LENGTH=4000`.
44
+ 3. **Auth:** copia `auth-verifier` y pasa `AuthFactory.create(settings)` a `create_app`, o escribe tu propio `TokenVerifier`.
45
+ 4. **`main.py`:**
46
+
47
+ ```python
48
+ settings = get_settings()
49
+ app = create_app(
50
+ settings=settings,
51
+ token_verifier=AuthFactory.create(settings),
52
+ memory=MemoryFactory.create(settings, session_factory=SessionLocal),
53
+ document_search=my_search_service,
54
+ tracer=TracingFactory.create(settings), # observability, opcional
55
+ cors_origins=settings.cors_origins,
56
+ )
57
+ ```
58
+
59
+ 5. **Cuota o rate limit:** copia `rate-limit-quota` (trae `ensure_turn_allowed` y `GET /agent/quota`) o implementa el guard tú (403 o 429 con `detail={"code": ...}`; el frontend lee `code` y `resets_at`).
60
+ 6. **Trazas, tokens y coste:** copia `observability` y pasa `tracer=TracingFactory.create(settings)`; el `TurnSummary` de cada turno sale en el log.
61
+ 7. **Más rutas:** `conversation-history` trae `api/conversations/` (listar, leer, borrar) y `agent-feedback` trae `api/feedback/` (pulgares). Para otras, un router por grupo en `api/<grupo>/router.py`, con `get_current_user` como dependencia, montado con `app.include_router` tras `create_app`.
62
+ 8. Para comprobarla: `pytest` con las recetas requeridas copiadas (`fastapi-base`, `project-settings`, `langchain-agent`, `agent-memory`, `langgraph-graph` y esta: 86 tests; 98 con `observability`).
63
+
64
+ **Dependencias** (además de las de `langgraph-graph`): `fastapi`, `sse-starlette`, `httpx` (tests). Probado con fastapi 0.162.5 y sse-starlette 3.7.0.
65
+
66
+ ## Origen
67
+
68
+ - Probado en producción: dos rutas (JSON y SSE) sobre el mismo grafo, `conversation_id` del cliente con `uuid4` del servidor si falta, tenant y usuario del token, guards antes del stream (flag 404 → acceso 403 → cuota → rate limit → saneado 400), `done` con `conversation_id` y `message_id`, persistir antes de responder, `error_id` en el stream, `EventSourceResponse` de sse-starlette, rate limit como dependencia que devuelve el usuario, `create_app(settings)` con los servicios y el verificador de tokens en `app.state`, `/docs` solo en desarrollo.
69
+ - Nuevo en esta receta: `TokenVerifier` como clase base con doble estático y `ensure_turn_allowed` como dependencia sustituible, para mantener la auth y las cuotas fuera de esta receta.
@@ -0,0 +1,35 @@
1
+ """Checks that run BEFORE a turn starts, in this order:
2
+
3
+ 1. endpoint enabled (404: off means "there is nothing here")
4
+ 2. authenticated (401, `get_current_user`)
5
+ 3. turn allowed (403 role without access, 429 quota or rate limit)
6
+
7
+ All of them before the stream opens: once the first SSE byte is out, the HTTP status is gone.
8
+ Step 3 is the extension point: the `rate-limit-quota` recipe (or your own rules) plugs in here.
9
+ """
10
+
11
+ from fastapi import Depends, HTTPException, Request, status
12
+
13
+ from ..auth import CurrentUser, get_current_user
14
+ from .settings import AgentApiSettings
15
+
16
+
17
+ def get_agent_api_settings(request: Request) -> AgentApiSettings:
18
+ settings: AgentApiSettings | None = getattr(request.app.state, "agent_api_settings", None)
19
+ if settings is None:
20
+ raise RuntimeError("app.state.agent_api_settings is not set: build the app with AgentApiSettings")
21
+ return settings
22
+
23
+
24
+ async def require_agent_enabled(settings: AgentApiSettings = Depends(get_agent_api_settings)) -> None:
25
+ if not settings.agent_endpoint_enabled:
26
+ raise HTTPException(status.HTTP_404_NOT_FOUND, "Not Found")
27
+
28
+
29
+ async def ensure_turn_allowed(user: CurrentUser = Depends(get_current_user)) -> CurrentUser:
30
+ """Role, quota and rate limit. Raise HTTPException(403/429) to refuse; return the user to allow.
31
+
32
+ Replace it (or `app.dependency_overrides[ensure_turn_allowed] = ...`) with your rules. Anything that
33
+ blocks (Redis, DB) goes through `run_in_threadpool` or an async client: never block the event loop.
34
+ """
35
+ return user
@@ -0,0 +1,86 @@
1
+ """POST /agent/chat (JSON) and POST /agent/stream (SSE): the same turn, two ways of answering.
2
+
3
+ Thin controller: guards -> sanitize -> build the key and the context from the token -> run the turn
4
+ (`agentic.conversation`). It knows nothing about the graph or the LLM.
5
+ """
6
+
7
+ import logging
8
+ import uuid
9
+
10
+ from fastapi import APIRouter, Depends, Request
11
+ from sse_starlette.sse import EventSourceResponse
12
+
13
+ from agentic.context import AgentContext
14
+ from agentic.conversation import answer_question, stream_answer
15
+ from agentic.graph import EventType, SSEEvent
16
+ from agentic.memory import Memory, MemoryKey
17
+
18
+ from ..auth import CurrentUser
19
+ from .guards import ensure_turn_allowed, get_agent_api_settings, require_agent_enabled
20
+ from .sanitize import sanitize_question
21
+ from .schemas import ChatRequest, ChatResponse
22
+ from .settings import AgentApiSettings
23
+ from .tracing import get_tracer, traced_turn
24
+
25
+ logger = logging.getLogger(__name__)
26
+
27
+ router = APIRouter(prefix="/agent", tags=["agent"], dependencies=[Depends(require_agent_enabled)])
28
+
29
+
30
+ def get_memory(request: Request) -> Memory:
31
+ memory: Memory | None = getattr(request.app.state, "memory", None)
32
+ if memory is None:
33
+ raise RuntimeError("app.state.memory is not set: build the app with a Memory (MemoryFactory)")
34
+ return memory
35
+
36
+
37
+ class Turn:
38
+ """What both endpoints need, built once: clean question, memory key and agent context."""
39
+
40
+ def __init__(self, body: ChatRequest, user: CurrentUser, settings: AgentApiSettings) -> None:
41
+ self.question = sanitize_question(body.question, max_length=settings.chat_max_question_length)
42
+ conversation_id = body.conversation_id or str(uuid.uuid4())
43
+ # The three ids. The client only chooses the last one; the other two come from the token.
44
+ self.key = MemoryKey(tenant_id=user.tenant_id, user_id=user.id, conversation_id=conversation_id)
45
+ self.context = AgentContext(
46
+ tenant_id=user.tenant_id, user_id=user.id, language=body.language or user.language
47
+ )
48
+
49
+
50
+ def prepare_turn(
51
+ body: ChatRequest,
52
+ user: CurrentUser = Depends(ensure_turn_allowed),
53
+ settings: AgentApiSettings = Depends(get_agent_api_settings),
54
+ ) -> Turn:
55
+ return Turn(body, user, settings)
56
+
57
+
58
+ @router.post("/chat", response_model=ChatResponse)
59
+ async def chat(
60
+ turn: Turn = Depends(prepare_turn), memory: Memory = Depends(get_memory), tracer=Depends(get_tracer)
61
+ ) -> ChatResponse:
62
+ with traced_turn(tracer, turn.key) as config:
63
+ result = await answer_question(turn.question, key=turn.key, context=turn.context, memory=memory, config=config)
64
+ return ChatResponse(**result.model_dump())
65
+
66
+
67
+ @router.post("/stream")
68
+ async def stream(
69
+ turn: Turn = Depends(prepare_turn), memory: Memory = Depends(get_memory), tracer=Depends(get_tracer)
70
+ ) -> EventSourceResponse:
71
+ """Same turn as `/chat`, answered as SSE events (see `agentic/graph/events.py`). Ends with
72
+ `done` (same fields as `ChatResponse`) or `error` with a correlation id, never with details."""
73
+
74
+ async def events():
75
+ try:
76
+ with traced_turn(tracer, turn.key) as config:
77
+ async for event in stream_answer(
78
+ turn.question, key=turn.key, context=turn.context, memory=memory, config=config
79
+ ):
80
+ yield event.to_sse()
81
+ except Exception: # outside the graph (memory, network): the graph already guards its own
82
+ error_id = uuid.uuid4().hex[:12]
83
+ logger.exception("Chat stream failed (error_id=%s, thread=%s)", error_id, turn.key.thread_id)
84
+ yield SSEEvent(type=EventType.ERROR, data={"error_id": error_id}).to_sse()
85
+
86
+ return EventSourceResponse(events())
@@ -0,0 +1,22 @@
1
+ """Text of the question before it reaches the graph. Trim, length, control characters, tags."""
2
+
3
+ import re
4
+
5
+ from fastapi import HTTPException, status
6
+
7
+ _CONTROL_CHARS = re.compile(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]") # keeps \n and \t
8
+ _HTML_TAGS = re.compile(r"<[^>]+>")
9
+
10
+
11
+ def sanitize_question(question: str, *, max_length: int) -> str:
12
+ """Clean question or 400. Prompt-injection detection, if any, goes here as a log, not a block."""
13
+ question = question.strip()
14
+ if not question:
15
+ raise HTTPException(status.HTTP_400_BAD_REQUEST, "The question cannot be empty.")
16
+ if len(question) > max_length:
17
+ raise HTTPException(status.HTTP_400_BAD_REQUEST, f"The question exceeds {max_length} characters.")
18
+ question = _CONTROL_CHARS.sub("", question)
19
+ question = _HTML_TAGS.sub("", question).strip()
20
+ if not question:
21
+ raise HTTPException(status.HTTP_400_BAD_REQUEST, "The question cannot be empty.")
22
+ return question
@@ -0,0 +1,26 @@
1
+ """Request and response of the chat endpoints: the HTTP side of the contract with the frontend."""
2
+
3
+ from pydantic import BaseModel, Field
4
+
5
+
6
+ class ChatRequest(BaseModel):
7
+ question: str = Field(min_length=1, max_length=10_000, description="Checked again by the sanitizer.")
8
+ conversation_id: str | None = Field(
9
+ default=None,
10
+ max_length=100,
11
+ pattern=r"^[A-Za-z0-9_\-]+$",
12
+ description=(
13
+ "The thread, chosen by the client (one uuid per conversation). Generated by the server when "
14
+ "absent. It is NOT the whole key: the backend prepends tenant and user from the token, so "
15
+ "sending someone else's id does not open their thread."
16
+ ),
17
+ )
18
+ language: str | None = Field(
19
+ default=None, min_length=2, max_length=5, description="ISO 639-1. Falls back to the user's language."
20
+ )
21
+
22
+
23
+ class ChatResponse(BaseModel):
24
+ answer: str
25
+ conversation_id: str = Field(description="Send it back in the next turn of the same conversation.")
26
+ message_id: str | None = Field(default=None, description="Persisted answer; what a vote points at.")
@@ -0,0 +1,14 @@
1
+ """Settings block of the chat endpoints. The project `Settings` inherits it (project-settings)."""
2
+
3
+ from pydantic import Field
4
+ from pydantic_settings import BaseSettings, SettingsConfigDict
5
+
6
+
7
+ class AgentApiSettings(BaseSettings):
8
+ model_config = SettingsConfigDict(env_file=".env", extra="ignore")
9
+
10
+ agent_endpoint_enabled: bool = Field(
11
+ default=True,
12
+ description="Kill switch. Off -> the chat routes answer 404, as if they did not exist.",
13
+ )
14
+ chat_max_question_length: int = Field(default=4000, ge=1, description="Longer questions get a 400.")
@@ -0,0 +1,38 @@
1
+ """Per-turn tracing, optional: if `app.state.tracer` exists (recipe `observability`), every turn
2
+ runs with its `config` and ends with `finish()`; if not, the turn runs with the default config.
3
+
4
+ The tracer is duck-typed on purpose: this recipe does not import `observability`. What it needs:
5
+ `begin_turn(thread_id=, tenant_id=, user_id=, request_id=) -> trace` with `.config` and `.finish(error=None)`.
6
+ """
7
+
8
+ from collections.abc import Iterator
9
+ from contextlib import contextmanager
10
+ from typing import Any
11
+
12
+ from fastapi import Request
13
+ from langchain_core.runnables import RunnableConfig
14
+
15
+ from ..request_id import current_request_id
16
+ from agentic.memory import MemoryKey
17
+
18
+
19
+ def get_tracer(request: Request) -> Any | None:
20
+ return getattr(request.app.state, "tracer", None)
21
+
22
+
23
+ @contextmanager
24
+ def traced_turn(tracer: Any | None, key: MemoryKey) -> Iterator[RunnableConfig | None]:
25
+ """`with traced_turn(tracer, key) as config:` around the turn. Finishes the trace with the error
26
+ class if the turn fails, and re-raises."""
27
+ if tracer is None:
28
+ yield None
29
+ return
30
+ trace = tracer.begin_turn(
31
+ thread_id=key.thread_id, tenant_id=key.tenant_id, user_id=key.user_id, request_id=current_request_id()
32
+ )
33
+ try:
34
+ yield trace.config
35
+ except BaseException as exc:
36
+ trace.finish(error=exc)
37
+ raise
38
+ trace.finish()
@@ -0,0 +1,67 @@
1
+ """`create_app(...)`: the FastAPI app with everything it needs injected.
2
+
3
+ Starts from `build_app` (recipe `fastapi-base`: request id, 500 without internals, CORS, /health,
4
+ docs flag) and adds the chat: the graph in the lifespan, the services in `app.state`, the router.
5
+ Nothing is read from the environment here: the caller (your `main.py`, or a test) builds the
6
+ pieces from the project settings and passes them in. That is the test seam.
7
+
8
+ # main.py
9
+ settings = get_settings() # project-settings
10
+ configure_logging(settings.log_level) # fastapi-base
11
+ app = create_app(
12
+ settings=settings, # inherits AgentApiSettings
13
+ token_verifier=AuthFactory.create(settings), # auth-verifier (or your subclass)
14
+ memory=MemoryFactory.create(settings, session_factory=SessionLocal),
15
+ document_search=my_search_service,
16
+ tracer=TracingFactory.create(settings), # observability (optional)
17
+ cors_origins=settings.cors_origins, # ApiSettings, fastapi-base
18
+ )
19
+ """
20
+
21
+ from collections.abc import AsyncIterator, Sequence
22
+ from contextlib import asynccontextmanager
23
+ from typing import Any
24
+
25
+ from fastapi import FastAPI
26
+
27
+ from agentic.graph import compile_graph
28
+ from agentic.llm import LLMSettings
29
+ from agentic.memory import Memory
30
+ from agentic.registry import registry
31
+
32
+ from .agent.router import router as agent_router
33
+ from .agent.settings import AgentApiSettings
34
+ from .auth import TokenVerifier
35
+ from .base import build_app
36
+
37
+
38
+ def create_app(
39
+ *,
40
+ settings: AgentApiSettings,
41
+ token_verifier: TokenVerifier,
42
+ memory: Memory,
43
+ document_search: Any,
44
+ llm_settings: LLMSettings | None = None,
45
+ tracer: Any | None = None,
46
+ docs: bool = False,
47
+ cors_origins: Sequence[str] = (),
48
+ ) -> FastAPI:
49
+ """`llm_settings=None` -> the project settings (`get_llm_settings()`); pass one only in tests.
50
+ `tracer` (recipe `observability`, `TracingFactory.create(settings)`) traces every turn; None = no traces.
51
+ `docs=False` hides /docs and /openapi.json: enable it in development only."""
52
+
53
+ @asynccontextmanager
54
+ async def lifespan(app: FastAPI) -> AsyncIterator[None]:
55
+ registry.configure(document_search=document_search, settings=llm_settings)
56
+ compile_graph()
57
+ yield
58
+ if tracer is not None:
59
+ await tracer.flush()
60
+
61
+ app = build_app(title="{{app_name}}", lifespan=lifespan, docs=docs, cors_origins=cors_origins)
62
+ app.state.agent_api_settings = settings
63
+ app.state.token_verifier = token_verifier
64
+ app.state.memory = memory
65
+ app.state.tracer = tracer
66
+ app.include_router(agent_router)
67
+ return app