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