@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.
- package/README.md +227 -2
- package/catalog.yaml +140 -0
- package/cli/copypasta.js +4 -0
- package/cli/lib/catalog.js +131 -0
- package/cli/lib/commands.js +162 -0
- package/cli/lib/index.js +4 -0
- package/cli/lib/main.js +130 -0
- package/package.json +38 -4
- package/recipes/agents/agent-memory/RECIPE.md +75 -0
- package/recipes/agents/agent-memory/files/agentic/memory/__init__.py +25 -0
- package/recipes/agents/agent-memory/files/agentic/memory/base.py +101 -0
- package/recipes/agents/agent-memory/files/agentic/memory/factory.py +33 -0
- package/recipes/agents/agent-memory/files/agentic/memory/in_memory.py +59 -0
- package/recipes/agents/agent-memory/files/agentic/memory/models.py +66 -0
- package/recipes/agents/agent-memory/files/agentic/memory/settings.py +24 -0
- package/recipes/agents/agent-memory/files/agentic/memory/sql.py +177 -0
- package/recipes/agents/agent-memory/files/pytest.ini +5 -0
- package/recipes/agents/agent-memory/files/tests/__init__.py +0 -0
- package/recipes/agents/agent-memory/files/tests/memory_conformance.py +158 -0
- package/recipes/agents/agent-memory/files/tests/test_memory.py +74 -0
- package/recipes/agents/langchain-agent/RECIPE.md +101 -0
- package/recipes/agents/langchain-agent/files/agentic/__init__.py +10 -0
- package/recipes/agents/langchain-agent/files/agentic/agents/__init__.py +13 -0
- package/recipes/agents/langchain-agent/files/agentic/agents/agents.py +43 -0
- package/recipes/agents/langchain-agent/files/agentic/agents/base_agent.py +126 -0
- package/recipes/agents/langchain-agent/files/agentic/agents/models.py +46 -0
- package/recipes/agents/langchain-agent/files/agentic/context.py +21 -0
- package/recipes/agents/langchain-agent/files/agentic/llm/__init__.py +5 -0
- package/recipes/agents/langchain-agent/files/agentic/llm/models.py +45 -0
- package/recipes/agents/langchain-agent/files/agentic/llm/provider.py +78 -0
- package/recipes/agents/langchain-agent/files/agentic/llm/settings.py +62 -0
- package/recipes/agents/langchain-agent/files/agentic/middleware/__init__.py +3 -0
- package/recipes/agents/langchain-agent/files/agentic/middleware/language.py +28 -0
- package/recipes/agents/langchain-agent/files/agentic/prompts/__init__.py +3 -0
- package/recipes/agents/langchain-agent/files/agentic/prompts/assistant.en.yaml +15 -0
- package/recipes/agents/langchain-agent/files/agentic/prompts/assistant.es.yaml +15 -0
- package/recipes/agents/langchain-agent/files/agentic/prompts/loader.py +69 -0
- package/recipes/agents/langchain-agent/files/agentic/tools/__init__.py +25 -0
- package/recipes/agents/langchain-agent/files/agentic/tools/base_tool.py +62 -0
- package/recipes/agents/langchain-agent/files/agentic/tools/search_documents.py +42 -0
- package/recipes/agents/langchain-agent/files/pytest.ini +5 -0
- package/recipes/agents/langchain-agent/files/tests/__init__.py +0 -0
- package/recipes/agents/langchain-agent/files/tests/fakes.py +30 -0
- package/recipes/agents/langchain-agent/files/tests/test_agents.py +151 -0
- package/recipes/agents/langgraph-graph/RECIPE.md +63 -0
- package/recipes/agents/langgraph-graph/files/agentic/conversation.py +73 -0
- package/recipes/agents/langgraph-graph/files/agentic/graph/__init__.py +17 -0
- package/recipes/agents/langgraph-graph/files/agentic/graph/builder.py +37 -0
- package/recipes/agents/langgraph-graph/files/agentic/graph/edges.py +8 -0
- package/recipes/agents/langgraph-graph/files/agentic/graph/event_processor.py +48 -0
- package/recipes/agents/langgraph-graph/files/agentic/graph/events.py +30 -0
- package/recipes/agents/langgraph-graph/files/agentic/graph/graph.py +60 -0
- package/recipes/agents/langgraph-graph/files/agentic/graph/nodes.py +63 -0
- package/recipes/agents/langgraph-graph/files/agentic/graph/state.py +31 -0
- package/recipes/agents/langgraph-graph/files/agentic/registry.py +85 -0
- package/recipes/agents/langgraph-graph/files/tests/test_graph.py +145 -0
- package/recipes/backend/.gitkeep +0 -0
- package/recipes/backend/agent-chat-api/RECIPE.md +69 -0
- package/recipes/backend/agent-chat-api/files/api/agent/guards.py +35 -0
- package/recipes/backend/agent-chat-api/files/api/agent/router.py +86 -0
- package/recipes/backend/agent-chat-api/files/api/agent/sanitize.py +22 -0
- package/recipes/backend/agent-chat-api/files/api/agent/schemas.py +26 -0
- package/recipes/backend/agent-chat-api/files/api/agent/settings.py +14 -0
- package/recipes/backend/agent-chat-api/files/api/agent/tracing.py +38 -0
- package/recipes/backend/agent-chat-api/files/api/app.py +67 -0
- package/recipes/backend/agent-chat-api/files/api/auth.py +73 -0
- package/recipes/backend/agent-chat-api/files/pytest.ini +5 -0
- package/recipes/backend/agent-chat-api/files/tests/test_agent_api.py +237 -0
- package/recipes/backend/agent-feedback/RECIPE.md +63 -0
- package/recipes/backend/agent-feedback/files/api/feedback/__init__.py +0 -0
- package/recipes/backend/agent-feedback/files/api/feedback/router.py +72 -0
- package/recipes/backend/agent-feedback/files/api/feedback/schemas.py +44 -0
- package/recipes/backend/agent-feedback/files/feedback/__init__.py +25 -0
- package/recipes/backend/agent-feedback/files/feedback/base.py +53 -0
- package/recipes/backend/agent-feedback/files/feedback/factory.py +30 -0
- package/recipes/backend/agent-feedback/files/feedback/in_memory.py +29 -0
- package/recipes/backend/agent-feedback/files/feedback/models.py +48 -0
- package/recipes/backend/agent-feedback/files/feedback/settings.py +17 -0
- package/recipes/backend/agent-feedback/files/feedback/sql.py +102 -0
- package/recipes/backend/agent-feedback/files/pytest.ini +5 -0
- package/recipes/backend/agent-feedback/files/tests/feedback_conformance.py +89 -0
- package/recipes/backend/agent-feedback/files/tests/test_feedback.py +63 -0
- package/recipes/backend/agent-feedback/files/tests/test_feedback_api.py +95 -0
- package/recipes/backend/auth-verifier/RECIPE.md +63 -0
- package/recipes/backend/auth-verifier/files/api/auth.py +73 -0
- package/recipes/backend/auth-verifier/files/auth/__init__.py +23 -0
- package/recipes/backend/auth-verifier/files/auth/factory.py +28 -0
- package/recipes/backend/auth-verifier/files/auth/jwt_verifier.py +101 -0
- package/recipes/backend/auth-verifier/files/auth/models.py +29 -0
- package/recipes/backend/auth-verifier/files/auth/settings.py +45 -0
- package/recipes/backend/auth-verifier/files/auth/supabase.py +80 -0
- package/recipes/backend/auth-verifier/files/pytest.ini +5 -0
- package/recipes/backend/auth-verifier/files/tests/__init__.py +0 -0
- package/recipes/backend/auth-verifier/files/tests/test_auth.py +229 -0
- package/recipes/backend/conversation-history/RECIPE.md +49 -0
- package/recipes/backend/conversation-history/files/api/conversations/__init__.py +0 -0
- package/recipes/backend/conversation-history/files/api/conversations/router.py +55 -0
- package/recipes/backend/conversation-history/files/api/conversations/schemas.py +57 -0
- package/recipes/backend/conversation-history/files/pytest.ini +5 -0
- package/recipes/backend/conversation-history/files/tests/test_conversations_api.py +127 -0
- package/recipes/backend/fastapi-base/RECIPE.md +57 -0
- package/recipes/backend/fastapi-base/files/api/app.py +37 -0
- package/recipes/backend/fastapi-base/files/api/base.py +54 -0
- package/recipes/backend/fastapi-base/files/api/errors.py +31 -0
- package/recipes/backend/fastapi-base/files/api/health.py +19 -0
- package/recipes/backend/fastapi-base/files/api/logging_setup.py +26 -0
- package/recipes/backend/fastapi-base/files/api/request_id.py +62 -0
- package/recipes/backend/fastapi-base/files/api/settings.py +32 -0
- package/recipes/backend/fastapi-base/files/pytest.ini +5 -0
- package/recipes/backend/fastapi-base/files/tests/__init__.py +0 -0
- package/recipes/backend/fastapi-base/files/tests/test_api_base.py +136 -0
- package/recipes/backend/observability/RECIPE.md +68 -0
- package/recipes/backend/observability/files/observability/__init__.py +34 -0
- package/recipes/backend/observability/files/observability/factory.py +73 -0
- package/recipes/backend/observability/files/observability/langfuse_tracer.py +29 -0
- package/recipes/backend/observability/files/observability/langsmith_tracer.py +23 -0
- package/recipes/backend/observability/files/observability/models.py +90 -0
- package/recipes/backend/observability/files/observability/opik_tracer.py +30 -0
- package/recipes/backend/observability/files/observability/settings.py +58 -0
- package/recipes/backend/observability/files/observability/tracer.py +142 -0
- package/recipes/backend/observability/files/observability/usage.py +61 -0
- package/recipes/backend/observability/files/pytest.ini +5 -0
- package/recipes/backend/observability/files/tests/__init__.py +0 -0
- package/recipes/backend/observability/files/tests/test_observability.py +219 -0
- package/recipes/backend/project-settings/RECIPE.md +40 -0
- package/recipes/backend/project-settings/files/.env.example +7 -0
- package/recipes/backend/project-settings/files/core/__init__.py +0 -0
- package/recipes/backend/project-settings/files/core/config.py +41 -0
- package/recipes/backend/project-settings/files/pytest.ini +3 -0
- package/recipes/backend/project-settings/files/tests/__init__.py +0 -0
- package/recipes/backend/project-settings/files/tests/test_settings.py +44 -0
- package/recipes/backend/rag-retriever/RECIPE.md +79 -0
- package/recipes/backend/rag-retriever/files/pytest.ini +5 -0
- package/recipes/backend/rag-retriever/files/rag/__init__.py +53 -0
- package/recipes/backend/rag-retriever/files/rag/base.py +106 -0
- package/recipes/backend/rag-retriever/files/rag/chunking.py +84 -0
- package/recipes/backend/rag-retriever/files/rag/document_search.py +60 -0
- package/recipes/backend/rag-retriever/files/rag/embeddings.py +91 -0
- package/recipes/backend/rag-retriever/files/rag/factory.py +82 -0
- package/recipes/backend/rag-retriever/files/rag/in_memory.py +52 -0
- package/recipes/backend/rag-retriever/files/rag/models.py +107 -0
- package/recipes/backend/rag-retriever/files/rag/pgvector.py +138 -0
- package/recipes/backend/rag-retriever/files/rag/qdrant.py +96 -0
- package/recipes/backend/rag-retriever/files/rag/settings.py +48 -0
- package/recipes/backend/rag-retriever/files/tests/__init__.py +0 -0
- package/recipes/backend/rag-retriever/files/tests/rag_conformance.py +95 -0
- package/recipes/backend/rag-retriever/files/tests/test_rag.py +270 -0
- package/recipes/backend/rate-limit-quota/RECIPE.md +77 -0
- package/recipes/backend/rate-limit-quota/files/api/agent/guards.py +62 -0
- package/recipes/backend/rate-limit-quota/files/api/limits/__init__.py +0 -0
- package/recipes/backend/rate-limit-quota/files/api/limits/router.py +38 -0
- package/recipes/backend/rate-limit-quota/files/limits/__init__.py +43 -0
- package/recipes/backend/rate-limit-quota/files/limits/base.py +161 -0
- package/recipes/backend/rate-limit-quota/files/limits/factory.py +69 -0
- package/recipes/backend/rate-limit-quota/files/limits/in_memory.py +36 -0
- package/recipes/backend/rate-limit-quota/files/limits/models.py +108 -0
- package/recipes/backend/rate-limit-quota/files/limits/settings.py +32 -0
- package/recipes/backend/rate-limit-quota/files/limits/sql.py +94 -0
- package/recipes/backend/rate-limit-quota/files/pytest.ini +5 -0
- package/recipes/backend/rate-limit-quota/files/tests/limits_conformance.py +146 -0
- package/recipes/backend/rate-limit-quota/files/tests/test_limits.py +167 -0
- package/recipes/backend/rate-limit-quota/files/tests/test_limits_api.py +100 -0
- package/recipes/backend/voice-providers/RECIPE.md +73 -0
- package/recipes/backend/voice-providers/files/api/__init__.py +0 -0
- package/recipes/backend/voice-providers/files/api/voice/__init__.py +0 -0
- package/recipes/backend/voice-providers/files/api/voice/router.py +113 -0
- package/recipes/backend/voice-providers/files/pytest.ini +5 -0
- package/recipes/backend/voice-providers/files/tests/__init__.py +0 -0
- package/recipes/backend/voice-providers/files/tests/fake_openai.py +44 -0
- package/recipes/backend/voice-providers/files/tests/test_voice.py +164 -0
- package/recipes/backend/voice-providers/files/tests/test_voice_api.py +106 -0
- package/recipes/backend/voice-providers/files/tests/voice_conformance.py +80 -0
- package/recipes/backend/voice-providers/files/voice/__init__.py +29 -0
- package/recipes/backend/voice-providers/files/voice/base.py +116 -0
- package/recipes/backend/voice-providers/files/voice/factory.py +48 -0
- package/recipes/backend/voice-providers/files/voice/fake.py +51 -0
- package/recipes/backend/voice-providers/files/voice/models.py +85 -0
- package/recipes/backend/voice-providers/files/voice/openai_provider.py +116 -0
- package/recipes/backend/voice-providers/files/voice/settings.py +48 -0
- package/recipes/frontend/.gitkeep +0 -0
- package/recipes/frontend/playwright-e2e/RECIPE.md +48 -0
- package/recipes/frontend/playwright-e2e/files/.github/workflows/frontend.yml +35 -0
- package/recipes/frontend/playwright-e2e/files/e2e/helpers.ts +25 -0
- package/recipes/frontend/playwright-e2e/files/e2e/home.spec.ts +10 -0
- package/recipes/frontend/playwright-e2e/files/e2e/login.spec.ts +26 -0
- package/recipes/frontend/playwright-e2e/files/e2e/navigation.spec.ts +27 -0
- package/recipes/frontend/playwright-e2e/files/playwright.config.ts +35 -0
- package/recipes/frontend/react-agent-chat/RECIPE.md +69 -0
- package/recipes/frontend/react-agent-chat/files/src/features/chat/chat-api.ts +27 -0
- package/recipes/frontend/react-agent-chat/files/src/features/chat/chat.css +18 -0
- package/recipes/frontend/react-agent-chat/files/src/features/chat/chat.test.tsx +139 -0
- package/recipes/frontend/react-agent-chat/files/src/features/chat/components/ChatView.tsx +22 -0
- package/recipes/frontend/react-agent-chat/files/src/features/chat/components/Composer.tsx +40 -0
- package/recipes/frontend/react-agent-chat/files/src/features/chat/components/Markdown.tsx +20 -0
- package/recipes/frontend/react-agent-chat/files/src/features/chat/components/MessageList.tsx +42 -0
- package/recipes/frontend/react-agent-chat/files/src/features/chat/events.ts +42 -0
- package/recipes/frontend/react-agent-chat/files/src/features/chat/fake-chat-api.ts +44 -0
- package/recipes/frontend/react-agent-chat/files/src/features/chat/index.ts +6 -0
- package/recipes/frontend/react-agent-chat/files/src/features/chat/sse-parser.test.ts +97 -0
- package/recipes/frontend/react-agent-chat/files/src/features/chat/sse-parser.ts +85 -0
- package/recipes/frontend/react-agent-chat/files/src/features/chat/use-chat.ts +136 -0
- package/recipes/frontend/react-app-router/RECIPE.md +58 -0
- package/recipes/frontend/react-app-router/files/src/App.test.tsx +54 -0
- package/recipes/frontend/react-app-router/files/src/App.tsx +14 -0
- package/recipes/frontend/react-app-router/files/src/router/ErrorScreen.tsx +21 -0
- package/recipes/frontend/react-app-router/files/src/router/Layout.tsx +28 -0
- package/recipes/frontend/react-app-router/files/src/router/NotFoundScreen.tsx +12 -0
- package/recipes/frontend/react-app-router/files/src/router/index.ts +1 -0
- package/recipes/frontend/react-app-router/files/src/router/router.css +29 -0
- package/recipes/frontend/react-app-router/files/src/router/router.test.tsx +65 -0
- package/recipes/frontend/react-app-router/files/src/router/routes.tsx +59 -0
- package/recipes/frontend/react-app-router/files/src/screens/SettingsScreen.tsx +10 -0
- package/recipes/frontend/react-supabase-auth/RECIPE.md +77 -0
- package/recipes/frontend/react-supabase-auth/files/src/auth/LoginScreen.tsx +64 -0
- package/recipes/frontend/react-supabase-auth/files/src/auth/SignOutButton.tsx +12 -0
- package/recipes/frontend/react-supabase-auth/files/src/auth/auth.css +33 -0
- package/recipes/frontend/react-supabase-auth/files/src/auth/auth.test.ts +149 -0
- package/recipes/frontend/react-supabase-auth/files/src/auth/auth.ts +59 -0
- package/recipes/frontend/react-supabase-auth/files/src/auth/fake-auth.ts +87 -0
- package/recipes/frontend/react-supabase-auth/files/src/auth/fake-gotrue.ts +85 -0
- package/recipes/frontend/react-supabase-auth/files/src/auth/index.ts +7 -0
- package/recipes/frontend/react-supabase-auth/files/src/auth/make-auth.ts +20 -0
- package/recipes/frontend/react-supabase-auth/files/src/auth/session-context.tsx +35 -0
- package/recipes/frontend/react-supabase-auth/files/src/auth/session-store.ts +63 -0
- package/recipes/frontend/react-supabase-auth/files/src/auth/session.test.tsx +56 -0
- package/recipes/frontend/react-supabase-auth/files/src/auth/settings.ts +30 -0
- package/recipes/frontend/react-supabase-auth/files/src/auth/supabase-auth.ts +85 -0
- package/recipes/frontend/vite-react-base/RECIPE.md +69 -0
- package/recipes/frontend/vite-react-base/files/.env +6 -0
- package/recipes/frontend/vite-react-base/files/.env.fake +2 -0
- package/recipes/frontend/vite-react-base/files/index.html +12 -0
- package/recipes/frontend/vite-react-base/files/package.json +30 -0
- package/recipes/frontend/vite-react-base/files/src/App.test.tsx +49 -0
- package/recipes/frontend/vite-react-base/files/src/App.tsx +13 -0
- package/recipes/frontend/vite-react-base/files/src/api/api.ts +37 -0
- package/recipes/frontend/vite-react-base/files/src/api/fake/fake-api.ts +29 -0
- package/recipes/frontend/vite-react-base/files/src/api/http-api.ts +16 -0
- package/recipes/frontend/vite-react-base/files/src/api/http-client.test.ts +84 -0
- package/recipes/frontend/vite-react-base/files/src/api/http-client.ts +94 -0
- package/recipes/frontend/vite-react-base/files/src/api/make-api.ts +30 -0
- package/recipes/frontend/vite-react-base/files/src/api/types.ts +7 -0
- package/recipes/frontend/vite-react-base/files/src/app-context.tsx +24 -0
- package/recipes/frontend/vite-react-base/files/src/auth/token-provider.ts +27 -0
- package/recipes/frontend/vite-react-base/files/src/config.ts +18 -0
- package/recipes/frontend/vite-react-base/files/src/hooks/use-load.ts +46 -0
- package/recipes/frontend/vite-react-base/files/src/main.tsx +27 -0
- package/recipes/frontend/vite-react-base/files/src/screens/HomeScreen.tsx +28 -0
- package/recipes/frontend/vite-react-base/files/src/styles/global.css +25 -0
- package/recipes/frontend/vite-react-base/files/src/styles/tokens.css +33 -0
- package/recipes/frontend/vite-react-base/files/src/styles/tokens.test.ts +45 -0
- package/recipes/frontend/vite-react-base/files/src/test-setup.ts +8 -0
- package/recipes/frontend/vite-react-base/files/src/vite-env.d.ts +11 -0
- package/recipes/frontend/vite-react-base/files/tsconfig.json +18 -0
- package/recipes/frontend/vite-react-base/files/vite.config.ts +19 -0
- 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,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,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,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)
|