@damiangilgonzalez/copypasta 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (255) hide show
  1. package/README.md +227 -2
  2. package/catalog.yaml +140 -0
  3. package/cli/copypasta.js +4 -0
  4. package/cli/lib/catalog.js +131 -0
  5. package/cli/lib/commands.js +162 -0
  6. package/cli/lib/index.js +4 -0
  7. package/cli/lib/main.js +130 -0
  8. package/package.json +38 -4
  9. package/recipes/agents/agent-memory/RECIPE.md +75 -0
  10. package/recipes/agents/agent-memory/files/agentic/memory/__init__.py +25 -0
  11. package/recipes/agents/agent-memory/files/agentic/memory/base.py +101 -0
  12. package/recipes/agents/agent-memory/files/agentic/memory/factory.py +33 -0
  13. package/recipes/agents/agent-memory/files/agentic/memory/in_memory.py +59 -0
  14. package/recipes/agents/agent-memory/files/agentic/memory/models.py +66 -0
  15. package/recipes/agents/agent-memory/files/agentic/memory/settings.py +24 -0
  16. package/recipes/agents/agent-memory/files/agentic/memory/sql.py +177 -0
  17. package/recipes/agents/agent-memory/files/pytest.ini +5 -0
  18. package/recipes/agents/agent-memory/files/tests/__init__.py +0 -0
  19. package/recipes/agents/agent-memory/files/tests/memory_conformance.py +158 -0
  20. package/recipes/agents/agent-memory/files/tests/test_memory.py +74 -0
  21. package/recipes/agents/langchain-agent/RECIPE.md +101 -0
  22. package/recipes/agents/langchain-agent/files/agentic/__init__.py +10 -0
  23. package/recipes/agents/langchain-agent/files/agentic/agents/__init__.py +13 -0
  24. package/recipes/agents/langchain-agent/files/agentic/agents/agents.py +43 -0
  25. package/recipes/agents/langchain-agent/files/agentic/agents/base_agent.py +126 -0
  26. package/recipes/agents/langchain-agent/files/agentic/agents/models.py +46 -0
  27. package/recipes/agents/langchain-agent/files/agentic/context.py +21 -0
  28. package/recipes/agents/langchain-agent/files/agentic/llm/__init__.py +5 -0
  29. package/recipes/agents/langchain-agent/files/agentic/llm/models.py +45 -0
  30. package/recipes/agents/langchain-agent/files/agentic/llm/provider.py +78 -0
  31. package/recipes/agents/langchain-agent/files/agentic/llm/settings.py +62 -0
  32. package/recipes/agents/langchain-agent/files/agentic/middleware/__init__.py +3 -0
  33. package/recipes/agents/langchain-agent/files/agentic/middleware/language.py +28 -0
  34. package/recipes/agents/langchain-agent/files/agentic/prompts/__init__.py +3 -0
  35. package/recipes/agents/langchain-agent/files/agentic/prompts/assistant.en.yaml +15 -0
  36. package/recipes/agents/langchain-agent/files/agentic/prompts/assistant.es.yaml +15 -0
  37. package/recipes/agents/langchain-agent/files/agentic/prompts/loader.py +69 -0
  38. package/recipes/agents/langchain-agent/files/agentic/tools/__init__.py +25 -0
  39. package/recipes/agents/langchain-agent/files/agentic/tools/base_tool.py +62 -0
  40. package/recipes/agents/langchain-agent/files/agentic/tools/search_documents.py +42 -0
  41. package/recipes/agents/langchain-agent/files/pytest.ini +5 -0
  42. package/recipes/agents/langchain-agent/files/tests/__init__.py +0 -0
  43. package/recipes/agents/langchain-agent/files/tests/fakes.py +30 -0
  44. package/recipes/agents/langchain-agent/files/tests/test_agents.py +151 -0
  45. package/recipes/agents/langgraph-graph/RECIPE.md +63 -0
  46. package/recipes/agents/langgraph-graph/files/agentic/conversation.py +73 -0
  47. package/recipes/agents/langgraph-graph/files/agentic/graph/__init__.py +17 -0
  48. package/recipes/agents/langgraph-graph/files/agentic/graph/builder.py +37 -0
  49. package/recipes/agents/langgraph-graph/files/agentic/graph/edges.py +8 -0
  50. package/recipes/agents/langgraph-graph/files/agentic/graph/event_processor.py +48 -0
  51. package/recipes/agents/langgraph-graph/files/agentic/graph/events.py +30 -0
  52. package/recipes/agents/langgraph-graph/files/agentic/graph/graph.py +60 -0
  53. package/recipes/agents/langgraph-graph/files/agentic/graph/nodes.py +63 -0
  54. package/recipes/agents/langgraph-graph/files/agentic/graph/state.py +31 -0
  55. package/recipes/agents/langgraph-graph/files/agentic/registry.py +85 -0
  56. package/recipes/agents/langgraph-graph/files/tests/test_graph.py +145 -0
  57. package/recipes/backend/.gitkeep +0 -0
  58. package/recipes/backend/agent-chat-api/RECIPE.md +69 -0
  59. package/recipes/backend/agent-chat-api/files/api/agent/guards.py +35 -0
  60. package/recipes/backend/agent-chat-api/files/api/agent/router.py +86 -0
  61. package/recipes/backend/agent-chat-api/files/api/agent/sanitize.py +22 -0
  62. package/recipes/backend/agent-chat-api/files/api/agent/schemas.py +26 -0
  63. package/recipes/backend/agent-chat-api/files/api/agent/settings.py +14 -0
  64. package/recipes/backend/agent-chat-api/files/api/agent/tracing.py +38 -0
  65. package/recipes/backend/agent-chat-api/files/api/app.py +67 -0
  66. package/recipes/backend/agent-chat-api/files/api/auth.py +73 -0
  67. package/recipes/backend/agent-chat-api/files/pytest.ini +5 -0
  68. package/recipes/backend/agent-chat-api/files/tests/test_agent_api.py +237 -0
  69. package/recipes/backend/agent-feedback/RECIPE.md +63 -0
  70. package/recipes/backend/agent-feedback/files/api/feedback/__init__.py +0 -0
  71. package/recipes/backend/agent-feedback/files/api/feedback/router.py +72 -0
  72. package/recipes/backend/agent-feedback/files/api/feedback/schemas.py +44 -0
  73. package/recipes/backend/agent-feedback/files/feedback/__init__.py +25 -0
  74. package/recipes/backend/agent-feedback/files/feedback/base.py +53 -0
  75. package/recipes/backend/agent-feedback/files/feedback/factory.py +30 -0
  76. package/recipes/backend/agent-feedback/files/feedback/in_memory.py +29 -0
  77. package/recipes/backend/agent-feedback/files/feedback/models.py +48 -0
  78. package/recipes/backend/agent-feedback/files/feedback/settings.py +17 -0
  79. package/recipes/backend/agent-feedback/files/feedback/sql.py +102 -0
  80. package/recipes/backend/agent-feedback/files/pytest.ini +5 -0
  81. package/recipes/backend/agent-feedback/files/tests/feedback_conformance.py +89 -0
  82. package/recipes/backend/agent-feedback/files/tests/test_feedback.py +63 -0
  83. package/recipes/backend/agent-feedback/files/tests/test_feedback_api.py +95 -0
  84. package/recipes/backend/auth-verifier/RECIPE.md +63 -0
  85. package/recipes/backend/auth-verifier/files/api/auth.py +73 -0
  86. package/recipes/backend/auth-verifier/files/auth/__init__.py +23 -0
  87. package/recipes/backend/auth-verifier/files/auth/factory.py +28 -0
  88. package/recipes/backend/auth-verifier/files/auth/jwt_verifier.py +101 -0
  89. package/recipes/backend/auth-verifier/files/auth/models.py +29 -0
  90. package/recipes/backend/auth-verifier/files/auth/settings.py +45 -0
  91. package/recipes/backend/auth-verifier/files/auth/supabase.py +80 -0
  92. package/recipes/backend/auth-verifier/files/pytest.ini +5 -0
  93. package/recipes/backend/auth-verifier/files/tests/__init__.py +0 -0
  94. package/recipes/backend/auth-verifier/files/tests/test_auth.py +229 -0
  95. package/recipes/backend/conversation-history/RECIPE.md +49 -0
  96. package/recipes/backend/conversation-history/files/api/conversations/__init__.py +0 -0
  97. package/recipes/backend/conversation-history/files/api/conversations/router.py +55 -0
  98. package/recipes/backend/conversation-history/files/api/conversations/schemas.py +57 -0
  99. package/recipes/backend/conversation-history/files/pytest.ini +5 -0
  100. package/recipes/backend/conversation-history/files/tests/test_conversations_api.py +127 -0
  101. package/recipes/backend/fastapi-base/RECIPE.md +57 -0
  102. package/recipes/backend/fastapi-base/files/api/app.py +37 -0
  103. package/recipes/backend/fastapi-base/files/api/base.py +54 -0
  104. package/recipes/backend/fastapi-base/files/api/errors.py +31 -0
  105. package/recipes/backend/fastapi-base/files/api/health.py +19 -0
  106. package/recipes/backend/fastapi-base/files/api/logging_setup.py +26 -0
  107. package/recipes/backend/fastapi-base/files/api/request_id.py +62 -0
  108. package/recipes/backend/fastapi-base/files/api/settings.py +32 -0
  109. package/recipes/backend/fastapi-base/files/pytest.ini +5 -0
  110. package/recipes/backend/fastapi-base/files/tests/__init__.py +0 -0
  111. package/recipes/backend/fastapi-base/files/tests/test_api_base.py +136 -0
  112. package/recipes/backend/observability/RECIPE.md +68 -0
  113. package/recipes/backend/observability/files/observability/__init__.py +34 -0
  114. package/recipes/backend/observability/files/observability/factory.py +73 -0
  115. package/recipes/backend/observability/files/observability/langfuse_tracer.py +29 -0
  116. package/recipes/backend/observability/files/observability/langsmith_tracer.py +23 -0
  117. package/recipes/backend/observability/files/observability/models.py +90 -0
  118. package/recipes/backend/observability/files/observability/opik_tracer.py +30 -0
  119. package/recipes/backend/observability/files/observability/settings.py +58 -0
  120. package/recipes/backend/observability/files/observability/tracer.py +142 -0
  121. package/recipes/backend/observability/files/observability/usage.py +61 -0
  122. package/recipes/backend/observability/files/pytest.ini +5 -0
  123. package/recipes/backend/observability/files/tests/__init__.py +0 -0
  124. package/recipes/backend/observability/files/tests/test_observability.py +219 -0
  125. package/recipes/backend/project-settings/RECIPE.md +40 -0
  126. package/recipes/backend/project-settings/files/.env.example +7 -0
  127. package/recipes/backend/project-settings/files/core/__init__.py +0 -0
  128. package/recipes/backend/project-settings/files/core/config.py +41 -0
  129. package/recipes/backend/project-settings/files/pytest.ini +3 -0
  130. package/recipes/backend/project-settings/files/tests/__init__.py +0 -0
  131. package/recipes/backend/project-settings/files/tests/test_settings.py +44 -0
  132. package/recipes/backend/rag-retriever/RECIPE.md +79 -0
  133. package/recipes/backend/rag-retriever/files/pytest.ini +5 -0
  134. package/recipes/backend/rag-retriever/files/rag/__init__.py +53 -0
  135. package/recipes/backend/rag-retriever/files/rag/base.py +106 -0
  136. package/recipes/backend/rag-retriever/files/rag/chunking.py +84 -0
  137. package/recipes/backend/rag-retriever/files/rag/document_search.py +60 -0
  138. package/recipes/backend/rag-retriever/files/rag/embeddings.py +91 -0
  139. package/recipes/backend/rag-retriever/files/rag/factory.py +82 -0
  140. package/recipes/backend/rag-retriever/files/rag/in_memory.py +52 -0
  141. package/recipes/backend/rag-retriever/files/rag/models.py +107 -0
  142. package/recipes/backend/rag-retriever/files/rag/pgvector.py +138 -0
  143. package/recipes/backend/rag-retriever/files/rag/qdrant.py +96 -0
  144. package/recipes/backend/rag-retriever/files/rag/settings.py +48 -0
  145. package/recipes/backend/rag-retriever/files/tests/__init__.py +0 -0
  146. package/recipes/backend/rag-retriever/files/tests/rag_conformance.py +95 -0
  147. package/recipes/backend/rag-retriever/files/tests/test_rag.py +270 -0
  148. package/recipes/backend/rate-limit-quota/RECIPE.md +77 -0
  149. package/recipes/backend/rate-limit-quota/files/api/agent/guards.py +62 -0
  150. package/recipes/backend/rate-limit-quota/files/api/limits/__init__.py +0 -0
  151. package/recipes/backend/rate-limit-quota/files/api/limits/router.py +38 -0
  152. package/recipes/backend/rate-limit-quota/files/limits/__init__.py +43 -0
  153. package/recipes/backend/rate-limit-quota/files/limits/base.py +161 -0
  154. package/recipes/backend/rate-limit-quota/files/limits/factory.py +69 -0
  155. package/recipes/backend/rate-limit-quota/files/limits/in_memory.py +36 -0
  156. package/recipes/backend/rate-limit-quota/files/limits/models.py +108 -0
  157. package/recipes/backend/rate-limit-quota/files/limits/settings.py +32 -0
  158. package/recipes/backend/rate-limit-quota/files/limits/sql.py +94 -0
  159. package/recipes/backend/rate-limit-quota/files/pytest.ini +5 -0
  160. package/recipes/backend/rate-limit-quota/files/tests/limits_conformance.py +146 -0
  161. package/recipes/backend/rate-limit-quota/files/tests/test_limits.py +167 -0
  162. package/recipes/backend/rate-limit-quota/files/tests/test_limits_api.py +100 -0
  163. package/recipes/backend/voice-providers/RECIPE.md +73 -0
  164. package/recipes/backend/voice-providers/files/api/__init__.py +0 -0
  165. package/recipes/backend/voice-providers/files/api/voice/__init__.py +0 -0
  166. package/recipes/backend/voice-providers/files/api/voice/router.py +113 -0
  167. package/recipes/backend/voice-providers/files/pytest.ini +5 -0
  168. package/recipes/backend/voice-providers/files/tests/__init__.py +0 -0
  169. package/recipes/backend/voice-providers/files/tests/fake_openai.py +44 -0
  170. package/recipes/backend/voice-providers/files/tests/test_voice.py +164 -0
  171. package/recipes/backend/voice-providers/files/tests/test_voice_api.py +106 -0
  172. package/recipes/backend/voice-providers/files/tests/voice_conformance.py +80 -0
  173. package/recipes/backend/voice-providers/files/voice/__init__.py +29 -0
  174. package/recipes/backend/voice-providers/files/voice/base.py +116 -0
  175. package/recipes/backend/voice-providers/files/voice/factory.py +48 -0
  176. package/recipes/backend/voice-providers/files/voice/fake.py +51 -0
  177. package/recipes/backend/voice-providers/files/voice/models.py +85 -0
  178. package/recipes/backend/voice-providers/files/voice/openai_provider.py +116 -0
  179. package/recipes/backend/voice-providers/files/voice/settings.py +48 -0
  180. package/recipes/frontend/.gitkeep +0 -0
  181. package/recipes/frontend/playwright-e2e/RECIPE.md +48 -0
  182. package/recipes/frontend/playwright-e2e/files/.github/workflows/frontend.yml +35 -0
  183. package/recipes/frontend/playwright-e2e/files/e2e/helpers.ts +25 -0
  184. package/recipes/frontend/playwright-e2e/files/e2e/home.spec.ts +10 -0
  185. package/recipes/frontend/playwright-e2e/files/e2e/login.spec.ts +26 -0
  186. package/recipes/frontend/playwright-e2e/files/e2e/navigation.spec.ts +27 -0
  187. package/recipes/frontend/playwright-e2e/files/playwright.config.ts +35 -0
  188. package/recipes/frontend/react-agent-chat/RECIPE.md +69 -0
  189. package/recipes/frontend/react-agent-chat/files/src/features/chat/chat-api.ts +27 -0
  190. package/recipes/frontend/react-agent-chat/files/src/features/chat/chat.css +18 -0
  191. package/recipes/frontend/react-agent-chat/files/src/features/chat/chat.test.tsx +139 -0
  192. package/recipes/frontend/react-agent-chat/files/src/features/chat/components/ChatView.tsx +22 -0
  193. package/recipes/frontend/react-agent-chat/files/src/features/chat/components/Composer.tsx +40 -0
  194. package/recipes/frontend/react-agent-chat/files/src/features/chat/components/Markdown.tsx +20 -0
  195. package/recipes/frontend/react-agent-chat/files/src/features/chat/components/MessageList.tsx +42 -0
  196. package/recipes/frontend/react-agent-chat/files/src/features/chat/events.ts +42 -0
  197. package/recipes/frontend/react-agent-chat/files/src/features/chat/fake-chat-api.ts +44 -0
  198. package/recipes/frontend/react-agent-chat/files/src/features/chat/index.ts +6 -0
  199. package/recipes/frontend/react-agent-chat/files/src/features/chat/sse-parser.test.ts +97 -0
  200. package/recipes/frontend/react-agent-chat/files/src/features/chat/sse-parser.ts +85 -0
  201. package/recipes/frontend/react-agent-chat/files/src/features/chat/use-chat.ts +136 -0
  202. package/recipes/frontend/react-app-router/RECIPE.md +58 -0
  203. package/recipes/frontend/react-app-router/files/src/App.test.tsx +54 -0
  204. package/recipes/frontend/react-app-router/files/src/App.tsx +14 -0
  205. package/recipes/frontend/react-app-router/files/src/router/ErrorScreen.tsx +21 -0
  206. package/recipes/frontend/react-app-router/files/src/router/Layout.tsx +28 -0
  207. package/recipes/frontend/react-app-router/files/src/router/NotFoundScreen.tsx +12 -0
  208. package/recipes/frontend/react-app-router/files/src/router/index.ts +1 -0
  209. package/recipes/frontend/react-app-router/files/src/router/router.css +29 -0
  210. package/recipes/frontend/react-app-router/files/src/router/router.test.tsx +65 -0
  211. package/recipes/frontend/react-app-router/files/src/router/routes.tsx +59 -0
  212. package/recipes/frontend/react-app-router/files/src/screens/SettingsScreen.tsx +10 -0
  213. package/recipes/frontend/react-supabase-auth/RECIPE.md +77 -0
  214. package/recipes/frontend/react-supabase-auth/files/src/auth/LoginScreen.tsx +64 -0
  215. package/recipes/frontend/react-supabase-auth/files/src/auth/SignOutButton.tsx +12 -0
  216. package/recipes/frontend/react-supabase-auth/files/src/auth/auth.css +33 -0
  217. package/recipes/frontend/react-supabase-auth/files/src/auth/auth.test.ts +149 -0
  218. package/recipes/frontend/react-supabase-auth/files/src/auth/auth.ts +59 -0
  219. package/recipes/frontend/react-supabase-auth/files/src/auth/fake-auth.ts +87 -0
  220. package/recipes/frontend/react-supabase-auth/files/src/auth/fake-gotrue.ts +85 -0
  221. package/recipes/frontend/react-supabase-auth/files/src/auth/index.ts +7 -0
  222. package/recipes/frontend/react-supabase-auth/files/src/auth/make-auth.ts +20 -0
  223. package/recipes/frontend/react-supabase-auth/files/src/auth/session-context.tsx +35 -0
  224. package/recipes/frontend/react-supabase-auth/files/src/auth/session-store.ts +63 -0
  225. package/recipes/frontend/react-supabase-auth/files/src/auth/session.test.tsx +56 -0
  226. package/recipes/frontend/react-supabase-auth/files/src/auth/settings.ts +30 -0
  227. package/recipes/frontend/react-supabase-auth/files/src/auth/supabase-auth.ts +85 -0
  228. package/recipes/frontend/vite-react-base/RECIPE.md +69 -0
  229. package/recipes/frontend/vite-react-base/files/.env +6 -0
  230. package/recipes/frontend/vite-react-base/files/.env.fake +2 -0
  231. package/recipes/frontend/vite-react-base/files/index.html +12 -0
  232. package/recipes/frontend/vite-react-base/files/package.json +30 -0
  233. package/recipes/frontend/vite-react-base/files/src/App.test.tsx +49 -0
  234. package/recipes/frontend/vite-react-base/files/src/App.tsx +13 -0
  235. package/recipes/frontend/vite-react-base/files/src/api/api.ts +37 -0
  236. package/recipes/frontend/vite-react-base/files/src/api/fake/fake-api.ts +29 -0
  237. package/recipes/frontend/vite-react-base/files/src/api/http-api.ts +16 -0
  238. package/recipes/frontend/vite-react-base/files/src/api/http-client.test.ts +84 -0
  239. package/recipes/frontend/vite-react-base/files/src/api/http-client.ts +94 -0
  240. package/recipes/frontend/vite-react-base/files/src/api/make-api.ts +30 -0
  241. package/recipes/frontend/vite-react-base/files/src/api/types.ts +7 -0
  242. package/recipes/frontend/vite-react-base/files/src/app-context.tsx +24 -0
  243. package/recipes/frontend/vite-react-base/files/src/auth/token-provider.ts +27 -0
  244. package/recipes/frontend/vite-react-base/files/src/config.ts +18 -0
  245. package/recipes/frontend/vite-react-base/files/src/hooks/use-load.ts +46 -0
  246. package/recipes/frontend/vite-react-base/files/src/main.tsx +27 -0
  247. package/recipes/frontend/vite-react-base/files/src/screens/HomeScreen.tsx +28 -0
  248. package/recipes/frontend/vite-react-base/files/src/styles/global.css +25 -0
  249. package/recipes/frontend/vite-react-base/files/src/styles/tokens.css +33 -0
  250. package/recipes/frontend/vite-react-base/files/src/styles/tokens.test.ts +45 -0
  251. package/recipes/frontend/vite-react-base/files/src/test-setup.ts +8 -0
  252. package/recipes/frontend/vite-react-base/files/src/vite-env.d.ts +11 -0
  253. package/recipes/frontend/vite-react-base/files/tsconfig.json +18 -0
  254. package/recipes/frontend/vite-react-base/files/vite.config.ts +19 -0
  255. package/unpacked-files.json +3 -0
@@ -0,0 +1,73 @@
1
+ """Who is calling: `CurrentUser` from a Bearer token.
2
+
3
+ The router never parses tokens itself. It asks the `TokenVerifier` stored in `app.state`, so the
4
+ provider (Supabase, own JWT, API key...) is chosen when the app is built, and tests use
5
+ `StaticTokenVerifier`. The `auth-verifier` recipe provides the real verifiers and their factory
6
+ (and ships this same file); until then, write one subclass here.
7
+ """
8
+
9
+ from abc import ABC, abstractmethod
10
+
11
+ from fastapi import Depends, HTTPException, Request, status
12
+ from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
13
+ from pydantic import BaseModel, ConfigDict, Field
14
+
15
+
16
+ class CurrentUser(BaseModel):
17
+ """The authenticated caller. `tenant_id` and `id` are the namespace of every conversation,
18
+ so they come from the token and never from the request body. Add what your guards need."""
19
+
20
+ model_config = ConfigDict(frozen=True)
21
+
22
+ id: str = Field(min_length=1)
23
+ tenant_id: str = Field(min_length=1)
24
+ language: str = Field(default="es", description="Fallback language when the request has none.")
25
+ email: str | None = None
26
+ role: str | None = Field(default=None, description="For 403 checks in `ensure_turn_allowed`, if you have roles.")
27
+
28
+
29
+ class InvalidToken(Exception):
30
+ """The token is missing, expired, forged or belongs to nobody. Reason only for the logs."""
31
+
32
+
33
+ class AuthUnavailable(Exception):
34
+ """The verifier could not decide (the identity provider did not answer). Not a 401: a 503."""
35
+
36
+
37
+ class TokenVerifier(ABC):
38
+ @abstractmethod
39
+ async def verify(self, token: str) -> CurrentUser:
40
+ """Return the caller, or raise `InvalidToken` (401) / `AuthUnavailable` (503)."""
41
+
42
+
43
+ class StaticTokenVerifier(TokenVerifier):
44
+ """A fixed `token -> user` table. For tests and local development only."""
45
+
46
+ def __init__(self, users: dict[str, CurrentUser]) -> None:
47
+ self._users = users
48
+
49
+ async def verify(self, token: str) -> CurrentUser:
50
+ try:
51
+ return self._users[token]
52
+ except KeyError:
53
+ raise InvalidToken("unknown token") from None
54
+
55
+
56
+ # auto_error=False: a missing header gets the same 401 as a bad token, with our own message.
57
+ _bearer = HTTPBearer(auto_error=False)
58
+
59
+
60
+ async def get_current_user(
61
+ request: Request, credentials: HTTPAuthorizationCredentials | None = Depends(_bearer)
62
+ ) -> CurrentUser:
63
+ verifier: TokenVerifier | None = getattr(request.app.state, "token_verifier", None)
64
+ if verifier is None:
65
+ raise RuntimeError("app.state.token_verifier is not set: build the app with a TokenVerifier")
66
+ if credentials is None:
67
+ raise HTTPException(status.HTTP_401_UNAUTHORIZED, "Not authenticated", {"WWW-Authenticate": "Bearer"})
68
+ try:
69
+ return await verifier.verify(credentials.credentials)
70
+ except InvalidToken:
71
+ raise HTTPException(status.HTTP_401_UNAUTHORIZED, "Invalid token", {"WWW-Authenticate": "Bearer"}) from None
72
+ except AuthUnavailable:
73
+ raise HTTPException(status.HTTP_503_SERVICE_UNAVAILABLE, "Authentication service unavailable") from None
@@ -0,0 +1,5 @@
1
+ [pytest]
2
+ asyncio_mode = auto
3
+ asyncio_default_fixture_loop_scope = function
4
+ pythonpath = .
5
+ testpaths = tests
@@ -0,0 +1,237 @@
1
+ """Chat endpoints over the real graph with fake LLMs. Needs langgraph-graph (and what it requires)
2
+ copied next to `api/`, plus tests/fakes.py from langchain-agent."""
3
+
4
+ import json
5
+ from collections.abc import AsyncIterator
6
+
7
+ import httpx
8
+ import pytest
9
+ from langchain_core.messages import AIMessage
10
+
11
+ from agentic.agents import AssistantAgent, ClassifierAgent
12
+ from agentic.memory import InMemoryMemory, MemoryKey
13
+ from agentic.registry import registry
14
+ from api.agent.guards import ensure_turn_allowed
15
+ from api.agent.settings import AgentApiSettings
16
+ from api.app import create_app
17
+ from api.auth import CurrentUser, StaticTokenVerifier
18
+ from fastapi import HTTPException
19
+
20
+ from .fakes import ScriptedChatModel, tool_call
21
+ from .test_graph import StreamingChatModel
22
+
23
+ ALICE = CurrentUser(id="user-1", tenant_id="tenant-1")
24
+ BOB = CurrentUser(id="user-2", tenant_id="tenant-2", language="en")
25
+ TOKENS = {"tok-alice": ALICE, "tok-bob": BOB}
26
+
27
+
28
+ def classifier_answering(category: str) -> ClassifierAgent:
29
+ args = {"category": category, "needs_search": False, "confidence": 0.9}
30
+ return ClassifierAgent(llm=ScriptedChatModel(responses=[tool_call("Classification", args, "c_router")]))
31
+
32
+
33
+ def make_app(memory: InMemoryMemory | None = None, **settings) -> tuple[object, InMemoryMemory]:
34
+ memory = memory or InMemoryMemory()
35
+ app = create_app(
36
+ settings=AgentApiSettings(**settings),
37
+ token_verifier=StaticTokenVerifier(TOKENS),
38
+ memory=memory,
39
+ document_search=None,
40
+ )
41
+ return app, memory
42
+
43
+
44
+ def client(app) -> httpx.AsyncClient:
45
+ return httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://test")
46
+
47
+
48
+ def auth(token: str = "tok-alice") -> dict[str, str]:
49
+ return {"Authorization": f"Bearer {token}"}
50
+
51
+
52
+ async def sse_events(response: httpx.Response) -> list[tuple[str, dict]]:
53
+ """Minimal SSE reader for tests: (event, parsed data) per block."""
54
+ events, event, data = [], None, []
55
+ async for line in response.aiter_lines():
56
+ if line.startswith("event:"):
57
+ event = line[6:].strip()
58
+ elif line.startswith("data:"):
59
+ data.append(line[5:].strip())
60
+ elif line == "" and event is not None:
61
+ events.append((event, json.loads("\n".join(data))))
62
+ event, data = None, []
63
+ return events
64
+
65
+
66
+ @pytest.fixture(autouse=True)
67
+ def answering_agents():
68
+ registry.reset()
69
+ registry.override(
70
+ classifier=classifier_answering("technical"),
71
+ assistant=AssistantAgent(llm=ScriptedChatModel(responses=[AIMessage("uno"), AIMessage("dos")]), tools=[]),
72
+ )
73
+ yield
74
+ registry.reset()
75
+
76
+
77
+ async def test_without_token_is_401_and_with_unknown_token_too():
78
+ app, _ = make_app()
79
+ async with client(app) as c:
80
+ assert (await c.post("/agent/chat", json={"question": "hola"})).status_code == 401
81
+ assert (await c.post("/agent/chat", json={"question": "hola"}, headers=auth("nope"))).status_code == 401
82
+
83
+
84
+ async def test_disabled_endpoint_is_404_even_without_token():
85
+ app, _ = make_app(agent_endpoint_enabled=False)
86
+ async with client(app) as c:
87
+ assert (await c.post("/agent/chat", json={"question": "hola"})).status_code == 404
88
+ assert (await c.post("/agent/stream", json={"question": "hola"}, headers=auth())).status_code == 404
89
+
90
+
91
+ async def test_blank_or_too_long_question_is_400():
92
+ app, _ = make_app(chat_max_question_length=10)
93
+ async with client(app) as c:
94
+ assert (await c.post("/agent/chat", json={"question": " <b> </b> "}, headers=auth())).status_code == 400
95
+ assert (await c.post("/agent/chat", json={"question": "x" * 11}, headers=auth())).status_code == 400
96
+ assert (await c.post("/agent/chat", json={"question": ""}, headers=auth())).status_code == 422
97
+
98
+
99
+ async def test_chat_answers_and_server_generates_the_conversation_id():
100
+ app, memory = make_app()
101
+ async with client(app) as c:
102
+ response = await c.post("/agent/chat", json={"question": "hola"}, headers=auth())
103
+
104
+ assert response.status_code == 200
105
+ body = response.json()
106
+ assert body["answer"] == "uno"
107
+ assert body["message_id"] # the persisted answer, votable
108
+ key = MemoryKey(tenant_id="tenant-1", user_id="user-1", conversation_id=body["conversation_id"])
109
+ assert [m.content for m in await memory.get_messages(key)] == ["hola", "uno"]
110
+
111
+
112
+ async def test_same_conversation_id_continues_the_thread_and_tenants_do_not_mix():
113
+ app, memory = make_app()
114
+ async with client(app) as c:
115
+ await c.post("/agent/chat", json={"question": "primera", "conversation_id": "conv-1"}, headers=auth())
116
+ second = await c.post("/agent/chat", json={"question": "segunda", "conversation_id": "conv-1"}, headers=auth())
117
+
118
+ assert second.json() == {"answer": "dos", "conversation_id": "conv-1", "message_id": second.json()["message_id"]}
119
+ alice = MemoryKey(tenant_id="tenant-1", user_id="user-1", conversation_id="conv-1")
120
+ assert [m.content for m in await memory.get_messages(alice)] == ["primera", "uno", "segunda", "dos"]
121
+ bob_same_id = MemoryKey(tenant_id="tenant-2", user_id="user-2", conversation_id="conv-1")
122
+ assert await memory.get_messages(bob_same_id) == []
123
+
124
+
125
+ async def test_turn_guard_can_refuse_before_anything_runs():
126
+ app, memory = make_app()
127
+
128
+ async def quota_exhausted() -> CurrentUser:
129
+ raise HTTPException(429, {"code": "ai_quota_daily_exhausted"})
130
+
131
+ app.dependency_overrides[ensure_turn_allowed] = quota_exhausted
132
+ async with client(app) as c:
133
+ response = await c.post("/agent/stream", json={"question": "hola"}, headers=auth())
134
+
135
+ assert response.status_code == 429
136
+ assert response.json()["detail"]["code"] == "ai_quota_daily_exhausted"
137
+ assert await memory.get_messages(MemoryKey(tenant_id="tenant-1", user_id="user-1", conversation_id="x")) == []
138
+
139
+
140
+ async def test_stream_sends_tokens_and_done_with_ids():
141
+ registry.override(assistant=AssistantAgent(llm=StreamingChatModel(messages=iter([AIMessage("hola que tal")])), tools=[]))
142
+ app, _ = make_app()
143
+ async with client(app) as c:
144
+ async with c.stream("POST", "/agent/stream", json={"question": "hola", "conversation_id": "conv-9"}, headers=auth()) as r:
145
+ assert r.status_code == 200
146
+ assert r.headers["content-type"].startswith("text/event-stream")
147
+ events = await sse_events(r)
148
+
149
+ names = [name for name, _ in events]
150
+ assert names[0] == "routing" and names[-1] == "done"
151
+ assert "".join(d["text"] for n, d in events if n == "token") == "hola que tal"
152
+ done = events[-1][1]
153
+ assert done["answer"] == "hola que tal" and done["conversation_id"] == "conv-9" and done["message_id"]
154
+
155
+
156
+ async def test_stream_failure_outside_the_graph_becomes_an_error_event_with_id_only():
157
+ class BrokenMemory(InMemoryMemory):
158
+ async def get_messages(self, key, turns=None): # type: ignore[override]
159
+ raise RuntimeError("db password is hunter2")
160
+
161
+ app, _ = make_app(memory=BrokenMemory())
162
+ async with client(app) as c:
163
+ async with c.stream("POST", "/agent/stream", json={"question": "hola"}, headers=auth()) as r:
164
+ assert r.status_code == 200
165
+ events = await sse_events(r)
166
+
167
+ assert [name for name, _ in events] == ["error"]
168
+ assert set(events[0][1]) == {"error_id"}
169
+ assert "hunter2" not in json.dumps(events)
170
+
171
+
172
+ async def test_language_comes_from_body_then_from_user():
173
+ seen: list[str] = []
174
+
175
+ class SpyAssistant(AssistantAgent):
176
+ async def process(self, question, *, context, history=(), config=None): # type: ignore[override]
177
+ seen.append(context.language)
178
+ return await super().process(question, context=context, history=history, config=config)
179
+
180
+ spy = SpyAssistant(llm=ScriptedChatModel(responses=[AIMessage("a"), AIMessage("b")]), tools=[])
181
+ for language in ("fr", "en"): # the registry keeps one assistant per language
182
+ registry.override(assistant=spy, language=language)
183
+ app, _ = make_app()
184
+ async with client(app) as c:
185
+ await c.post("/agent/chat", json={"question": "hi", "language": "fr"}, headers=auth("tok-bob"))
186
+ await c.post("/agent/chat", json={"question": "hi"}, headers=auth("tok-bob"))
187
+
188
+ assert seen == ["fr", "en"]
189
+
190
+
191
+ async def test_docs_hidden_by_default_and_health_and_request_id_come_from_fastapi_base():
192
+ app, _ = make_app()
193
+ async with client(app) as c:
194
+ assert (await c.get("/docs")).status_code == 404
195
+ assert (await c.get("/health")).json() == {"status": "ok"}
196
+ refused = await c.post("/agent/chat", json={"question": "hola"})
197
+ assert refused.status_code == 401 and refused.headers["x-request-id"]
198
+
199
+
200
+ class FakeTrace:
201
+ def __init__(self, calls: list, **run) -> None:
202
+ self.calls = calls
203
+ self.run = run
204
+ self.config = {"callbacks": [], "metadata": {"thread_id": run["thread_id"], "traced": True}}
205
+
206
+ def finish(self, error=None):
207
+ self.calls.append((self.run, type(error).__name__ if error else None))
208
+
209
+
210
+ class FakeTracer:
211
+ """What `observability` provides, duck-typed: begin_turn(...) -> trace with .config and .finish()."""
212
+
213
+ def __init__(self) -> None:
214
+ self.calls: list = []
215
+ self.flushed = False
216
+
217
+ def begin_turn(self, **run):
218
+ return FakeTrace(self.calls, **run)
219
+
220
+ async def flush(self):
221
+ self.flushed = True
222
+
223
+
224
+ async def test_turns_run_inside_the_tracer_when_the_app_has_one():
225
+ tracer = FakeTracer()
226
+ app = create_app(
227
+ settings=AgentApiSettings(), token_verifier=StaticTokenVerifier(TOKENS), memory=InMemoryMemory(),
228
+ document_search=None, tracer=tracer,
229
+ )
230
+ async with client(app) as c:
231
+ chat = await c.post("/agent/chat", json={"question": "hola", "conversation_id": "conv-9"}, headers=auth())
232
+ stream = await c.post("/agent/stream", json={"question": "hola", "conversation_id": "conv-9"}, headers=auth())
233
+ assert chat.status_code == 200 and stream.status_code == 200
234
+ assert [r["thread_id"] for r, _ in tracer.calls] == ["tenant-1:user-1:conv-9"] * 2
235
+ assert tracer.calls[0][0]["tenant_id"] == "tenant-1" and tracer.calls[0][0]["user_id"] == "user-1"
236
+ assert tracer.calls[0][0]["request_id"] == chat.headers["x-request-id"]
237
+ assert [e for _, e in tracer.calls] == [None, None]
@@ -0,0 +1,63 @@
1
+ # agent-feedback
2
+
3
+ ## Cuándo usarla
4
+
5
+ Para los **pulgares arriba y abajo** sobre las respuestas del agente: un voto por usuario y respuesta (volver a votar lo actualiza), con comentario opcional, deshacer y recuperar los votos de una conversación para pintar el estado al recargar. Cierra el ciclo con el `message_id` que ya devuelven `done`, `ChatResponse` y el historial.
6
+
7
+ **Requiere `agent-chat-api`** (usa su `get_current_user`, `get_memory`, `require_agent_enabled` y `create_app`). **Usa `project-settings`** (bloque `FeedbackSettings`). El núcleo `feedback/` no importa FastAPI ni el agente.
8
+
9
+ ## Qué incluye
10
+
11
+ ```
12
+ feedback/
13
+ models.py FeedbackBackend · Rating (+1 | -1) · FeedbackVote · Feedback (con fechas) · FeedbackResult
14
+ base.py FeedbackStore (ABC): vote (upsert) · get · list_for_conversation · remove; subclase: _save, get, list, remove
15
+ in_memory.py InMemoryFeedbackStore (tests y desarrollo)
16
+ sql.py SqlFeedbackStore + tabla agent_feedback (SQLAlchemy 2; UNIQUE tenant+user+message, CHECK rating)
17
+ settings.py bloque FeedbackSettings: FEEDBACK_BACKEND (obligatorio)
18
+ factory.py FeedbackFactory.create(settings, session_factory=...)
19
+ api/feedback/
20
+ router.py POST /agent/feedback · GET /agent/feedback?conversation_id= · DELETE /agent/feedback/{message_id}
21
+ schemas.py FeedbackRequest{conversation_id, message_id, rating, comment?} · FeedbackResponse (+ created_or_updated)
22
+ tests/
23
+ feedback_conformance.py lo que TODO backend debe cumplir (6 tests) y FakeClock
24
+ test_feedback.py conformidad en RAM y SQL, modelos, settings y factory (16 tests)
25
+ test_feedback_api.py guards, crear → actualizar, 404 único, deshacer (4 tests)
26
+ pytest.ini
27
+ ```
28
+
29
+ ## Decisiones
30
+
31
+ - **Un voto por (tenant, usuario, mensaje), upsert.** Votar otra vez cambia `rating` y `comment` y conserva `created_at`. La respuesta dice `created` o `updated`.
32
+ - **La propiedad se comprueba en la memoria, no en la tabla de votos.** El mensaje debe ser una respuesta del agente (`ai` con texto) dentro de una conversación del propio usuario; se lee con `Memory.get_history`. Por eso el voto lleva `conversation_id` además de `message_id` (con una tabla de mensajes propia bastaría el segundo; aquí la memoria es un contrato, no una tabla).
33
+ - **Un solo 404.** Mensaje inexistente, de otro usuario o tenant, humano, o una tool call: la misma respuesta, para no filtrar qué existe.
34
+ - **Mismos guards que el chat:** agente apagado → 404, sin token → 401. No pasa por el rate limit del turno: votar no gasta LLM.
35
+ - **Backend en settings** (`FEEDBACK_BACKEND=in_memory | sql`), sin valor por defecto, como las demás recetas. La tabla no lleva clave foránea a los mensajes porque la receta no conoce tus nombres de tabla; añádela en tu migración si quieres borrado en cascada.
36
+ - **`GET /agent/feedback?conversation_id=`** devuelve los votos del usuario en esa conversación para restaurar los pulgares al recargar. Es nuevo (en producción el estado vivía solo en el cliente); se añade porque sin él el historial de `conversation-history` llega sin votos.
37
+ - **`rating` como `Literal[-1, 1]`:** Pydantic rechaza cualquier otro valor con 422, no hace falta un 400 manual.
38
+ - **Reloj inyectable** y async en todos los backends, igual que `agent-memory` y `rate-limit-quota`.
39
+
40
+ ## Cómo adaptarla
41
+
42
+ 1. Copia `files/` en la raíz del backend, encima de `agent-chat-api`.
43
+ 2. **Settings:** `class Settings(FeedbackSettings, BaseAppSettings)`. En el `.env`: `FEEDBACK_BACKEND=sql`.
44
+ 3. **Tabla:** `metadata.create_all(engine)` o una migración con la `Table` de `feedback/sql.py`.
45
+ 4. **`main.py`:**
46
+
47
+ ```python
48
+ from api.feedback.router import router as feedback_router
49
+ app = create_app(...)
50
+ app.state.feedback_store = FeedbackFactory.create(settings, session_factory=SessionLocal)
51
+ app.include_router(feedback_router)
52
+ ```
53
+
54
+ 5. **Frontend:** tras `done{conversation_id, message_id}` muestra los pulgares; al pulsar, `POST /agent/feedback`; para quitar el voto, `DELETE /agent/feedback/{message_id}`; al abrir una conversación del historial, `GET /agent/feedback?conversation_id=` y cruza por `message_id` con los mensajes de `conversation-history`.
55
+ 6. **Otro backend:** subclase de `FeedbackStore` con `_save`, `get`, `list_for_conversation` y `remove`, una rama en `FeedbackFactory` y una clase de test que herede de `FeedbackConformance`.
56
+ 7. Para comprobarla: `pytest` con las recetas backend copiadas (134 tests con las ocho).
57
+
58
+ **Dependencias:** `pydantic`, `pydantic-settings`; `sqlalchemy` para SQL; las de `agent-chat-api` para `api/`.
59
+
60
+ ## Origen
61
+
62
+ - Probado en producción: `POST /agent/feedback {message_id, rating ±1}` con UPSERT por (mensaje, usuario), `created_or_updated` en la respuesta, comprobación de propiedad (tenant, usuario y `role = 'ai'`) con un único 404, flag del agente → 404 antes que nada, tabla `agent_feedback` con `UNIQUE` por mensaje y usuario y `CHECK(rating IN (-1, 1))`, columna `comment` reservada.
63
+ - Nuevo en esta receta: store como clase base con backends por settings, `conversation_id` en el voto para comprobar la propiedad contra la memoria, `GET` por conversación y `DELETE` para deshacer.
@@ -0,0 +1,72 @@
1
+ """POST /agent/feedback (vote), DELETE /agent/feedback/{message_id} (undo), GET /agent/feedback?conversation_id=.
2
+
3
+ Ownership: the message must be an answer (`ai` with text) inside the caller's own conversation,
4
+ read from the same `Memory` the chat writes. Anything else is one 404: unknown message, another
5
+ user's, a human message, a tool call. Same guards as the chat (404 when the agent is off, 401).
6
+ Mount it next to the chat router: `app.include_router(feedback_router)` after `create_app(...)`.
7
+ """
8
+
9
+ from fastapi import APIRouter, Depends, HTTPException, Path, Query, Request, Response, status
10
+
11
+ from agentic.memory import Memory, MemoryKey
12
+ from feedback import FeedbackStore, FeedbackVote
13
+
14
+ from ..agent.guards import require_agent_enabled
15
+ from ..agent.router import get_memory
16
+ from ..auth import CurrentUser, get_current_user
17
+ from .schemas import ID_PATTERN, FeedbackListResponse, FeedbackOut, FeedbackRequest, FeedbackResponse
18
+
19
+ router = APIRouter(prefix="/agent/feedback", tags=["agent"], dependencies=[Depends(require_agent_enabled)])
20
+
21
+
22
+ def get_feedback_store(request: Request) -> FeedbackStore:
23
+ store: FeedbackStore | None = getattr(request.app.state, "feedback_store", None)
24
+ if store is None:
25
+ raise RuntimeError("app.state.feedback_store is not set: build it with FeedbackFactory")
26
+ return store
27
+
28
+
29
+ async def is_answer_of(memory: Memory, key: MemoryKey, message_id: str) -> bool:
30
+ """True if `message_id` is an AI message with text in that thread (never a human or tool message)."""
31
+ for item in await memory.get_history(key):
32
+ if item.message.id == message_id:
33
+ return item.message.type == "ai" and bool(str(item.message.text).strip())
34
+ return False
35
+
36
+
37
+ @router.post("", response_model=FeedbackResponse)
38
+ async def vote(
39
+ body: FeedbackRequest,
40
+ user: CurrentUser = Depends(get_current_user),
41
+ memory: Memory = Depends(get_memory),
42
+ store: FeedbackStore = Depends(get_feedback_store),
43
+ ) -> FeedbackResponse:
44
+ key = MemoryKey(tenant_id=user.tenant_id, user_id=user.id, conversation_id=body.conversation_id)
45
+ if not await is_answer_of(memory, key, body.message_id):
46
+ raise HTTPException(status.HTTP_404_NOT_FOUND, "Message not found")
47
+ result = await store.vote(FeedbackVote(tenant_id=user.tenant_id, user_id=user.id, **body.model_dump()))
48
+ return FeedbackResponse(
49
+ **FeedbackOut.from_feedback(result.feedback).model_dump(),
50
+ created_or_updated="created" if result.created else "updated",
51
+ )
52
+
53
+
54
+ @router.get("", response_model=FeedbackListResponse)
55
+ async def list_votes(
56
+ conversation_id: str = Query(pattern=ID_PATTERN, max_length=100),
57
+ user: CurrentUser = Depends(get_current_user),
58
+ store: FeedbackStore = Depends(get_feedback_store),
59
+ ) -> FeedbackListResponse:
60
+ votes = await store.list_for_conversation(user.tenant_id, user.id, conversation_id)
61
+ return FeedbackListResponse(conversation_id=conversation_id, feedback=[FeedbackOut.from_feedback(v) for v in votes])
62
+
63
+
64
+ @router.delete("/{message_id}", status_code=status.HTTP_204_NO_CONTENT)
65
+ async def undo(
66
+ message_id: str = Path(pattern=ID_PATTERN, max_length=100),
67
+ user: CurrentUser = Depends(get_current_user),
68
+ store: FeedbackStore = Depends(get_feedback_store),
69
+ ) -> Response:
70
+ if not await store.remove(user.tenant_id, user.id, message_id):
71
+ raise HTTPException(status.HTTP_404_NOT_FOUND, "Feedback not found")
72
+ return Response(status_code=status.HTTP_204_NO_CONTENT)
@@ -0,0 +1,44 @@
1
+ from datetime import datetime
2
+ from typing import Literal
3
+
4
+ from pydantic import BaseModel, ConfigDict, Field
5
+
6
+ from feedback import COMMENT_MAX_LENGTH, Feedback, Rating
7
+
8
+ ID_PATTERN = r"^[A-Za-z0-9_\-]+$" # same rule as ChatRequest.conversation_id
9
+
10
+
11
+ class FeedbackRequest(BaseModel):
12
+ """`conversation_id` and `message_id` are what `done` / `ChatResponse` returned for that answer."""
13
+
14
+ model_config = ConfigDict(frozen=True)
15
+
16
+ conversation_id: str = Field(pattern=ID_PATTERN, max_length=100)
17
+ message_id: str = Field(pattern=ID_PATTERN, max_length=100)
18
+ rating: Rating = Field(description="+1 helpful, -1 not helpful.")
19
+ comment: str | None = Field(default=None, max_length=COMMENT_MAX_LENGTH)
20
+
21
+
22
+ class FeedbackOut(BaseModel):
23
+ model_config = ConfigDict(frozen=True)
24
+
25
+ message_id: str
26
+ conversation_id: str
27
+ rating: Rating
28
+ comment: str | None = None
29
+ updated_at: datetime
30
+
31
+ @classmethod
32
+ def from_feedback(cls, feedback: Feedback) -> "FeedbackOut":
33
+ return cls(**feedback.model_dump(include=set(cls.model_fields)))
34
+
35
+
36
+ class FeedbackResponse(FeedbackOut):
37
+ created_or_updated: Literal["created", "updated"]
38
+
39
+
40
+ class FeedbackListResponse(BaseModel):
41
+ model_config = ConfigDict(frozen=True)
42
+
43
+ conversation_id: str
44
+ feedback: list[FeedbackOut]
@@ -0,0 +1,25 @@
1
+ """Thumbs up / down on agent answers. Independent of FastAPI and of the agent.
2
+
3
+ One vote per (tenant, user, message), upserted. Backend chosen in the settings (`FEEDBACK_BACKEND`),
4
+ built by `FeedbackFactory`. Whether the user may vote a message is decided by the caller
5
+ (the API checks the message is an answer in the user's own conversation).
6
+ """
7
+
8
+ from .base import FeedbackStore
9
+ from .factory import FeedbackFactory
10
+ from .in_memory import InMemoryFeedbackStore
11
+ from .models import COMMENT_MAX_LENGTH, Feedback, FeedbackBackend, FeedbackResult, FeedbackVote, Rating
12
+ from .settings import FeedbackSettings
13
+
14
+ __all__ = [
15
+ "COMMENT_MAX_LENGTH",
16
+ "Feedback",
17
+ "FeedbackBackend",
18
+ "FeedbackFactory",
19
+ "FeedbackResult",
20
+ "FeedbackSettings",
21
+ "FeedbackStore",
22
+ "FeedbackVote",
23
+ "InMemoryFeedbackStore",
24
+ "Rating",
25
+ ]
@@ -0,0 +1,53 @@
1
+ """The contract. Every backend passes `tests/feedback_conformance.py`.
2
+
3
+ vote(vote) upsert by (tenant, user, message): first time `created=True`
4
+ get(...) the user's vote on a message, or None
5
+ list_for_conversation(...) the user's votes in a conversation (so the UI restores the thumbs)
6
+ remove(...) undo a vote; False if there was none
7
+
8
+ Keys always carry tenant AND user: a vote is private to who cast it. Time comes from `clock`.
9
+ Async even in memory: the contract follows the slowest backend.
10
+ """
11
+
12
+ from abc import ABC, abstractmethod
13
+ from collections.abc import Callable
14
+ from datetime import UTC, datetime
15
+
16
+ from .models import Feedback, FeedbackResult, FeedbackVote
17
+
18
+ Clock = Callable[[], datetime]
19
+
20
+
21
+ def utc_now() -> datetime:
22
+ return datetime.now(UTC)
23
+
24
+
25
+ class FeedbackStore(ABC):
26
+ def __init__(self, *, clock: Clock = utc_now) -> None:
27
+ self._clock = clock
28
+
29
+ async def vote(self, vote: FeedbackVote) -> FeedbackResult:
30
+ """Create the vote or update rating and comment of the existing one (same tenant, user, message)."""
31
+ now = self._clock()
32
+ current = await self.get(vote.tenant_id, vote.user_id, vote.message_id)
33
+ if current is None:
34
+ feedback = Feedback(**vote.model_dump(), created_at=now, updated_at=now)
35
+ else:
36
+ feedback = current.model_copy(update={"rating": vote.rating, "comment": vote.comment, "updated_at": now})
37
+ await self._save(feedback)
38
+ return FeedbackResult(feedback=feedback, created=current is None)
39
+
40
+ @abstractmethod
41
+ async def get(self, tenant_id: str, user_id: str, message_id: str) -> Feedback | None: ...
42
+
43
+ @abstractmethod
44
+ async def list_for_conversation(self, tenant_id: str, user_id: str, conversation_id: str) -> list[Feedback]:
45
+ """The user's votes in that conversation, oldest first. [] if none."""
46
+
47
+ @abstractmethod
48
+ async def remove(self, tenant_id: str, user_id: str, message_id: str) -> bool:
49
+ """Delete the vote. True if there was one."""
50
+
51
+ @abstractmethod
52
+ async def _save(self, feedback: Feedback) -> None:
53
+ """Insert or replace the row for (tenant, user, message)."""
@@ -0,0 +1,30 @@
1
+ """The one place that builds the store from the backend the settings name. There is no default."""
2
+
3
+ from collections.abc import Callable
4
+ from typing import Any
5
+
6
+ from .base import Clock, FeedbackStore, utc_now
7
+ from .models import FeedbackBackend
8
+ from .settings import FeedbackSettings
9
+
10
+
11
+ class FeedbackFactory:
12
+ @staticmethod
13
+ def create(
14
+ settings: FeedbackSettings, *, session_factory: Callable[[], Any] | None = None, clock: Clock = utc_now
15
+ ) -> FeedbackStore:
16
+ """Once at startup:
17
+ app.state.feedback_store = FeedbackFactory.create(get_settings(), session_factory=SessionLocal)
18
+ `SQL` needs the app's `session_factory`. Unknown backend -> ValueError."""
19
+ match settings.feedback_backend:
20
+ case FeedbackBackend.IN_MEMORY:
21
+ from .in_memory import InMemoryFeedbackStore
22
+
23
+ return InMemoryFeedbackStore(clock=clock)
24
+ case FeedbackBackend.SQL:
25
+ if session_factory is None:
26
+ raise ValueError("FEEDBACK_BACKEND=sql needs the app's session_factory")
27
+ from .sql import SqlFeedbackStore
28
+
29
+ return SqlFeedbackStore(session_factory, clock=clock)
30
+ raise ValueError(f"Unknown feedback backend: {settings.feedback_backend!r}")
@@ -0,0 +1,29 @@
1
+ """Per-process dict. For tests and local dev only: lost on restart, not shared between workers."""
2
+
3
+ from .base import FeedbackStore
4
+ from .models import Feedback
5
+
6
+ Key = tuple[str, str, str] # tenant, user, message
7
+
8
+
9
+ class InMemoryFeedbackStore(FeedbackStore):
10
+ def __init__(self, **kwargs) -> None:
11
+ super().__init__(**kwargs)
12
+ self._votes: dict[Key, Feedback] = {}
13
+
14
+ async def get(self, tenant_id: str, user_id: str, message_id: str) -> Feedback | None:
15
+ return self._votes.get((tenant_id, user_id, message_id))
16
+
17
+ async def list_for_conversation(self, tenant_id: str, user_id: str, conversation_id: str) -> list[Feedback]:
18
+ mine = [
19
+ f
20
+ for f in self._votes.values()
21
+ if (f.tenant_id, f.user_id, f.conversation_id) == (tenant_id, user_id, conversation_id)
22
+ ]
23
+ return sorted(mine, key=lambda f: f.created_at)
24
+
25
+ async def remove(self, tenant_id: str, user_id: str, message_id: str) -> bool:
26
+ return self._votes.pop((tenant_id, user_id, message_id), None) is not None
27
+
28
+ async def _save(self, feedback: Feedback) -> None:
29
+ self._votes[(feedback.tenant_id, feedback.user_id, feedback.message_id)] = feedback