@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,96 @@
1
+ """Qdrant backend (`qdrant-client`, async). One collection, payload = the chunk fields, metadata
2
+ nested under `metadata`. `tenant_id` and `document_id` get keyword payload indexes.
3
+
4
+ `AsyncQdrantClient(":memory:")` runs the same code without a server: that is what the tests use.
5
+ """
6
+
7
+ from typing import Any
8
+
9
+ from qdrant_client import AsyncQdrantClient, models as q
10
+
11
+ from .base import VectorStore
12
+ from .models import Chunk, EmbeddedChunk, Filters, SearchHit, metadata_of
13
+
14
+ KEYWORD_FIELDS = ("tenant_id", "document_id")
15
+
16
+
17
+ class QdrantVectorStore(VectorStore):
18
+ def __init__(self, client: AsyncQdrantClient, *, collection: str, dimension: int) -> None:
19
+ self._client = client
20
+ self.collection = collection
21
+ self.dimension = dimension
22
+
23
+ async def ensure_ready(self) -> None:
24
+ if not await self._client.collection_exists(self.collection):
25
+ await self._client.create_collection(
26
+ self.collection, vectors_config=q.VectorParams(size=self.dimension, distance=q.Distance.COSINE)
27
+ )
28
+ for field in KEYWORD_FIELDS:
29
+ await self._client.create_payload_index(self.collection, field, q.PayloadSchemaType.KEYWORD)
30
+
31
+ async def upsert(self, chunks: list[EmbeddedChunk]) -> None:
32
+ if chunks:
33
+ await self._client.upsert(
34
+ self.collection,
35
+ points=[q.PointStruct(id=c.chunk.id, vector=c.vector, payload=_payload(c.chunk)) for c in chunks],
36
+ )
37
+
38
+ async def existing_hashes(self, tenant_id: str, document_id: str) -> dict[str, str]:
39
+ hashes: dict[str, str] = {}
40
+ offset = None
41
+ while True:
42
+ points, offset = await self._client.scroll(
43
+ self.collection,
44
+ scroll_filter=_filter(tenant_id, document_id=document_id),
45
+ with_payload=["content_hash"],
46
+ with_vectors=False,
47
+ limit=256,
48
+ offset=offset,
49
+ )
50
+ hashes.update({str(p.id): p.payload["content_hash"] for p in points})
51
+ if offset is None:
52
+ return hashes
53
+
54
+ async def delete_chunks(self, tenant_id: str, chunk_ids: list[str]) -> None:
55
+ if chunk_ids:
56
+ selector = q.FilterSelector(filter=_filter(tenant_id, ids=chunk_ids))
57
+ await self._client.delete(self.collection, points_selector=selector)
58
+
59
+ async def delete_document(self, tenant_id: str, document_id: str) -> int:
60
+ count = len(await self.existing_hashes(tenant_id, document_id))
61
+ if count:
62
+ selector = q.FilterSelector(filter=_filter(tenant_id, document_id=document_id))
63
+ await self._client.delete(self.collection, points_selector=selector)
64
+ return count
65
+
66
+ async def search(
67
+ self, tenant_id: str, vector: list[float], *, limit: int, filters: Filters | None = None
68
+ ) -> list[SearchHit]:
69
+ response = await self._client.query_points(
70
+ self.collection, query=vector, limit=limit, with_payload=True, query_filter=_filter(tenant_id, filters=filters)
71
+ )
72
+ return [
73
+ SearchHit(chunk=_chunk(str(p.id), p.payload or {}), score=max(0.0, min(1.0, p.score)))
74
+ for p in response.points
75
+ ]
76
+
77
+
78
+ def _payload(chunk: Chunk) -> dict[str, Any]:
79
+ return chunk.model_dump(exclude={"id"})
80
+
81
+
82
+ def _chunk(point_id: str, payload: dict[str, Any]) -> Chunk:
83
+ return Chunk(id=point_id, **{**payload, "metadata": metadata_of(payload.get("metadata") or {})})
84
+
85
+
86
+ def _filter(
87
+ tenant_id: str, *, document_id: str | None = None, ids: list[str] | None = None, filters: Filters | None = None
88
+ ) -> q.Filter:
89
+ must: list[Any] = [q.FieldCondition(key="tenant_id", match=q.MatchValue(value=tenant_id))]
90
+ if document_id is not None:
91
+ must.append(q.FieldCondition(key="document_id", match=q.MatchValue(value=document_id)))
92
+ if ids is not None:
93
+ must.append(q.HasIdCondition(has_id=ids))
94
+ for key, value in (filters or {}).items():
95
+ must.append(q.FieldCondition(key=f"metadata.{key}", match=q.MatchValue(value=value)))
96
+ return q.Filter(must=must)
@@ -0,0 +1,48 @@
1
+ """RAG settings BLOCK, meant to be mixed into the project settings (`project-settings` recipe):
2
+
3
+ class Settings(RagSettings, LLMSettings, BaseAppSettings): ...
4
+
5
+ Env vars:
6
+ RAG_BACKEND=memory|qdrant|pgvector required, no default (RAM is for dev only)
7
+ EMBEDDINGS_PROVIDER=openai|hashing openai (hashing = local, no network: dev and tests)
8
+ EMBEDDING_MODEL=text-embedding-3-small EMBEDDING_DIMENSION=1536
9
+ OPENAI_API_KEY=... same name as the `langchain-agent` block: one key
10
+ RAG_CHUNK_SIZE=1000 RAG_CHUNK_OVERLAP=200 (characters)
11
+ RAG_SEARCH_LIMIT=5 RAG_MIN_SCORE=0.0 (cosine; 0.0 = keep everything, see RECIPE)
12
+ QDRANT_URL=https://... QDRANT_API_KEY=... QDRANT_COLLECTION={{app_name}}_chunks
13
+ (pgvector uses the app's own database: pass `session_factory` to the factory)
14
+ """
15
+
16
+ from pydantic import Field, SecretStr, model_validator
17
+ from pydantic_settings import BaseSettings, SettingsConfigDict
18
+
19
+ from .models import EmbeddingsProvider, RagBackend
20
+
21
+
22
+ class RagSettings(BaseSettings):
23
+ model_config = SettingsConfigDict(extra="ignore")
24
+
25
+ rag_backend: RagBackend = Field(description="Where the vectors live. No default on purpose.")
26
+ embeddings_provider: EmbeddingsProvider = EmbeddingsProvider.OPENAI
27
+ embedding_model: str = "text-embedding-3-small"
28
+ embedding_dimension: int = Field(default=1536, gt=0)
29
+ openai_api_key: SecretStr | None = None
30
+
31
+ rag_chunk_size: int = Field(default=1000, gt=0)
32
+ rag_chunk_overlap: int = Field(default=200, ge=0)
33
+ rag_search_limit: int = Field(default=5, ge=1, le=100)
34
+ rag_min_score: float = Field(default=0.0, ge=0.0, le=1.0)
35
+
36
+ qdrant_url: str | None = None
37
+ qdrant_api_key: SecretStr | None = None
38
+ qdrant_collection: str = "{{app_name}}_chunks"
39
+
40
+ @model_validator(mode="after")
41
+ def _backend_has_what_it_needs(self) -> "RagSettings":
42
+ if self.embeddings_provider is EmbeddingsProvider.OPENAI and self.openai_api_key is None:
43
+ raise ValueError("EMBEDDINGS_PROVIDER=openai needs OPENAI_API_KEY")
44
+ if self.rag_backend is RagBackend.QDRANT and not self.qdrant_url:
45
+ raise ValueError("RAG_BACKEND=qdrant needs QDRANT_URL")
46
+ if self.rag_chunk_overlap >= self.rag_chunk_size:
47
+ raise ValueError("RAG_CHUNK_OVERLAP must be smaller than RAG_CHUNK_SIZE")
48
+ return self
@@ -0,0 +1,95 @@
1
+ """Behaviour every `VectorStore` backend must have. A new backend = a subclass with a `store` fixture.
2
+
3
+ class TestRedisVectorStore(VectorStoreConformance):
4
+ @pytest.fixture
5
+ async def store(self): ...
6
+
7
+ Vectors are 4-dimensional here (`DIMENSION`): build the backend's collection with it.
8
+ """
9
+
10
+ import pytest
11
+
12
+ from rag.models import Chunk, EmbeddedChunk
13
+
14
+ DIMENSION = 4
15
+ TENANT = "tenant-1"
16
+ OTHER_TENANT = "tenant-2"
17
+
18
+
19
+ def chunk(document_id: str, index: int, text: str, *, tenant_id: str = TENANT, **metadata) -> Chunk:
20
+ return Chunk(
21
+ id=Chunk.id_for(tenant_id, document_id, index),
22
+ tenant_id=tenant_id,
23
+ document_id=document_id,
24
+ chunk_index=index,
25
+ text=text,
26
+ content_hash=Chunk.hash_of(text),
27
+ title=document_id.title(),
28
+ source=f"https://docs.example/{document_id}",
29
+ metadata=metadata,
30
+ )
31
+
32
+
33
+ def embedded(document_id: str, index: int, vector: list[float], *, tenant_id: str = TENANT, **metadata) -> EmbeddedChunk:
34
+ return EmbeddedChunk(chunk=chunk(document_id, index, f"{document_id} #{index}", tenant_id=tenant_id, **metadata), vector=vector)
35
+
36
+
37
+ ROWS = [
38
+ embedded("manual", 0, [1, 0, 0, 0], category="manual"),
39
+ embedded("manual", 1, [0.9, 0.1, 0, 0], category="manual"),
40
+ embedded("faq", 0, [0, 1, 0, 0], category="faq"),
41
+ embedded("secret", 0, [1, 0, 0, 0], tenant_id=OTHER_TENANT, category="manual"),
42
+ ]
43
+
44
+
45
+ class VectorStoreConformance:
46
+ @pytest.fixture
47
+ async def filled(self, store):
48
+ await store.ensure_ready()
49
+ await store.upsert(ROWS)
50
+ return store
51
+
52
+ async def test_search_orders_by_cosine_and_respects_limit(self, filled):
53
+ hits = await filled.search(TENANT, [1, 0, 0, 0], limit=2)
54
+ assert [(h.chunk.document_id, h.chunk.chunk_index) for h in hits] == [("manual", 0), ("manual", 1)]
55
+ assert hits[0].score == pytest.approx(1.0) and 0.9 < hits[1].score < 1.0
56
+ assert hits[0].chunk == ROWS[0].chunk # title, source and metadata round-trip
57
+
58
+ async def test_tenant_is_filtered_inside_the_query(self, filled):
59
+ hits = await filled.search(OTHER_TENANT, [1, 0, 0, 0], limit=10)
60
+ assert [h.chunk.document_id for h in hits] == ["secret"]
61
+ assert await filled.existing_hashes(OTHER_TENANT, "manual") == {}
62
+
63
+ async def test_metadata_filters_are_equality(self, filled):
64
+ hits = await filled.search(TENANT, [1, 0, 0, 0], limit=10, filters={"category": "faq"})
65
+ assert [h.chunk.document_id for h in hits] == ["faq"]
66
+ assert await filled.search(TENANT, [1, 0, 0, 0], limit=10, filters={"category": "nope"}) == []
67
+
68
+ async def test_upsert_replaces_by_id(self, filled):
69
+ changed = embedded("manual", 0, [0, 0, 0, 1], category="manual")
70
+ await filled.upsert([changed])
71
+ assert await filled.existing_hashes(TENANT, "manual") == {
72
+ changed.chunk.id: changed.chunk.content_hash,
73
+ ROWS[1].chunk.id: ROWS[1].chunk.content_hash,
74
+ }
75
+ best = (await filled.search(TENANT, [0, 0, 0, 1], limit=1))[0]
76
+ assert best.chunk.id == changed.chunk.id and best.chunk.text == changed.chunk.text
77
+
78
+ async def test_delete_chunks_only_touches_the_tenant(self, filled):
79
+ await filled.delete_chunks(OTHER_TENANT, [ROWS[0].chunk.id])
80
+ assert ROWS[0].chunk.id in await filled.existing_hashes(TENANT, "manual")
81
+ await filled.delete_chunks(TENANT, [ROWS[0].chunk.id, "missing-id"])
82
+ assert list(await filled.existing_hashes(TENANT, "manual")) == [ROWS[1].chunk.id]
83
+
84
+ async def test_delete_document_returns_the_count(self, filled):
85
+ assert await filled.delete_document(TENANT, "manual") == 2
86
+ assert await filled.delete_document(TENANT, "manual") == 0
87
+ assert [h.chunk.document_id for h in await filled.search(TENANT, [1, 0, 0, 0], limit=10)] == ["faq"]
88
+ assert await filled.existing_hashes(OTHER_TENANT, "secret") != {}
89
+
90
+ async def test_empty_store_and_empty_upsert(self, store):
91
+ await store.ensure_ready()
92
+ await store.ensure_ready() # idempotent
93
+ await store.upsert([])
94
+ assert await store.search(TENANT, [1, 0, 0, 0], limit=5) == []
95
+ assert await store.existing_hashes(TENANT, "manual") == {}
@@ -0,0 +1,270 @@
1
+ import os
2
+
3
+ import pytest
4
+ from pydantic import SecretStr
5
+
6
+ from rag import (
7
+ Document,
8
+ DocumentSearchService,
9
+ EmbedderFactory,
10
+ HashingEmbedder,
11
+ RagFactory,
12
+ RagSettings,
13
+ RetrievalError,
14
+ Retriever,
15
+ TextChunker,
16
+ VectorStoreFactory,
17
+ format_hits,
18
+ )
19
+ from rag.in_memory import InMemoryVectorStore
20
+ from rag.models import Chunk, SearchHit
21
+ from rag.qdrant import QdrantVectorStore
22
+
23
+ from .rag_conformance import DIMENSION, TENANT, VectorStoreConformance, chunk
24
+
25
+ # --- backends -------------------------------------------------------------------------------
26
+
27
+
28
+ class TestInMemoryVectorStore(VectorStoreConformance):
29
+ @pytest.fixture
30
+ async def store(self):
31
+ return InMemoryVectorStore()
32
+
33
+
34
+ class TestQdrantVectorStore(VectorStoreConformance):
35
+ @pytest.fixture
36
+ async def store(self):
37
+ from qdrant_client import AsyncQdrantClient
38
+
39
+ return QdrantVectorStore(AsyncQdrantClient(":memory:"), collection="test_chunks", dimension=DIMENSION)
40
+
41
+
42
+ @pytest.mark.skipif(not os.environ.get("RAG_TEST_DATABASE_URL"), reason="needs a Postgres with pgvector")
43
+ class TestPgVectorStore(VectorStoreConformance):
44
+ @pytest.fixture
45
+ async def store(self):
46
+ from sqlalchemy import create_engine, text
47
+ from sqlalchemy.orm import sessionmaker
48
+
49
+ from rag.pgvector import TABLE, PgVectorStore
50
+
51
+ engine = create_engine(os.environ["RAG_TEST_DATABASE_URL"])
52
+ with engine.begin() as connection:
53
+ connection.execute(text(f"DROP TABLE IF EXISTS {TABLE}"))
54
+ return PgVectorStore(sessionmaker(engine), dimension=DIMENSION)
55
+
56
+
57
+ # --- chunking -------------------------------------------------------------------------------
58
+
59
+
60
+ def test_chunker_cuts_at_paragraphs_then_sentences_and_overlaps():
61
+ alpha, beta, gamma = "Alpha one. Alpha two.", "Beta one. Beta two.", "Gamma one. Gamma two."
62
+ pieces = TextChunker(size=45, overlap=10).split("\n\n".join([alpha, beta, gamma]))
63
+ # greedy: the first two paragraphs fit together; the third starts with the overlap, cut at a word
64
+ assert pieces == [f"{alpha}\n\n{beta}", f"two.\n\n{gamma}"]
65
+ sentences = TextChunker(size=25, overlap=0).split(f"{alpha}\n\n{beta}")
66
+ assert sentences == ["Alpha one. Alpha two.", "Beta one. Beta two."]
67
+ assert TextChunker().split(" ") == []
68
+ assert TextChunker(size=30, overlap=0).split("x" * 70) == ["x" * 30, "x" * 30, "x" * 10]
69
+
70
+
71
+ def test_chunker_builds_deterministic_ids_and_hashes():
72
+ document = Document(id="manual.pdf", title="Manual", text="one two\n\nthree four", source="s3://m", metadata={"year": 2026})
73
+ chunks = TextChunker(size=12, overlap=0).chunk(TENANT, document)
74
+ assert [c.text for c in chunks] == ["one two", "three four"]
75
+ assert [c.chunk_index for c in chunks] == [0, 1]
76
+ assert chunks[0].id == Chunk.id_for(TENANT, "manual.pdf", 0) != chunks[1].id
77
+ assert chunks[0].content_hash == Chunk.hash_of("one two")
78
+ assert (chunks[0].title, chunks[0].source, chunks[0].metadata) == ("Manual", "s3://m", {"year": 2026})
79
+ assert TextChunker(size=12, overlap=0).chunk(TENANT, document) == chunks
80
+ with pytest.raises(ValueError):
81
+ TextChunker(size=10, overlap=10)
82
+
83
+
84
+ # --- embedders ------------------------------------------------------------------------------
85
+
86
+
87
+ async def test_hashing_embedder_is_deterministic_and_unit_length():
88
+ embedder = HashingEmbedder(dimension=64)
89
+ a, b = await embedder.embed(["reset the device", "Reset the DEVICE"])
90
+ assert a == b and len(a) == 64 and sum(v * v for v in a) == pytest.approx(1.0)
91
+ assert await embedder.embed([]) == []
92
+ (empty,) = await embedder.embed([" "])
93
+ assert empty == [0.0] * 64
94
+
95
+
96
+ class ExplodingEmbedder(HashingEmbedder):
97
+ async def _embed(self, texts):
98
+ raise ConnectionError("sk-live-key-leaked in message")
99
+
100
+
101
+ async def test_embedder_failures_become_retrieval_error_without_the_message():
102
+ with pytest.raises(RetrievalError) as info:
103
+ await ExplodingEmbedder().embed(["x"])
104
+ assert (info.value.kind, info.value.stage) == ("ConnectionError", "embed")
105
+ assert "sk-live" not in str(info.value)
106
+
107
+
108
+ class ShortEmbedder(HashingEmbedder):
109
+ async def _embed(self, texts):
110
+ return []
111
+
112
+
113
+ async def test_embedder_must_return_one_vector_per_text():
114
+ with pytest.raises(RetrievalError, match="MissingVectors"):
115
+ await ShortEmbedder().embed(["x"])
116
+
117
+
118
+ # --- retriever ------------------------------------------------------------------------------
119
+
120
+
121
+ class CountingEmbedder(HashingEmbedder):
122
+ def __init__(self) -> None:
123
+ super().__init__(dimension=64)
124
+ self.embedded: list[str] = []
125
+
126
+ async def _embed(self, texts):
127
+ self.embedded.extend(texts)
128
+ return await super()._embed(texts)
129
+
130
+
131
+ @pytest.fixture
132
+ def embedder() -> CountingEmbedder:
133
+ return CountingEmbedder()
134
+
135
+
136
+ @pytest.fixture
137
+ def retriever(embedder) -> Retriever:
138
+ return Retriever(embedder=embedder, store=InMemoryVectorStore(), chunker=TextChunker(size=40, overlap=0), limit=3)
139
+
140
+
141
+ MANUAL = Document(
142
+ id="manual",
143
+ title="Device manual",
144
+ source="https://docs.example/manual",
145
+ text="To reset the device hold the button.\n\nThe battery lasts ten hours.\n\nWarranty covers two years.",
146
+ metadata={"category": "manual"},
147
+ )
148
+
149
+
150
+ async def test_index_embeds_only_what_changed_and_drops_stale_chunks(retriever, embedder):
151
+ first = await retriever.index(TENANT, MANUAL)
152
+ assert (first.chunks, first.embedded, first.deleted, first.unchanged) == (3, 3, 0, 0)
153
+
154
+ again = await retriever.index(TENANT, MANUAL)
155
+ assert (again.embedded, again.deleted) == (0, 0) and len(embedder.embedded) == 3
156
+
157
+ edited = MANUAL.model_copy(update={"text": MANUAL.text.replace("ten hours", "twelve hours")})
158
+ third = await retriever.index(TENANT, edited)
159
+ assert (third.chunks, third.embedded, third.deleted) == (3, 1, 0)
160
+ assert embedder.embedded[-1] == "The battery lasts twelve hours."
161
+
162
+ shorter = MANUAL.model_copy(update={"text": "To reset the device hold the button."})
163
+ fourth = await retriever.index(TENANT, shorter)
164
+ assert (fourth.chunks, fourth.embedded, fourth.deleted) == (1, 0, 2)
165
+ assert len(await retriever.store.existing_hashes(TENANT, "manual")) == 1
166
+
167
+
168
+ async def test_search_ranks_by_meaning_filters_and_isolates_tenants(retriever):
169
+ await retriever.index(TENANT, MANUAL)
170
+ await retriever.index(TENANT, Document(id="faq", text="How long does the battery last?", metadata={"category": "faq"}))
171
+ await retriever.index("tenant-2", Document(id="spy", text="reset reset reset the device"))
172
+
173
+ hits = await retriever.search(TENANT, "how do I reset the device?")
174
+ assert hits[0].chunk.text == "To reset the device hold the button." and hits[0].score > hits[-1].score
175
+ assert {h.chunk.tenant_id for h in hits} == {TENANT} and len(hits) <= 3
176
+
177
+ faq_only = await retriever.search(TENANT, "battery", filters={"category": "faq"})
178
+ assert [h.chunk.document_id for h in faq_only] == ["faq"]
179
+
180
+ assert await retriever.search(TENANT, " ") == []
181
+ assert await retriever.search(TENANT, "battery", min_score=0.99) == []
182
+ assert len(await retriever.search(TENANT, "battery", limit=1)) == 1
183
+
184
+
185
+ async def test_remove_deletes_the_document(retriever):
186
+ await retriever.index(TENANT, MANUAL)
187
+ assert await retriever.remove(TENANT, "manual") == 3
188
+ assert await retriever.search(TENANT, "reset the device") == []
189
+
190
+
191
+ class BrokenStore(InMemoryVectorStore):
192
+ async def search(self, *args, **kwargs):
193
+ raise TimeoutError("postgres://user:password@host/db")
194
+
195
+
196
+ async def test_store_failures_become_retrieval_error_without_the_message(embedder):
197
+ retriever = Retriever(embedder=embedder, store=BrokenStore())
198
+ with pytest.raises(RetrievalError) as info:
199
+ await retriever.search(TENANT, "x")
200
+ assert (info.value.kind, info.value.stage) == ("TimeoutError", "store") and "password" not in str(info.value)
201
+
202
+
203
+ # --- document search service and prompt context --------------------------------------------
204
+
205
+
206
+ async def test_document_search_service_matches_the_agent_tool_protocol(retriever):
207
+ await retriever.index(TENANT, MANUAL)
208
+ service = DocumentSearchService(retriever, filters={"category": "manual"})
209
+ hits = await service.search(TENANT, "reset the device", 2)
210
+ assert len(hits) == 2 and set(hits[0]) == {"title", "snippet", "source", "document_id", "score"}
211
+ assert hits[0]["title"] == "Device manual" and hits[0]["snippet"].startswith("To reset")
212
+ assert await service.search("tenant-2", "reset the device", 2) == []
213
+
214
+
215
+ def test_format_hits_numbers_cites_and_hides_scores():
216
+ hits = [
217
+ SearchHit(chunk=chunk("manual", 0, "Hold the button.\n"), score=0.91),
218
+ SearchHit(chunk=chunk("faq", 3, "Ten hours."), score=0.42),
219
+ ]
220
+ text = format_hits(hits)
221
+ assert text == "[1] Manual (https://docs.example/manual)\nHold the button.\n\n[2] Faq (https://docs.example/faq)\nTen hours."
222
+ assert "0.91" not in text and TENANT not in text
223
+ assert format_hits([]) == "No relevant documents."
224
+
225
+
226
+ # --- settings and factory -------------------------------------------------------------------
227
+
228
+
229
+ def test_settings_require_a_backend_and_what_it_needs():
230
+ with pytest.raises(ValueError, match="rag_backend"):
231
+ RagSettings(_env_file=None)
232
+ with pytest.raises(ValueError, match="OPENAI_API_KEY"):
233
+ RagSettings(_env_file=None, rag_backend="memory")
234
+ with pytest.raises(ValueError, match="QDRANT_URL"):
235
+ RagSettings(_env_file=None, rag_backend="qdrant", embeddings_provider="hashing")
236
+ with pytest.raises(ValueError, match="OVERLAP"):
237
+ RagSettings(_env_file=None, rag_backend="memory", embeddings_provider="hashing", rag_chunk_size=10, rag_chunk_overlap=10)
238
+ settings = RagSettings(_env_file=None, rag_backend="memory", openai_api_key="sk-test", rag_min_score=0.3)
239
+ assert settings.openai_api_key.get_secret_value() == "sk-test" and settings.rag_min_score == 0.3
240
+
241
+
242
+ def test_factory_builds_the_configured_pieces():
243
+ settings = RagSettings(
244
+ _env_file=None,
245
+ rag_backend="memory",
246
+ embeddings_provider="hashing",
247
+ embedding_dimension=32,
248
+ rag_chunk_size=500,
249
+ rag_chunk_overlap=50,
250
+ rag_search_limit=7,
251
+ rag_min_score=0.2,
252
+ )
253
+ retriever = RagFactory.create(settings)
254
+ assert isinstance(retriever.store, InMemoryVectorStore) and isinstance(retriever.embedder, HashingEmbedder)
255
+ assert retriever.embedder.dimension == 32
256
+ assert (retriever.chunker.size, retriever.chunker.overlap, retriever.limit, retriever.min_score) == (500, 50, 7, 0.2)
257
+
258
+ qdrant = VectorStoreFactory.create(settings.model_copy(update={"rag_backend": "qdrant", "qdrant_url": "http://q:6333"}))
259
+ assert isinstance(qdrant, QdrantVectorStore) and qdrant.collection == settings.qdrant_collection
260
+
261
+ with pytest.raises(ValueError, match="session_factory"):
262
+ VectorStoreFactory.create(settings.model_copy(update={"rag_backend": "pgvector"}))
263
+ with pytest.raises(ValueError, match="dimension"):
264
+ RagFactory.create(settings, embedder=HashingEmbedder(dimension=8))
265
+
266
+
267
+ def test_openai_embedder_is_built_lazily_with_the_key():
268
+ settings = RagSettings(_env_file=None, rag_backend="memory", openai_api_key=SecretStr("sk-test"), embedding_dimension=256)
269
+ embedder = EmbedderFactory.create(settings)
270
+ assert (embedder.model, embedder.dimension) == ("text-embedding-3-small", 256)
@@ -0,0 +1,77 @@
1
+ # rate-limit-quota
2
+
3
+ ## Cuándo usarla
4
+
5
+ Para **frenar el abuso y acotar el gasto** del agente: un rate limit por usuario (ventana deslizante) y una cuota por tenant (diaria y mensual, en peticiones o en coste). La lógica está hecha en clases base; cambiar dónde se guardan los contadores (RAM, SQL, Redis, Supabase…) es escribir una subclase con dos o tres métodos.
6
+
7
+ No depende de ninguna receta: `limits/` no importa FastAPI ni el agente. **Usa `project-settings`** (bloque `LimitsSettings`) y **`agent-chat-api`**: trae el `ensure_turn_allowed` ya implementado y `GET /agent/quota`.
8
+
9
+ ## Qué incluye
10
+
11
+ ```
12
+ limits/
13
+ models.py LimitsBackend · QuotaUnit · QuotaPeriod · WindowState · RateLimitDecision · QuotaLimits
14
+ · PeriodUsage · QuotaStatus · excepciones RateLimited y QuotaExhausted (con su `code`)
15
+ base.py RateLimiter (ABC): check(subject) → decisión o RateLimited(retry_after, resets_at)
16
+ QuotaStore (ABC): status(tenant) · ensure_available(tenant) · record(tenant, amount)
17
+ TurnLimits: fachada allow(tenant, user) = cuota → rate limit → registrar
18
+ in_memory.py InMemoryRateLimiter · InMemoryQuotaStore (tests y desarrollo en un proceso)
19
+ sql.py SqlRateLimiter · SqlQuotaStore + tablas rate_limit_hits y ai_usage_daily (SQLAlchemy 2)
20
+ settings.py bloque LimitsSettings: LIMITS_BACKEND (obligatorio), RATE_LIMIT_*, QUOTA_*
21
+ factory.py LimitsFactory.create(settings, session_factory=...) → TurnLimits
22
+ api/
23
+ agent/guards.py SUSTITUYE al de agent-chat-api: ensure_turn_allowed pregunta a app.state.turn_limits
24
+ limits/router.py GET /agent/quota {available, exhausted, resets_at}
25
+ tests/
26
+ limits_conformance.py lo que TODO backend debe cumplir (5 tests de rate limit + 6 de cuota) y FakeClock
27
+ test_limits.py conformidad en RAM y SQL, TurnLimits, settings y factory (31 tests)
28
+ test_limits_api.py 429 con código y Retry-After, GET /agent/quota, mismos guards (4 tests)
29
+ pytest.ini
30
+ ```
31
+
32
+ ## Decisiones
33
+
34
+ - **La lógica en la base, el almacenamiento en la subclase.** `RateLimiter` decide, calcula `retry_after` y lanza; el backend solo implementa `_acquire` (poda, cuenta y, si cabe, registra). `QuotaStore` calcula periodos, resets y qué periodo bloquea; el backend solo implementa `_usage` y `_add_usage`. Así un backend nuevo son dos métodos y una clase de test de conformidad, y la semántica (una petición rechazada no cuenta, el mes bloquea antes que el día) es la misma en todos.
35
+ - **El backend se elige en los settings, no en el código.** `LIMITS_BACKEND=in_memory | sql`, sin valor por defecto: un límite en memoria con varios workers es un límite por worker, no por usuario, y conviene decidirlo a sabiendas.
36
+ - **Cuota por tenant, rate limit por usuario.** `TurnLimits.allow` comprueba primero la cuota (si el tenant no tiene presupuesto, da igual lo demás) y luego la ventana. Las comprobaciones de rol (403) van antes: quien no tiene acceso no debe gastar cuota.
37
+ - **Unidad de la cuota configurable.** `QUOTA_UNIT=requests` registra una unidad por turno permitido, en el propio guard. `QUOTA_UNIT=cost` no registra nada: el proyecto llama a `quota.record(tenant_id, coste)` cuando sabe lo que costó el turno (los proyectos de origen lo hacen en un callback del LLM). Lo que no sabemos no lo inventamos.
38
+ - **Límites por tenant en una tabla:** `_limits(tenant_id)` es un método que por defecto devuelve los de los settings; se sobrescribe para leer una tabla tipo `tenant_quota`.
39
+ - **El contrato HTTP es el ya probado en producción**, que el frontend interpreta: 429 con `detail={"code": "rate_limited" | "ai_quota_daily_exhausted" | "ai_quota_monthly_exhausted", "resets_at"}`, cabecera `Retry-After` cuando es rate limit, y `GET /agent/quota {available, exhausted, resets_at}` para bloquear el composer hasta `resets_at`.
40
+ - **Periodos en UTC** (día natural y mes natural). El reset es la medianoche o el día 1 siguiente. Si el negocio necesita la zona del tenant, se cambia en `QuotaStore.status`, en un solo sitio.
41
+ - **Reloj inyectable.** `clock` es un callable que devuelve un `datetime` UTC; los tests mueven el tiempo con `FakeClock` sin dormir.
42
+ - **Sin estado en `app.state` no hay límites.** Si `turn_limits` no está, el guard deja pasar y `/agent/quota` dice disponible: los tests de `agent-chat-api` siguen funcionando sin esta receta.
43
+ - **Todo Pydantic:** estados, decisiones, límites y la respuesta del endpoint son `BaseModel` inmutables.
44
+
45
+ ## Cómo adaptarla
46
+
47
+ 1. Copia `files/` en la raíz del backend, encima de `agent-chat-api`. `api/agent/guards.py` **sobrescribe** el de esa receta (mismas funciones más el guard implementado).
48
+ 2. **Settings:** `class Settings(LimitsSettings, BaseAppSettings)`. En el `.env`:
49
+
50
+ ```
51
+ LIMITS_BACKEND=sql
52
+ RATE_LIMIT_REQUESTS=20
53
+ RATE_LIMIT_WINDOW_SECONDS=60
54
+ QUOTA_UNIT=requests
55
+ QUOTA_DAILY_LIMIT=200
56
+ QUOTA_MONTHLY_LIMIT=4000
57
+ ```
58
+
59
+ `RATE_LIMIT_ENABLED=false` quita el rate limit; una cuota vacía es ilimitada.
60
+ 3. **Tablas:** `metadata.create_all(engine)` o una migración con las `Table` de `limits/sql.py`.
61
+ 4. **`main.py`:** tras `create_app`:
62
+
63
+ ```python
64
+ app.state.turn_limits = LimitsFactory.create(settings, session_factory=SessionLocal)
65
+ app.include_router(quota_router) # from api.limits.router import router as quota_router
66
+ ```
67
+
68
+ 5. **Cuota en coste:** con `QUOTA_UNIT=cost`, llama a `app.state.turn_limits.quota.record(tenant_id, coste)` donde conozcas el coste del turno (callback de uso de tokens, fin de `stream_answer`…).
69
+ 6. **Otro backend (Redis):** subclase de `RateLimiter` cuyo `_acquire` ejecute un Lua sobre un sorted set (`ZREMRANGEBYSCORE`, `ZCARD`, `ZADD` si cabe, `ZRANGE 0 0` para el más antiguo), subclase de `QuotaStore` con `INCRBYFLOAT` en claves `usage:{tenant}:{día}`, una rama en `LimitsFactory` y dos clases de test que hereden de `RateLimiterConformance` y `QuotaStoreConformance`.
70
+ 7. Para comprobarla: `pytest` con las cinco recetas backend copiadas (101 tests en total).
71
+
72
+ **Dependencias:** `pydantic`, `pydantic-settings`; `sqlalchemy` para el backend SQL; las de `agent-chat-api` para `api/`.
73
+
74
+ ## Origen
75
+
76
+ - Probado en producción: ventana deslizante por usuario con 429 y `retry_after` (en memoria, o Redis con Lua según settings); cuota diaria y mensual por tenant con marca de agotada, códigos `ai_quota_{daily|monthly}_exhausted` con `resets_at`, `GET /agent/quota` y el frontend que bloquea el composer hasta el reset; uso diario por usuario consultable por el cliente.
77
+ - Nuevo en esta receta: clases base con el almacenamiento abstraído, factory por settings, fachada `TurnLimits`, unidad de cuota configurable y tests de conformidad, para que cambiar de sistema de almacenamiento no toque la lógica.
@@ -0,0 +1,62 @@
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 (429 quota exhausted or rate limited; add your 403 role checks here)
6
+
7
+ All of them before the stream opens: once the first SSE byte is out, the HTTP status is gone.
8
+
9
+ This file REPLACES `api/agent/guards.py` from `agent-chat-api`: step 3 asks the `TurnLimits`
10
+ stored in `app.state.turn_limits` (recipe `rate-limit-quota`). Without it, every turn is allowed.
11
+ """
12
+
13
+ from fastapi import Depends, HTTPException, Request, status
14
+
15
+ from limits import QuotaExhausted, RateLimited, TurnLimits
16
+
17
+ from ..auth import CurrentUser, get_current_user
18
+ from .settings import AgentApiSettings
19
+
20
+
21
+ def get_agent_api_settings(request: Request) -> AgentApiSettings:
22
+ settings: AgentApiSettings | None = getattr(request.app.state, "agent_api_settings", None)
23
+ if settings is None:
24
+ raise RuntimeError("app.state.agent_api_settings is not set: build the app with AgentApiSettings")
25
+ return settings
26
+
27
+
28
+ def get_turn_limits(request: Request) -> TurnLimits | None:
29
+ """`None` = no limits configured (tests, or a deployment that does not want them)."""
30
+ return getattr(request.app.state, "turn_limits", None)
31
+
32
+
33
+ async def require_agent_enabled(settings: AgentApiSettings = Depends(get_agent_api_settings)) -> None:
34
+ if not settings.agent_endpoint_enabled:
35
+ raise HTTPException(status.HTTP_404_NOT_FOUND, "Not Found")
36
+
37
+
38
+ async def ensure_turn_allowed(
39
+ user: CurrentUser = Depends(get_current_user), limits: TurnLimits | None = Depends(get_turn_limits)
40
+ ) -> CurrentUser:
41
+ """Quota (per tenant) then rate limit (per user). 429 with the contract the frontend reads:
42
+
43
+ {"code": "ai_quota_daily_exhausted" | "ai_quota_monthly_exhausted" | "rate_limited",
44
+ "resets_at": "<ISO 8601>"} (+ `Retry-After` header when rate limited)
45
+
46
+ Role checks (403) go before `limits.allow`: a user without access must not spend quota.
47
+ """
48
+ if limits is None:
49
+ return user
50
+ try:
51
+ await limits.allow(user.tenant_id, user.id)
52
+ except QuotaExhausted as exc:
53
+ raise HTTPException(
54
+ status.HTTP_429_TOO_MANY_REQUESTS, {"code": exc.code, "resets_at": exc.resets_at.isoformat()}
55
+ ) from None
56
+ except RateLimited as exc:
57
+ raise HTTPException(
58
+ status.HTTP_429_TOO_MANY_REQUESTS,
59
+ {"code": exc.code, "resets_at": exc.resets_at.isoformat(), "retry_after": exc.retry_after},
60
+ headers={"Retry-After": str(exc.retry_after)},
61
+ ) from None
62
+ return user