@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,43 @@
1
+ """Concrete agents. Each one only declares what makes it different."""
2
+
3
+ from collections.abc import Sequence
4
+
5
+ from langchain.agents.middleware import AgentMiddleware
6
+ from langchain_core.tools import BaseTool
7
+
8
+ from ..middleware import build_language_middleware
9
+ from ..prompts import load_prompt
10
+ from .base_agent import BaseAgent
11
+ from .models import AgentType, Classification
12
+
13
+
14
+ class AssistantAgent(BaseAgent):
15
+ """Conversational agent with tools. Plain-text answer (no response_format)."""
16
+
17
+ agent_type = AgentType.ASSISTANT
18
+
19
+ def __init__(self, *args, tools: Sequence[BaseTool], **kwargs) -> None:
20
+ super().__init__(*args, **kwargs)
21
+ self._tools = list(tools)
22
+
23
+ def get_prompt(self) -> str:
24
+ return load_prompt("assistant", self.language).render()
25
+
26
+ def get_tools(self) -> Sequence[BaseTool]:
27
+ return self._tools
28
+
29
+ def get_middleware(self) -> Sequence[AgentMiddleware]:
30
+ return [build_language_middleware()]
31
+
32
+
33
+ class ClassifierAgent(BaseAgent):
34
+ """Single-call agent without tools that returns a structured answer."""
35
+
36
+ agent_type = AgentType.CLASSIFIER
37
+ response_format = Classification
38
+
39
+ def get_prompt(self) -> str:
40
+ return (
41
+ "Classify the user's question. Categories: billing, technical, other.\n"
42
+ "Set needs_search to true if the answer depends on the user's documents."
43
+ )
@@ -0,0 +1,126 @@
1
+ """Base of every agent: a thin, testable wrapper around `langchain.agents.create_agent`.
2
+
3
+ Life cycle: `__init__` (cheap, no I/O) -> `await initialize()` (builds `self.agent` once)
4
+ -> `await process(...)` (one turn). `process` calls `initialize` itself, so callers may skip it.
5
+
6
+ A subclass declares:
7
+ - `agent_type` (class attribute)
8
+ - `response_format` (class attribute, optional): a Pydantic model -> `AgentTurn.structured`;
9
+ None -> plain text in `AgentTurn.answer`.
10
+ - `get_prompt()`: the system prompt (usually `load_prompt(...).render(...)`).
11
+ - `get_tools()` / `get_middleware()`: optional, empty by default.
12
+
13
+ The model is chosen FROM OUTSIDE (`model`, usually `LLMModel.from_id(settings.<agent>_model)`),
14
+ never hard-coded in the class. Credentials come from the project settings via `get_llm_settings()`;
15
+ `settings=` is only for tests.
16
+ `llm=` is the test seam: pass a fake chat model and nothing else is built.
17
+
18
+ The agent is stateless: it receives the history and returns the new messages. Persisting
19
+ them is the caller's job (see the langgraph-graph recipe, `memory/`).
20
+ """
21
+
22
+ import logging
23
+ from abc import ABC, abstractmethod
24
+ from collections.abc import Sequence
25
+ from typing import Any, ClassVar
26
+
27
+ from langchain.agents import create_agent
28
+ from langchain.agents.middleware import AgentMiddleware
29
+ from langchain_core.language_models.chat_models import BaseChatModel
30
+ from langchain_core.messages import AIMessage, BaseMessage, HumanMessage
31
+ from langchain_core.runnables import RunnableConfig
32
+ from langchain_core.tools import BaseTool
33
+ from pydantic import BaseModel
34
+
35
+ from ..context import AgentContext
36
+ from ..llm.models import LLMModel
37
+ from ..llm.provider import LLMProvider
38
+ from ..llm.settings import LLMSettings
39
+ from .models import AgentError, AgentTurn, AgentType
40
+
41
+ logger = logging.getLogger(__name__)
42
+
43
+
44
+ class BaseAgent(ABC):
45
+ agent_type: ClassVar[AgentType]
46
+ response_format: ClassVar[type[BaseModel] | None] = None
47
+ context_schema: ClassVar[type[BaseModel]] = AgentContext
48
+
49
+ def __init__(
50
+ self,
51
+ model: LLMModel | None = None,
52
+ settings: LLMSettings | None = None,
53
+ *,
54
+ language: str = "es",
55
+ temperature: float | None = 0.0,
56
+ streaming: bool = False,
57
+ llm: BaseChatModel | None = None,
58
+ ) -> None:
59
+ if llm is None:
60
+ if model is None:
61
+ raise ValueError(f"{type(self).__name__} needs a `model` (or an `llm` in tests)")
62
+ llm = LLMProvider.create_from_model(model, settings, temperature=temperature, streaming=streaming)
63
+ self.model = model
64
+ self.language = language
65
+ self.llm = llm
66
+ self.agent: Any = None
67
+
68
+ # --- What a subclass defines ---------------------------------------------------------------
69
+
70
+ @abstractmethod
71
+ def get_prompt(self) -> str:
72
+ """The system prompt of this agent."""
73
+
74
+ def get_tools(self) -> Sequence[BaseTool]:
75
+ return []
76
+
77
+ def get_middleware(self) -> Sequence[AgentMiddleware]:
78
+ return []
79
+
80
+ # --- Template -----------------------------------------------------------------------------
81
+
82
+ async def initialize(self) -> None:
83
+ """Build the LangChain agent once. A second call is a no-op."""
84
+ if self.agent is not None:
85
+ return
86
+ self.agent = create_agent(
87
+ model=self.llm,
88
+ tools=list(self.get_tools()),
89
+ system_prompt=self.get_prompt(),
90
+ middleware=list(self.get_middleware()),
91
+ response_format=self.response_format,
92
+ context_schema=self.context_schema,
93
+ name=self.agent_type.value,
94
+ )
95
+ logger.info("Agent %s ready (model=%s)", self.agent_type.value, getattr(self.model, "model_id", "injected"))
96
+
97
+ def build_messages(self, question: str, history: Sequence[BaseMessage]) -> list[BaseMessage]:
98
+ """Input messages of one turn. Override to add images, XML-tagged data, etc."""
99
+ return [*history, HumanMessage(question)]
100
+
101
+ async def process(
102
+ self,
103
+ question: str,
104
+ *,
105
+ context: AgentContext,
106
+ history: Sequence[BaseMessage] = (),
107
+ config: RunnableConfig | None = None,
108
+ ) -> AgentTurn:
109
+ """Run one turn. `config` carries callbacks/metadata (observability), never business data."""
110
+ await self.initialize()
111
+ previous = list(history)
112
+ result = await self.agent.ainvoke(
113
+ {"messages": self.build_messages(question, previous)}, context=context, config=config
114
+ )
115
+ return self._to_turn(result, len(previous))
116
+
117
+ def _to_turn(self, result: dict[str, Any], history_len: int) -> AgentTurn:
118
+ messages: list[BaseMessage] = result.get("messages") or []
119
+ if not messages:
120
+ raise AgentError("the agent produced no messages", kind="NoMessages")
121
+ structured = result.get("structured_response")
122
+ if self.response_format is not None and structured is None:
123
+ raise AgentError("the agent ended without a structured answer", kind="NoStructuredResponse")
124
+ last_ai = next((m for m in reversed(messages) if isinstance(m, AIMessage)), None)
125
+ answer = str(last_ai.text) if last_ai is not None else ""
126
+ return AgentTurn(answer=answer, structured=structured, new_messages=messages[history_len:])
@@ -0,0 +1,46 @@
1
+ """Agent types, the turn result and the structured answers (`response_format`)."""
2
+
3
+ from enum import Enum
4
+ from typing import Any
5
+
6
+ from langchain_core.messages import BaseMessage
7
+ from pydantic import BaseModel, ConfigDict, Field
8
+
9
+
10
+ class AgentType(str, Enum):
11
+ ASSISTANT = "assistant"
12
+ CLASSIFIER = "classifier"
13
+
14
+
15
+ class AgentTurn(BaseModel):
16
+ """What `BaseAgent.process` returns.
17
+
18
+ - `answer`: text of the last AI message ("" if the agent only returned structured output).
19
+ - `structured`: the `response_format` instance, or None when the agent has no response_format.
20
+ - `new_messages`: messages produced in this turn (human + AI + tools), ready to persist in memory.
21
+ """
22
+
23
+ model_config = ConfigDict(frozen=True, arbitrary_types_allowed=True)
24
+
25
+ answer: str
26
+ structured: Any = None
27
+ new_messages: list[BaseMessage] = Field(default_factory=list)
28
+
29
+
30
+ class AgentError(RuntimeError):
31
+ """The agent ended in a state the caller cannot use. `kind` is safe to log; the text may not be."""
32
+
33
+ def __init__(self, message: str, *, kind: str) -> None:
34
+ super().__init__(message)
35
+ self.kind = kind
36
+
37
+
38
+ # --- Structured answers: one Pydantic model per agent that needs one ---------------------------
39
+
40
+
41
+ class Classification(BaseModel):
42
+ """Example `response_format` for a classifier agent."""
43
+
44
+ category: str = Field(description="One of the categories listed in the prompt.")
45
+ needs_search: bool = Field(description="True if answering requires searching the documents.")
46
+ confidence: float = Field(ge=0, le=1, description="How sure the classification is, 0 to 1.")
@@ -0,0 +1,21 @@
1
+ """Run context: data the agent's tools and middleware need but the LLM never sees."""
2
+
3
+ from pydantic import BaseModel, ConfigDict, Field
4
+
5
+
6
+ class AgentContext(BaseModel):
7
+ """Passed as `context=` on every run and declared as `context_schema` in `create_agent`.
8
+
9
+ Tools read it via `runtime.context` (`ToolRuntime`), middleware via `request.runtime.context`
10
+ and graph nodes via `runtime.context` (`Runtime`). It never goes into a prompt or a tool
11
+ argument, so the LLM cannot read or forge the tenant.
12
+
13
+ Add the fields your app needs (feature flags, permissions, model tier...). Keep it small
14
+ and immutable: it is security data, not working state.
15
+ """
16
+
17
+ model_config = ConfigDict(extra="forbid", frozen=True)
18
+
19
+ tenant_id: str = Field(description="Tenant the run belongs to. Every data access filters by it.")
20
+ user_id: str = Field(description="User who asked.")
21
+ language: str = Field(default="es", description="ISO 639-1 code the answer must be written in.")
@@ -0,0 +1,5 @@
1
+ from .models import LLMModel, LLMProviderName
2
+ from .provider import LLMProvider
3
+ from .settings import LLMSettings, get_llm_settings
4
+
5
+ __all__ = ["LLMModel", "LLMProvider", "LLMProviderName", "LLMSettings", "get_llm_settings"]
@@ -0,0 +1,45 @@
1
+ """Catalogue of the models the app may use. Add a member to use a new model; nothing else changes."""
2
+
3
+ from enum import Enum
4
+
5
+
6
+ class LLMProviderName(str, Enum):
7
+ OPENAI = "openai"
8
+ ANTHROPIC = "anthropic"
9
+ AZURE_OPENAI = "azure_openai"
10
+ GROQ = "groq"
11
+
12
+
13
+ class LLMModel(Enum):
14
+ """`(provider, model_id, reasoning_effort)`.
15
+
16
+ - `model_id` is what the provider expects. For Azure OpenAI it is the *deployment name*.
17
+ - `reasoning_effort` is the default for that model (`None` = do not send it). Only send it
18
+ to models that accept it.
19
+ """
20
+
21
+ # OpenAI
22
+ GPT_4_1 = (LLMProviderName.OPENAI, "gpt-4.1", None)
23
+ GPT_4_1_MINI = (LLMProviderName.OPENAI, "gpt-4.1-mini", None)
24
+ GPT_4_1_NANO = (LLMProviderName.OPENAI, "gpt-4.1-nano", None)
25
+ # Anthropic
26
+ CLAUDE_SONNET_5_5 = (LLMProviderName.ANTHROPIC, "claude-sonnet-5-5", None)
27
+ CLAUDE_HAIKU_5_5 = (LLMProviderName.ANTHROPIC, "claude-haiku-5-5", None)
28
+ # Azure OpenAI: model_id = your deployment name
29
+ AZURE_GPT_4_1 = (LLMProviderName.AZURE_OPENAI, "gpt-4.1", None)
30
+ # Groq
31
+ LLAMA_3_3_70B = (LLMProviderName.GROQ, "llama-3.3-70b-versatile", None)
32
+
33
+ def __init__(self, provider: LLMProviderName, model_id: str, reasoning_effort: str | None) -> None:
34
+ self.provider = provider
35
+ self.model_id = model_id
36
+ self.reasoning_effort = reasoning_effort
37
+
38
+ @classmethod
39
+ def from_id(cls, model_id: str) -> "LLMModel":
40
+ """Member for a model id read from settings/env. Unknown id -> ValueError listing the valid ones."""
41
+ for member in cls:
42
+ if member.model_id == model_id:
43
+ return member
44
+ valid = ", ".join(sorted({m.model_id for m in cls}))
45
+ raise ValueError(f"Unknown model id {model_id!r}. Valid: {valid}")
@@ -0,0 +1,78 @@
1
+ """Factory: `LLMModel` + project settings -> LangChain chat model. The only place that knows provider classes."""
2
+
3
+ from typing import Any
4
+
5
+ from langchain_core.language_models.chat_models import BaseChatModel
6
+
7
+ from .models import LLMModel, LLMProviderName
8
+ from .settings import LLMSettings, get_llm_settings
9
+
10
+ _NOT_PASSED: Any = object()
11
+
12
+
13
+ class LLMProvider:
14
+ @staticmethod
15
+ def create_from_model(
16
+ model: LLMModel,
17
+ settings: LLMSettings | None = None,
18
+ *,
19
+ temperature: float | None = None,
20
+ streaming: bool = False,
21
+ reasoning_effort: str | None = _NOT_PASSED,
22
+ ) -> BaseChatModel:
23
+ """Build the chat model for `model`.
24
+
25
+ - `temperature=None` -> not sent (reasoning models reject it).
26
+ - `reasoning_effort` not passed -> the model's default (`LLMModel.reasoning_effort`).
27
+ - Provider packages are imported lazily: install only the ones you use.
28
+ - `settings=None` -> the project settings (`get_llm_settings()`); pass one only in tests.
29
+ - Unknown provider -> ValueError. There is no silent default.
30
+ """
31
+ effort = model.reasoning_effort if reasoning_effort is _NOT_PASSED else reasoning_effort
32
+ settings = settings or get_llm_settings()
33
+ api_key = settings.api_key_for(model.provider.value)
34
+ common: dict[str, Any] = {
35
+ "timeout": settings.llm_timeout_seconds,
36
+ "max_retries": settings.llm_max_retries,
37
+ "streaming": streaming,
38
+ }
39
+ if temperature is not None:
40
+ common["temperature"] = temperature
41
+
42
+ match model.provider:
43
+ case LLMProviderName.OPENAI:
44
+ from langchain_openai import ChatOpenAI
45
+
46
+ if effort is not None:
47
+ common["reasoning_effort"] = effort
48
+ return ChatOpenAI(model=model.model_id, api_key=api_key, stream_usage=True, **common)
49
+
50
+ case LLMProviderName.AZURE_OPENAI:
51
+ from langchain_openai import AzureChatOpenAI
52
+
53
+ if not settings.azure_openai_endpoint or not settings.azure_openai_api_version:
54
+ raise ValueError("Azure OpenAI needs azure_openai_endpoint and azure_openai_api_version")
55
+ if effort is not None:
56
+ common["reasoning_effort"] = effort
57
+ return AzureChatOpenAI(
58
+ azure_deployment=model.model_id,
59
+ azure_endpoint=settings.azure_openai_endpoint,
60
+ api_version=settings.azure_openai_api_version,
61
+ api_key=api_key,
62
+ stream_usage=True,
63
+ **common,
64
+ )
65
+
66
+ case LLMProviderName.ANTHROPIC:
67
+ from langchain_anthropic import ChatAnthropic
68
+
69
+ if effort is not None:
70
+ common["reasoning_effort"] = effort
71
+ return ChatAnthropic(model=model.model_id, api_key=api_key, max_tokens=8192, **common)
72
+
73
+ case LLMProviderName.GROQ:
74
+ from langchain_groq import ChatGroq
75
+
76
+ return ChatGroq(model=model.model_id, api_key=api_key, **common)
77
+
78
+ raise ValueError(f"Unsupported provider: {model.provider!r}")
@@ -0,0 +1,62 @@
1
+ """LLM settings BLOCK: the config this recipe needs, meant to be mixed into the project settings.
2
+
3
+ This recipe does not ship the project settings (that is the `project-settings` recipe, or the
4
+ one your backend already has). It only brings this block:
5
+
6
+ # core/config.py
7
+ from agentic.llm.settings import LLMSettings
8
+
9
+ class Settings(LLMSettings, BaseAppSettings): ...
10
+
11
+ Env vars it reads: OPENAI_API_KEY, ANTHROPIC_API_KEY, GROQ_API_KEY, AZURE_OPENAI_API_KEY,
12
+ AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_VERSION, LLM_TIMEOUT_SECONDS, LLM_MAX_RETRIES,
13
+ ASSISTANT_MODEL, CLASSIFIER_MODEL.
14
+ """
15
+
16
+ from pydantic import SecretStr
17
+ from pydantic_settings import BaseSettings, SettingsConfigDict
18
+
19
+ # The ONLY line that knows where the project settings live. Change it to your path.
20
+ PROJECT_SETTINGS = "core.config"
21
+
22
+
23
+ class LLMSettings(BaseSettings):
24
+ model_config = SettingsConfigDict(extra="ignore")
25
+
26
+ openai_api_key: SecretStr | None = None
27
+ anthropic_api_key: SecretStr | None = None
28
+ groq_api_key: SecretStr | None = None
29
+ azure_openai_api_key: SecretStr | None = None
30
+ azure_openai_endpoint: str | None = None
31
+ azure_openai_api_version: str | None = None
32
+
33
+ llm_timeout_seconds: float = 60.0
34
+ llm_max_retries: int = 2
35
+
36
+ # Model per agent, as an LLMModel id (see models.py)
37
+ assistant_model: str = "gpt-4.1-mini"
38
+ classifier_model: str = "gpt-4.1-nano"
39
+
40
+ def api_key_for(self, provider: str) -> SecretStr:
41
+ """`provider` is an `LLMProviderName` value: openai | anthropic | groq | azure_openai."""
42
+ key: SecretStr | None = getattr(self, f"{provider}_api_key", None)
43
+ if key is None or not key.get_secret_value():
44
+ raise ValueError(f"Missing API key for provider {provider!r}: set {provider.upper()}_API_KEY")
45
+ return key
46
+
47
+
48
+ def get_llm_settings() -> LLMSettings:
49
+ """The project settings (which inherit `LLMSettings`). Imported lazily: copying this recipe
50
+ alone never breaks on import; it only fails here, with a clear message, if nothing is wired."""
51
+ from importlib import import_module
52
+
53
+ try:
54
+ settings = import_module(PROJECT_SETTINGS).get_settings()
55
+ except (ImportError, AttributeError) as exc:
56
+ raise RuntimeError(
57
+ f"No project settings at {PROJECT_SETTINGS!r}.get_settings(). Add the `project-settings` "
58
+ "recipe (or point PROJECT_SETTINGS at yours) and mix LLMSettings into its Settings."
59
+ ) from exc
60
+ if not isinstance(settings, LLMSettings):
61
+ raise RuntimeError("The project Settings must inherit LLMSettings: class Settings(LLMSettings, ...)")
62
+ return settings
@@ -0,0 +1,3 @@
1
+ from .language import build_language_middleware
2
+
3
+ __all__ = ["build_language_middleware"]
@@ -0,0 +1,28 @@
1
+ """Example middleware: remind the model of the answer language on every model call.
2
+
3
+ Pattern: a `build_*_middleware(...)` factory returns a `@wrap_model_call` function that changes
4
+ the request only for that call with `request.override(...)`. The stored history is untouched.
5
+ """
6
+
7
+ from collections.abc import Awaitable, Callable
8
+
9
+ from langchain.agents.middleware import ModelRequest, ModelResponse, wrap_model_call
10
+ from langchain_core.messages import SystemMessage
11
+
12
+ LANGUAGE_NAMES = {"es": "Spanish", "en": "English", "fr": "French", "de": "German", "it": "Italian", "pt": "Portuguese"}
13
+
14
+
15
+ def build_language_middleware():
16
+ @wrap_model_call
17
+ async def language_reminder(
18
+ request: ModelRequest, handler: Callable[[ModelRequest], Awaitable[ModelResponse]]
19
+ ) -> ModelResponse:
20
+ context = request.runtime.context if request.runtime else None
21
+ language = getattr(context, "language", None)
22
+ if not language:
23
+ return await handler(request)
24
+ name = LANGUAGE_NAMES.get(language, language)
25
+ reminder = SystemMessage(f"Answer in {name}, whatever the language of the documents.")
26
+ return await handler(request.override(messages=[*request.messages, reminder]))
27
+
28
+ return language_reminder
@@ -0,0 +1,3 @@
1
+ from .loader import Prompt, load_prompt
2
+
3
+ __all__ = ["Prompt", "load_prompt"]
@@ -0,0 +1,15 @@
1
+ name: assistant
2
+ version: 1
3
+ language: en
4
+ description: Example assistant that answers using the search tool.
5
+ system: |
6
+ # Role and objective
7
+ You are the assistant of {{app_name}}. You answer questions about the user's documents.
8
+
9
+ # Tools
10
+ - `search_documents`: use it whenever the answer depends on the documents.
11
+ Do not make data up: if the search returns nothing, say so.
12
+
13
+ # Answer format
14
+ - Answer in English, briefly and directly.
15
+ - Cite the title of the document each fact comes from.
@@ -0,0 +1,15 @@
1
+ name: assistant
2
+ version: 1
3
+ language: es
4
+ description: Asistente de ejemplo que responde usando la tool de búsqueda.
5
+ system: |
6
+ # Rol y objetivo
7
+ Eres el asistente de {{app_name}}. Respondes preguntas sobre la documentación del usuario.
8
+
9
+ # Herramientas
10
+ - `search_documents`: úsala siempre que la respuesta dependa de la documentación.
11
+ No inventes datos: si la búsqueda no devuelve nada, dilo.
12
+
13
+ # Formato de la respuesta
14
+ - Responde en español, de forma breve y directa.
15
+ - Cita el título del documento del que sale cada dato.
@@ -0,0 +1,69 @@
1
+ """Prompts as versioned data: `prompts/<name>.<language>.yaml`.
2
+
3
+ File format:
4
+
5
+ name: assistant
6
+ version: 1 # bump on every change; it is logged with each run
7
+ language: es
8
+ description: One line on what this prompt is for.
9
+ system: |
10
+ The system prompt text. Placeholders use str.format: {tenant_name}
11
+
12
+ Rules:
13
+ - One file per prompt and language. Missing language -> falls back to DEFAULT_LANGUAGE with a warning.
14
+ - No Jinja, no ChatPromptTemplate: the system prompt is a plain string passed to `create_agent`.
15
+ - Wrap data you inject in XML tags (<question>...</question>) so the model tells data from instructions.
16
+ """
17
+
18
+ import logging
19
+ from functools import lru_cache
20
+ from pathlib import Path
21
+
22
+ import yaml
23
+ from pydantic import BaseModel, ConfigDict
24
+
25
+ logger = logging.getLogger(__name__)
26
+
27
+ PROMPTS_DIR = Path(__file__).parent
28
+ DEFAULT_LANGUAGE = "es"
29
+ _REQUIRED = ("name", "version", "language", "system")
30
+
31
+
32
+ class Prompt(BaseModel):
33
+ model_config = ConfigDict(frozen=True)
34
+
35
+ name: str
36
+ version: int
37
+ language: str
38
+ description: str
39
+ system: str
40
+
41
+ def render(self, **values: str) -> str:
42
+ """`system` with its `{placeholders}` filled. A missing value raises KeyError."""
43
+ return self.system.format(**values) if values else self.system
44
+
45
+
46
+ @lru_cache(maxsize=None)
47
+ def load_prompt(name: str, language: str = DEFAULT_LANGUAGE) -> Prompt:
48
+ """Load and cache a prompt. Names must be identifiers (guards against path traversal)."""
49
+ if not name.isidentifier() or not language.isalpha():
50
+ raise ValueError(f"Invalid prompt name or language: {name!r}, {language!r}")
51
+
52
+ path = PROMPTS_DIR / f"{name}.{language}.yaml"
53
+ if not path.exists():
54
+ if language == DEFAULT_LANGUAGE:
55
+ raise FileNotFoundError(f"Prompt not found: {path.name}")
56
+ logger.warning("Prompt %s has no %r version; using %r", name, language, DEFAULT_LANGUAGE)
57
+ return load_prompt(name, DEFAULT_LANGUAGE)
58
+
59
+ data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
60
+ missing = [key for key in _REQUIRED if key not in data]
61
+ if missing:
62
+ raise ValueError(f"Prompt {path.name} is missing fields: {missing}")
63
+ return Prompt(
64
+ name=data["name"],
65
+ version=int(data["version"]),
66
+ language=data["language"],
67
+ description=data.get("description", ""),
68
+ system=data["system"],
69
+ )
@@ -0,0 +1,25 @@
1
+ """Tool registry: adding a tool = one file + one line in `ToolSet.default`."""
2
+
3
+ from collections.abc import Sequence
4
+ from typing import Any
5
+
6
+ from langchain_core.tools import BaseTool
7
+
8
+ from .base_tool import AppTool, ToolContextError
9
+ from .search_documents import SearchDocumentsTool
10
+
11
+
12
+ class ToolSet:
13
+ @staticmethod
14
+ def default(*, document_search: Any) -> list[BaseTool]:
15
+ """The tools of the main agent, built with the services they need."""
16
+ return [
17
+ SearchDocumentsTool(service=document_search),
18
+ ]
19
+
20
+ @staticmethod
21
+ def names(tools: Sequence[BaseTool]) -> list[str]:
22
+ return [tool.name for tool in tools]
23
+
24
+
25
+ __all__ = ["AppTool", "SearchDocumentsTool", "ToolContextError", "ToolSet"]
@@ -0,0 +1,62 @@
1
+ """Base for every tool of the app.
2
+
3
+ A tool subclass declares:
4
+ - `name`: snake_case verb (`search_documents`, `get_order`).
5
+ - `description`: explicit string, not a docstring. Says WHEN to use it and WHAT it returns.
6
+ It is all the LLM knows about the tool.
7
+ - `args_schema`: Pydantic model with `Field(description=...)` per argument, plus a
8
+ `runtime: ToolRuntime` field. `runtime` is injected by LangChain and hidden from the LLM.
9
+ - `execute(runtime, **args)`: the async work. Return a string (what the LLM reads).
10
+
11
+ The base gives:
12
+ - `_arun` with fail-safe errors: an exception is logged and the LLM gets SAFE_FAILURE,
13
+ never the internal message (it could leak keys, SQL, paths...).
14
+ - `context_of(runtime)`: the AgentContext, fail-closed if it is missing.
15
+ - `emit(runtime, data)`: custom stream event (shows up in `stream_mode="custom"`).
16
+ """
17
+
18
+ import logging
19
+ from abc import abstractmethod
20
+ from typing import Any, ClassVar
21
+
22
+ from langchain.tools import BaseTool, ToolRuntime
23
+
24
+ from ..context import AgentContext
25
+
26
+ logger = logging.getLogger(__name__)
27
+
28
+
29
+ class ToolContextError(RuntimeError):
30
+ """The tool ran without an AgentContext: a wiring bug. Never answer without a tenant."""
31
+
32
+
33
+ class AppTool(BaseTool):
34
+ SAFE_FAILURE: ClassVar[str] = "The tool failed. Do not retry it; answer with what you already have."
35
+
36
+ @abstractmethod
37
+ async def execute(self, runtime: ToolRuntime, **kwargs: Any) -> str:
38
+ """The work of the tool. Raise freely: `_arun` turns errors into SAFE_FAILURE."""
39
+
40
+ def _run(self, *args: Any, **kwargs: Any) -> str:
41
+ raise NotImplementedError(f"{self.name} is async only; run the agent with ainvoke/astream")
42
+
43
+ async def _arun(self, *args: Any, runtime: ToolRuntime, **kwargs: Any) -> str:
44
+ try:
45
+ return await self.execute(runtime, **kwargs)
46
+ except ToolContextError:
47
+ raise
48
+ except Exception:
49
+ logger.exception("Tool %s failed", self.name)
50
+ return self.SAFE_FAILURE
51
+
52
+ @staticmethod
53
+ def context_of(runtime: ToolRuntime) -> AgentContext:
54
+ context = getattr(runtime, "context", None)
55
+ if not isinstance(context, AgentContext):
56
+ raise ToolContextError("Tool called without AgentContext (pass context= to the agent run)")
57
+ return context
58
+
59
+ @staticmethod
60
+ def emit(runtime: ToolRuntime, data: dict[str, Any]) -> None:
61
+ if runtime.stream_writer is not None:
62
+ runtime.stream_writer(data)