@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,146 @@
1
+ """Behaviour every backend must have. A new backend = a subclass with a fixture.
2
+
3
+ class TestRedisRateLimiter(RateLimiterConformance):
4
+ @pytest.fixture
5
+ def limiter(self, clock): return RedisRateLimiter(redis, max_requests=3, window_seconds=60, clock=clock)
6
+
7
+ class TestRedisQuotaStore(QuotaStoreConformance):
8
+ @pytest.fixture
9
+ def quota(self, clock): return RedisQuotaStore(redis, limits=QuotaLimits(daily=2, monthly=3), clock=clock)
10
+
11
+ The `clock` fixture is a `FakeClock`: tests move time with `clock.advance(seconds)` / `clock.set(dt)`.
12
+ """
13
+
14
+ from datetime import UTC, datetime, timedelta
15
+
16
+ import pytest
17
+
18
+ from limits import QuotaExhausted, QuotaPeriod, RateLimited
19
+
20
+ MAX_REQUESTS = 3
21
+ WINDOW = 60
22
+ DAILY, MONTHLY = 2, 3
23
+ START = datetime(2026, 3, 30, 10, 0, tzinfo=UTC)
24
+
25
+
26
+ class FakeClock:
27
+ def __init__(self, now: datetime = START) -> None:
28
+ self.now = now
29
+
30
+ def __call__(self) -> datetime:
31
+ return self.now
32
+
33
+ def advance(self, seconds: float) -> None:
34
+ self.now += timedelta(seconds=seconds)
35
+
36
+ def set(self, now: datetime) -> None:
37
+ self.now = now
38
+
39
+
40
+ @pytest.fixture
41
+ def clock() -> FakeClock:
42
+ return FakeClock()
43
+
44
+
45
+ class RateLimiterConformance:
46
+ """Fixture `limiter`: `max_requests=MAX_REQUESTS`, `window_seconds=WINDOW`, `clock=clock`."""
47
+
48
+ async def test_allows_up_to_the_limit_and_counts_down(self, limiter):
49
+ remaining = [(await limiter.check("u1")).remaining for _ in range(MAX_REQUESTS)]
50
+ assert remaining == [2, 1, 0]
51
+
52
+ async def test_refuses_the_next_one_with_retry_after(self, limiter, clock):
53
+ for _ in range(MAX_REQUESTS):
54
+ await limiter.check("u1")
55
+ clock.advance(10)
56
+
57
+ with pytest.raises(RateLimited) as exc:
58
+ await limiter.check("u1")
59
+
60
+ assert exc.value.code == "rate_limited"
61
+ assert exc.value.retry_after == WINDOW - 10
62
+ assert exc.value.resets_at == START + timedelta(seconds=WINDOW)
63
+
64
+ async def test_refused_requests_are_not_counted(self, limiter, clock):
65
+ for _ in range(MAX_REQUESTS):
66
+ await limiter.check("u1")
67
+ for _ in range(5):
68
+ with pytest.raises(RateLimited):
69
+ await limiter.check("u1")
70
+ clock.advance(WINDOW)
71
+
72
+ assert (await limiter.check("u1")).remaining == MAX_REQUESTS - 1
73
+
74
+ async def test_window_slides_one_slot_at_a_time(self, limiter, clock):
75
+ await limiter.check("u1")
76
+ clock.advance(30)
77
+ await limiter.check("u1")
78
+ await limiter.check("u1")
79
+ clock.advance(31) # only the first hit has left the window
80
+
81
+ assert (await limiter.check("u1")).remaining == 0
82
+ with pytest.raises(RateLimited) as exc:
83
+ await limiter.check("u1")
84
+ assert exc.value.retry_after == 29
85
+
86
+ async def test_subjects_are_independent(self, limiter):
87
+ for _ in range(MAX_REQUESTS):
88
+ await limiter.check("u1")
89
+
90
+ assert (await limiter.check("u2")).remaining == MAX_REQUESTS - 1
91
+
92
+
93
+ class QuotaStoreConformance:
94
+ """Fixture `quota`: `limits=QuotaLimits(daily=DAILY, monthly=MONTHLY)`, `clock=clock`."""
95
+
96
+ async def test_unknown_tenant_has_everything_available(self, quota):
97
+ status = await quota.status("t1")
98
+ assert status.available and status.exhausted is None and status.resets_at is None
99
+ assert (status.daily.used, status.daily.limit) == (0, DAILY)
100
+ assert (status.monthly.used, status.monthly.limit) == (0, MONTHLY)
101
+
102
+ async def test_record_accumulates_and_daily_exhausts_first(self, quota):
103
+ await quota.record("t1", 1)
104
+ await quota.record("t1", 0.5)
105
+ assert (await quota.status("t1")).daily.used == 1.5
106
+
107
+ await quota.record("t1", 0.5)
108
+ with pytest.raises(QuotaExhausted) as exc:
109
+ await quota.ensure_available("t1")
110
+
111
+ assert exc.value.code == "ai_quota_daily_exhausted"
112
+ assert exc.value.period == QuotaPeriod.DAILY
113
+ assert exc.value.resets_at == datetime(2026, 3, 31, tzinfo=UTC)
114
+
115
+ async def test_daily_resets_at_midnight_utc_but_monthly_keeps_counting(self, quota, clock):
116
+ await quota.record("t1", DAILY)
117
+ clock.set(datetime(2026, 3, 31, 0, 0, 1, tzinfo=UTC))
118
+
119
+ status = await quota.ensure_available("t1")
120
+
121
+ assert status.daily.used == 0 and status.monthly.used == DAILY
122
+
123
+ async def test_monthly_exhausts_and_resets_on_the_first_of_next_month(self, quota, clock):
124
+ await quota.record("t1", DAILY)
125
+ clock.set(datetime(2026, 3, 31, 12, 0, tzinfo=UTC))
126
+ await quota.record("t1", MONTHLY - DAILY)
127
+
128
+ with pytest.raises(QuotaExhausted) as exc:
129
+ await quota.ensure_available("t1")
130
+ assert exc.value.code == "ai_quota_monthly_exhausted"
131
+ assert exc.value.resets_at == datetime(2026, 4, 1, tzinfo=UTC)
132
+
133
+ clock.set(datetime(2026, 4, 1, tzinfo=UTC))
134
+ assert (await quota.status("t1")).monthly.used == 0
135
+
136
+ async def test_tenants_are_independent(self, quota):
137
+ await quota.record("t1", DAILY)
138
+
139
+ assert (await quota.status("t2")).available
140
+ assert not (await quota.status("t1")).available
141
+
142
+ async def test_recording_zero_or_negative(self, quota):
143
+ await quota.record("t1", 0)
144
+ assert (await quota.status("t1")).daily.used == 0
145
+ with pytest.raises(ValueError):
146
+ await quota.record("t1", -1)
@@ -0,0 +1,167 @@
1
+ from datetime import UTC, datetime
2
+
3
+ import pytest
4
+ from pydantic import ValidationError
5
+ from sqlalchemy import create_engine
6
+ from sqlalchemy.orm import sessionmaker
7
+ from sqlalchemy.pool import StaticPool
8
+
9
+ from limits import (
10
+ InMemoryQuotaStore,
11
+ InMemoryRateLimiter,
12
+ LimitsBackend,
13
+ LimitsFactory,
14
+ LimitsSettings,
15
+ QuotaExhausted,
16
+ QuotaLimits,
17
+ QuotaUnit,
18
+ RateLimited,
19
+ TurnLimits,
20
+ )
21
+ from limits.sql import SqlQuotaStore, SqlRateLimiter, metadata
22
+
23
+ from .limits_conformance import ( # noqa: F401 (clock: fixture used by the conformance classes)
24
+ DAILY,
25
+ MAX_REQUESTS,
26
+ MONTHLY,
27
+ WINDOW,
28
+ FakeClock,
29
+ QuotaStoreConformance,
30
+ RateLimiterConformance,
31
+ clock,
32
+ )
33
+
34
+
35
+ def sqlite_session_factory():
36
+ engine = create_engine("sqlite://", poolclass=StaticPool, connect_args={"check_same_thread": False})
37
+ metadata.create_all(engine)
38
+ return sessionmaker(engine)
39
+
40
+
41
+ LIMITS = QuotaLimits(daily=DAILY, monthly=MONTHLY)
42
+
43
+
44
+ class TestInMemoryRateLimiter(RateLimiterConformance):
45
+ @pytest.fixture
46
+ def limiter(self, clock):
47
+ return InMemoryRateLimiter(max_requests=MAX_REQUESTS, window_seconds=WINDOW, clock=clock)
48
+
49
+
50
+ class TestSqlRateLimiter(RateLimiterConformance):
51
+ @pytest.fixture
52
+ def limiter(self, clock):
53
+ return SqlRateLimiter(sqlite_session_factory(), max_requests=MAX_REQUESTS, window_seconds=WINDOW, clock=clock)
54
+
55
+
56
+ class TestInMemoryQuotaStore(QuotaStoreConformance):
57
+ @pytest.fixture
58
+ def quota(self, clock):
59
+ return InMemoryQuotaStore(limits=LIMITS, clock=clock)
60
+
61
+
62
+ class TestSqlQuotaStore(QuotaStoreConformance):
63
+ @pytest.fixture
64
+ def quota(self, clock):
65
+ return SqlQuotaStore(sqlite_session_factory(), limits=LIMITS, clock=clock)
66
+
67
+
68
+ # --- TurnLimits: the facade a turn calls -----------------------------------------------------
69
+
70
+
71
+ def turn_limits(unit: QuotaUnit = QuotaUnit.REQUESTS, *, rate_limiter: bool = True) -> TurnLimits:
72
+ clock = FakeClock()
73
+ return TurnLimits(
74
+ quota=InMemoryQuotaStore(limits=QuotaLimits(daily=2), clock=clock),
75
+ rate_limiter=InMemoryRateLimiter(max_requests=1, window_seconds=60, clock=clock) if rate_limiter else None,
76
+ unit=unit,
77
+ )
78
+
79
+
80
+ async def test_requests_unit_counts_each_allowed_turn():
81
+ limits = turn_limits(rate_limiter=False)
82
+ await limits.allow("t1", "u1")
83
+ await limits.allow("t1", "u2")
84
+
85
+ with pytest.raises(QuotaExhausted):
86
+ await limits.allow("t1", "u3")
87
+ assert (await limits.status("t1")).daily.used == 2
88
+
89
+
90
+ async def test_cost_unit_records_nothing_until_you_do():
91
+ limits = turn_limits(QuotaUnit.COST, rate_limiter=False)
92
+ for _ in range(5):
93
+ await limits.allow("t1", "u1")
94
+ assert (await limits.status("t1")).daily.used == 0
95
+
96
+ await limits.quota.record("t1", 2.0) # your code, once the turn is priced
97
+ with pytest.raises(QuotaExhausted):
98
+ await limits.allow("t1", "u1")
99
+
100
+
101
+ async def test_quota_is_checked_before_the_rate_limit_and_a_refused_turn_is_not_counted():
102
+ limits = turn_limits()
103
+ await limits.allow("t1", "u1")
104
+
105
+ with pytest.raises(RateLimited):
106
+ await limits.allow("t1", "u1")
107
+ assert (await limits.status("t1")).daily.used == 1
108
+
109
+ await limits.quota.record("t1", 1) # tenant exhausted: quota wins even for a fresh user
110
+ with pytest.raises(QuotaExhausted):
111
+ await limits.allow("t1", "u2")
112
+
113
+
114
+ async def test_per_tenant_limits_by_overriding_limits():
115
+ class TenantTableQuota(InMemoryQuotaStore):
116
+ async def _limits(self, tenant_id):
117
+ return QuotaLimits(daily=10) if tenant_id == "premium" else self.default_limits
118
+
119
+ quota = TenantTableQuota(limits=QuotaLimits(daily=1), clock=FakeClock())
120
+ await quota.record("premium", 1)
121
+ await quota.record("basic", 1)
122
+
123
+ assert (await quota.status("premium")).available
124
+ assert not (await quota.status("basic")).available
125
+
126
+
127
+ # --- Settings + factory: the backend is chosen in .env, not in code ---------------------------
128
+
129
+
130
+ def test_everything_comes_from_env(monkeypatch):
131
+ monkeypatch.setenv("LIMITS_BACKEND", "in_memory")
132
+ monkeypatch.setenv("RATE_LIMIT_REQUESTS", "5")
133
+ monkeypatch.setenv("RATE_LIMIT_WINDOW_SECONDS", "30")
134
+ monkeypatch.setenv("QUOTA_UNIT", "cost")
135
+ monkeypatch.setenv("QUOTA_DAILY_LIMIT", "2.5")
136
+
137
+ limits = LimitsFactory.create(LimitsSettings())
138
+
139
+ assert isinstance(limits.quota, InMemoryQuotaStore) and isinstance(limits.rate_limiter, InMemoryRateLimiter)
140
+ assert (limits.rate_limiter.max_requests, limits.rate_limiter.window_seconds) == (5, 30)
141
+ assert limits.unit == QuotaUnit.COST
142
+ assert limits.quota.default_limits == QuotaLimits(daily=2.5, monthly=None)
143
+
144
+
145
+ def test_switching_to_sql_is_only_a_setting():
146
+ limits = LimitsFactory.create(LimitsSettings(limits_backend="sql"), session_factory=sqlite_session_factory())
147
+ assert isinstance(limits.quota, SqlQuotaStore) and isinstance(limits.rate_limiter, SqlRateLimiter)
148
+
149
+
150
+ def test_rate_limit_can_be_switched_off():
151
+ limits = LimitsFactory.create(LimitsSettings(limits_backend="in_memory", rate_limit_enabled=False))
152
+ assert limits.rate_limiter is None
153
+
154
+
155
+ def test_backend_is_required_and_validated(monkeypatch):
156
+ monkeypatch.delenv("LIMITS_BACKEND", raising=False)
157
+ with pytest.raises(ValidationError):
158
+ LimitsSettings()
159
+ with pytest.raises(ValidationError):
160
+ LimitsSettings(limits_backend="redis")
161
+ with pytest.raises(ValueError, match="session_factory"):
162
+ LimitsFactory.create(LimitsSettings(limits_backend=LimitsBackend.SQL))
163
+
164
+
165
+ def test_default_clock_is_utc():
166
+ store = InMemoryQuotaStore(limits=QuotaLimits())
167
+ assert store._clock().tzinfo is UTC and abs((store._clock() - datetime.now(UTC)).total_seconds()) < 5
@@ -0,0 +1,100 @@
1
+ """The guard and GET /agent/quota on the real app. Needs agent-chat-api (and what it requires)
2
+ copied next to `limits/`, with this recipe's `api/agent/guards.py` in place."""
3
+
4
+ import httpx
5
+ import pytest
6
+ from langchain_core.messages import AIMessage
7
+
8
+ from agentic.agents import AssistantAgent
9
+ from agentic.memory import InMemoryMemory
10
+ from agentic.registry import registry
11
+ from api.agent.settings import AgentApiSettings
12
+ from api.app import create_app
13
+ from api.auth import StaticTokenVerifier
14
+ from api.limits.router import router as quota_router
15
+ from limits import InMemoryQuotaStore, InMemoryRateLimiter, QuotaLimits, QuotaUnit, TurnLimits
16
+
17
+ from .fakes import ScriptedChatModel
18
+ from .limits_conformance import FakeClock
19
+ from .test_agent_api import TOKENS, auth, classifier_answering
20
+
21
+
22
+ def make_app(limits: TurnLimits | None):
23
+ app = create_app(
24
+ settings=AgentApiSettings(),
25
+ token_verifier=StaticTokenVerifier(TOKENS),
26
+ memory=InMemoryMemory(),
27
+ document_search=None,
28
+ )
29
+ app.state.turn_limits = limits
30
+ app.include_router(quota_router)
31
+ return app
32
+
33
+
34
+ def limits_for_tests(clock: FakeClock, *, daily: float | None = 2, per_minute: int = 1) -> TurnLimits:
35
+ return TurnLimits(
36
+ quota=InMemoryQuotaStore(limits=QuotaLimits(daily=daily), clock=clock),
37
+ rate_limiter=InMemoryRateLimiter(max_requests=per_minute, window_seconds=60, clock=clock),
38
+ unit=QuotaUnit.REQUESTS,
39
+ )
40
+
41
+
42
+ def client(app) -> httpx.AsyncClient:
43
+ return httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://test")
44
+
45
+
46
+ @pytest.fixture(autouse=True)
47
+ def answering_agents():
48
+ registry.reset()
49
+ registry.override(
50
+ classifier=classifier_answering("technical"),
51
+ assistant=AssistantAgent(llm=ScriptedChatModel(responses=[AIMessage("ok")] * 5), tools=[]),
52
+ )
53
+ yield
54
+ registry.reset()
55
+
56
+
57
+ async def test_without_limits_everything_passes_and_quota_is_available():
58
+ app = make_app(None)
59
+ async with client(app) as c:
60
+ assert (await c.post("/agent/chat", json={"question": "hola"}, headers=auth())).status_code == 200
61
+ assert (await c.get("/agent/quota", headers=auth())).json() == {"available": True, "exhausted": None, "resets_at": None}
62
+
63
+
64
+ async def test_rate_limited_turn_is_429_with_code_and_retry_after():
65
+ clock = FakeClock()
66
+ app = make_app(limits_for_tests(clock))
67
+ async with client(app) as c:
68
+ assert (await c.post("/agent/chat", json={"question": "hola"}, headers=auth())).status_code == 200
69
+ clock.advance(15)
70
+ response = await c.post("/agent/stream", json={"question": "otra"}, headers=auth())
71
+
72
+ assert response.status_code == 429
73
+ assert response.headers["retry-after"] == "45"
74
+ detail = response.json()["detail"]
75
+ assert detail["code"] == "rate_limited" and detail["retry_after"] == 45
76
+ assert detail["resets_at"] == "2026-03-30T10:01:00+00:00"
77
+
78
+
79
+ async def test_exhausted_quota_is_429_and_get_quota_says_until_when():
80
+ clock = FakeClock()
81
+ app = make_app(limits_for_tests(clock, daily=1, per_minute=10))
82
+ async with client(app) as c:
83
+ assert (await c.post("/agent/chat", json={"question": "hola"}, headers=auth())).status_code == 200
84
+ refused = await c.post("/agent/chat", json={"question": "otra"}, headers=auth())
85
+ quota = await c.get("/agent/quota", headers=auth())
86
+ other_tenant = await c.get("/agent/quota", headers=auth("tok-bob"))
87
+
88
+ assert refused.status_code == 429
89
+ assert refused.json()["detail"] == {"code": "ai_quota_daily_exhausted", "resets_at": "2026-03-31T00:00:00+00:00"}
90
+ assert quota.json() == {"available": False, "exhausted": "daily", "resets_at": "2026-03-31T00:00:00Z"}
91
+ assert other_tenant.json()["available"] is True
92
+
93
+
94
+ async def test_quota_route_has_the_same_guards_as_the_chat():
95
+ app = make_app(None)
96
+ async with client(app) as c:
97
+ assert (await c.get("/agent/quota")).status_code == 401
98
+ app.state.agent_api_settings = AgentApiSettings(agent_endpoint_enabled=False)
99
+ async with client(app) as c:
100
+ assert (await c.get("/agent/quota", headers=auth())).status_code == 404
@@ -0,0 +1,73 @@
1
+ # voice-providers
2
+
3
+ ## Cuándo usarla
4
+
5
+ Para **dictar al agente y leerle la respuesta**: un endpoint que recibe el audio del navegador (`MediaRecorder`) y devuelve el texto, y otro que convierte texto en audio. El proveedor (OpenAI o un doble local) se elige en `.env`, nada toca disco y cada fallo llega con un código HTTP distinto para "es culpa del audio", "el proveedor está saturado" o "falta la clave".
6
+
7
+ No cubre la conversación de voz en tiempo real (WebRTC, VAD, barge-in). Si la necesitas, `Transcriber`/`Synthesizer` siguen valiendo por turno; el transporte es otra receta.
8
+
9
+ **Requiere `fastapi-base`** (`ApiError`, request id) **y `auth-verifier`** (`get_current_user`) para el router. `voice/` solo no requiere nada. **Usa `project-settings`** (bloque `VoiceSettings`).
10
+
11
+ ## Qué incluye
12
+
13
+ ```
14
+ voice/
15
+ models.py AudioInput(content, mime) · Transcription(text, language, engine, duration_ms) · Speech(audio, mime) · VoiceError(code, retryable, kind) · AUDIO_FORMATS
16
+ base.py Transcriber (ABC, template: valida formato/tamaño/vacío, timeout, traduce errores) · Synthesizer (ABC: vacío, longitud, voz permitida)
17
+ openai_provider.py OpenAITranscriber (gpt-4o-*-transcribe o whisper-1 con no_speech_prob) · OpenAISynthesizer · translate_openai_error · openai_client
18
+ fake.py FakeTranscriber (texto fijo, b"SILENCE" → "") · FakeSynthesizer (WAV de silencio proporcional al texto)
19
+ settings.py bloque VoiceSettings: STT_PROVIDER y TTS_PROVIDER (obligatorios), STT_MODEL/LANGUAGE/PROMPT/MAX_BYTES/TIMEOUT, TTS_MODEL/VOICE/FORMAT/MAX_CHARS
20
+ factory.py VoiceFactory.transcriber(settings, http_client=) · VoiceFactory.synthesizer(settings, http_client=)
21
+ api/voice/router.py POST /voice/transcribe (multipart file + language?) → {text, language} · POST /voice/synthesize {text, voice?} → audio, no-store
22
+ tests/
23
+ fake_openai.py OpenAI a nivel HTTP (httpx.MockTransport): el SDK real corre, solo se sustituye la red
24
+ voice_conformance.py TranscriberConformance (6) y SynthesizerConformance (3): lo que todo proveedor debe cumplir
25
+ test_voice.py 37 tests sin red: conformidad de los cuatro proveedores, qué se envía a OpenAI, whisper y silencio, mapeo de errores HTTP, fakes, settings, factory
26
+ test_voice_api.py 13 tests del router (se saltan sin fastapi-base y auth-verifier): 401, 413, 415, 422 con código, 429/502/503/504, audio con no-store, app sin voz → 503
27
+ pytest.ini
28
+ ```
29
+
30
+ ## Decisiones
31
+
32
+ - **Template method en la base, proveedor en la subclase.** `transcribe()` valida que haya contenido, que el MIME esté en `AUDIO_FORMATS` y que no supere `max_bytes`, acota el tiempo con `asyncio.wait_for`, comprueba que el proveedor devolvió texto y traduce cualquier excepción a `VoiceError`. `_transcribe()` solo habla con el SDK. Lo mismo `synthesize()` con texto vacío, longitud y lista de voces.
33
+ - **`""` significa "sin voz"**, nunca un error. El router lo convierte en 422 `no_speech`; un agente de voz lo saltaría. Con `whisper-1` se usa `verbose_json` y si todos los segmentos tienen `no_speech_prob` sobre el umbral se devuelve `""`: es la única defensa contra el "Subtítulos por Amara.org" que Whisper alucina con silencio (la alternativa es filtrarlo por regex). Los modelos `gpt-4o-*-transcribe` no alucinan así y van en `json`.
34
+ - **El proveedor no reintenta** (`max_retries=0`); `VoiceError.retryable` lo dice y decide el que llama. Un 429 del proveedor es `rate_limited` (429 al cliente con `Retry-After`), un timeout es 504, un fallo del proveedor es 502 y una configuración mala (401, modelo inexistente) es 503: el cliente distingue "reintenta" de "avisa a soporte".
35
+ - **Culpa del audio o culpa del proveedor.** 413/415 y los 400 que apuntan a `file` (`audio_too_short`, `unsupported_format`) son `invalid_audio` y no reintentables; cualquier otro 400 se registra con su `param` (suele ser un modelo mal escrito).
36
+ - **Solo la clase del error al log:** el mensaje del SDK puede llevar la URL con la clave.
37
+ - **El audio no toca disco ni se guarda.** `read_bounded` lee el upload por trozos en memoria y corta en cuanto pasa `max_bytes` (413) sin esperar al final. La respuesta de TTS lleva `Cache-Control: no-store`.
38
+ - **MIME sin parámetros y extensión por tabla.** `MediaRecorder` manda `audio/webm;codecs=opus` o `audio/mp4` (Safari); `AUDIO_FORMATS` lo pasa a la extensión que OpenAI entiende en `file=("audio.webm", bytes)`. `audio/aac` no está: OpenAI lo rechaza.
39
+ - **Idioma como pista, no como verdad.** `STT_LANGUAGE` es el del proyecto (`es`) y el cliente puede mandar otro por petición (por ejemplo el de la interfaz); `None` deja que el modelo detecte. `STT_PROMPT` es vocabulario del dominio (siglas, nombres de producto): mejora Whisper más que cualquier otro ajuste.
40
+ - **`FakeSynthesizer` devuelve un WAV válido**, no `b"fake"`: el frontend puede reproducirlo en desarrollo sin clave.
41
+ - **Tests a nivel HTTP** (`httpx.MockTransport`): se comprueba lo que de verdad se envía (nombre de archivo, modelo, idioma, prompt, `response_format`), no un mock del método.
42
+ - **Sin TTS en streaming ni efectos de sonido.** Trocear la respuesta del LLM por frases y mandarlas al proveedor en PCM mientras suena un teclado es parte de un pipeline en tiempo real, no de esta receta. `Synthesizer._synthesize` devuelve bytes completos; un streaming sería `AsyncIterator[bytes]` en una subclase.
43
+
44
+ ## Cómo adaptarla
45
+
46
+ 1. Copia `files/` en la raíz del backend, encima de `fastapi-base` y `auth-verifier`.
47
+ 2. **Settings:** `class Settings(VoiceSettings, LLMSettings, BaseAppSettings)` (comparte `OPENAI_API_KEY`). En el `.env`:
48
+
49
+ ```
50
+ STT_PROVIDER=openai STT_MODEL=gpt-4o-mini-transcribe STT_LANGUAGE=es STT_PROMPT="Acme, SKU, ERP"
51
+ TTS_PROVIDER=openai TTS_MODEL=gpt-4o-mini-tts TTS_VOICE=nova TTS_FORMAT=mp3
52
+ ```
53
+
54
+ En local sin clave: `STT_PROVIDER=fake` y `TTS_PROVIDER=fake`. Si tu app solo dicta, borra `Synthesizer`, `FakeSynthesizer`, `OpenAISynthesizer`, el endpoint `/synthesize` y los campos `TTS_*`: sin segundo uso no hay abstracción que mantener.
55
+ 3. **Arranque** (`lifespan` de `create_app`):
56
+
57
+ ```python
58
+ app.state.transcriber = VoiceFactory.transcriber(settings)
59
+ app.state.synthesizer = VoiceFactory.synthesizer(settings)
60
+ app.include_router(voice_router)
61
+ ```
62
+
63
+ y al apagar, `await app.state.transcriber.close()`.
64
+ 4. **Frontend:** `MediaRecorder` con `audio/webm;codecs=opus` y `audio/mp4` como respaldo para Safari; `FormData` con `file` y, si quieres, `language`; `fetch("/voice/transcribe")` con el Bearer. Para leer: `fetch("/voice/synthesize")` → `blob` → `new Audio(URL.createObjectURL(blob)).play()`. Añade `voice.use` a tus guards si tienes roles y pasa el endpoint por `rate-limit-quota`.
65
+ 5. **Proveedor nuevo** (Deepgram, Groq Whisper, Whisper local): subclase de `Transcriber` con `_transcribe` y `_translate`, `class TestX(TranscriberConformance)` con la fixture, un valor en `SttProvider` y un caso en la factory. Groq y Azure con API compatible: solo `OPENAI_BASE_URL`.
66
+ 6. Para comprobarla: `pytest` (37 tests sin red; con `fastapi-base` y `auth-verifier` copiadas, 50 de esta receta).
67
+
68
+ **Dependencias:** `pydantic-settings`, `fastapi`, `python-multipart` (uploads); `openai` (probado con 3.55) para el proveedor openai; `httpx` en tests.
69
+
70
+ ## Origen
71
+
72
+ - Probado en producción: transcriptor base con template method (valida, mide, traduce a un error propio con `retryable`), `AudioInput(content, mime)`, texto vacío = sin voz, `no_speech_prob` de `verbose_json`, `max_retries=0`, mapa de errores del SDK a códigos, upload acotado en memoria sin tocar disco, dobles y batería de conformidad, `FakeOpenAI` con `httpx.MockTransport`; TTS bajo demanda con `audio/speech` (MP3 completo), lista de voces permitidas, `tts_max_chars`, `Cache-Control: no-store`, idioma por petición, 503 sin clave frente a 502 con fallo del proveedor, filtro de alucinaciones de Whisper; STT/TTS como ABC con factory por nombre; captura con `MediaRecorder` webm/opus y mp4 para Safari.
73
+ - No incluido en esta receta: TTS por frases en streaming y el transporte de voz en tiempo real.
@@ -0,0 +1,113 @@
1
+ """POST /voice/transcribe (multipart `file`, optional `language`) -> {text, language}
2
+ POST /voice/synthesize {text, voice?} -> audio bytes (audio/mpeg...), `Cache-Control: no-store`.
3
+
4
+ Nothing is stored: not the audio, not the text. The upload is read in memory and cut as soon as it
5
+ passes the limit. `VoiceError` codes map to HTTP here and nowhere else:
6
+ invalid_audio -> 415 (format) / 413 (size) / 422 (empty, too short) no speech -> 422 {"code": "no_speech"}
7
+ text_too_long -> 413 invalid_voice -> 422 rate_limited -> 429 timeout -> 504 unavailable -> 502 (503 if misconfigured)
8
+ """
9
+
10
+ import re
11
+
12
+ from fastapi import APIRouter, Depends, File, Form, Request, Response, UploadFile
13
+ from pydantic import BaseModel, Field
14
+
15
+ from ..auth import CurrentUser, get_current_user
16
+ from ..errors import ApiError
17
+ from voice import AudioInput, Synthesizer, Transcriber, VoiceError, VoiceErrorCode
18
+
19
+ router = APIRouter(prefix="/voice", tags=["voice"])
20
+
21
+ LANGUAGE = re.compile(r"^[a-z]{2}(-[A-Za-z]{2})?$")
22
+ READ_CHUNK = 64 * 1024
23
+
24
+
25
+ def get_transcriber(request: Request) -> Transcriber:
26
+ transcriber: Transcriber | None = getattr(request.app.state, "transcriber", None)
27
+ if transcriber is None:
28
+ raise ApiError(503, "voice_unavailable") # the app was built without voice
29
+ return transcriber
30
+
31
+
32
+ def get_synthesizer(request: Request) -> Synthesizer:
33
+ synthesizer: Synthesizer | None = getattr(request.app.state, "synthesizer", None)
34
+ if synthesizer is None:
35
+ raise ApiError(503, "voice_unavailable")
36
+ return synthesizer
37
+
38
+
39
+ class TranscribeResponse(BaseModel):
40
+ text: str
41
+ language: str | None
42
+
43
+
44
+ class SynthesizeRequest(BaseModel):
45
+ text: str = Field(min_length=1)
46
+ voice: str | None = None
47
+
48
+
49
+ async def read_bounded(file: UploadFile, max_bytes: int) -> bytes:
50
+ """Reads the upload in memory and stops as soon as it exceeds `max_bytes` (413), so a huge
51
+ body never gets buffered whole."""
52
+ chunks: list[bytes] = []
53
+ total = 0
54
+ while chunk := await file.read(READ_CHUNK):
55
+ total += len(chunk)
56
+ if total > max_bytes:
57
+ raise ApiError(413, "audio_too_large", max_bytes=max_bytes)
58
+ chunks.append(chunk)
59
+ return b"".join(chunks)
60
+
61
+
62
+ @router.post("/transcribe", response_model=TranscribeResponse)
63
+ async def transcribe(
64
+ file: UploadFile = File(...),
65
+ language: str | None = Form(default=None),
66
+ user: CurrentUser = Depends(get_current_user),
67
+ transcriber: Transcriber = Depends(get_transcriber),
68
+ ) -> TranscribeResponse:
69
+ if language is not None and not LANGUAGE.match(language):
70
+ raise ApiError(422, "invalid_language")
71
+ mime = (file.content_type or "").split(";")[0].strip().lower()
72
+ audio = AudioInput(content=await read_bounded(file, transcriber.max_bytes), mime=mime)
73
+ if audio.extension is None:
74
+ raise ApiError(415, "unsupported_audio_format", received=mime)
75
+ if not audio.content:
76
+ raise ApiError(422, "empty_audio")
77
+ try:
78
+ result = await transcriber.transcribe(audio, language=language)
79
+ except VoiceError as error:
80
+ raise _http_error(error) from None
81
+ if not result.text:
82
+ raise ApiError(422, "no_speech")
83
+ return TranscribeResponse(text=result.text, language=result.language)
84
+
85
+
86
+ @router.post("/synthesize", response_class=Response)
87
+ async def synthesize(
88
+ body: SynthesizeRequest,
89
+ user: CurrentUser = Depends(get_current_user),
90
+ synthesizer: Synthesizer = Depends(get_synthesizer),
91
+ ) -> Response:
92
+ try:
93
+ speech = await synthesizer.synthesize(body.text, voice=body.voice)
94
+ except VoiceError as error:
95
+ raise _http_error(error) from None
96
+ return Response(content=speech.audio, media_type=speech.mime, headers={"Cache-Control": "no-store"})
97
+
98
+
99
+ def _http_error(error: VoiceError) -> ApiError:
100
+ match error.code:
101
+ case VoiceErrorCode.INVALID_AUDIO:
102
+ return ApiError(422, "invalid_audio")
103
+ case VoiceErrorCode.EMPTY_TEXT:
104
+ return ApiError(422, "empty_text")
105
+ case VoiceErrorCode.TEXT_TOO_LONG:
106
+ return ApiError(413, "text_too_long")
107
+ case VoiceErrorCode.INVALID_VOICE:
108
+ return ApiError(422, "invalid_voice")
109
+ case VoiceErrorCode.RATE_LIMITED:
110
+ return ApiError(429, "provider_rate_limited", headers={"Retry-After": "5"})
111
+ case VoiceErrorCode.TIMEOUT:
112
+ return ApiError(504, "provider_timeout")
113
+ return ApiError(502 if error.retryable else 503, "provider_unavailable")
@@ -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,44 @@
1
+ """OpenAI at the HTTP level: the real SDK runs, only the network is replaced (`httpx.MockTransport`).
2
+ That way the tests check what is actually sent (multipart file name, model, language, prompt)."""
3
+
4
+ import json
5
+ import re
6
+
7
+ import httpx
8
+
9
+ FILENAME = re.compile(rb'filename="([^"]+)"')
10
+ FIELD = re.compile(rb'name="([a-z_\[\]]+)"\r\n\r\n([^\r]*)\r\n')
11
+
12
+
13
+ class FakeOpenAI:
14
+ """`status` != 200 -> that error for every call. `verbose_segments` -> whisper verbose_json answer."""
15
+
16
+ def __init__(self, *, text: str = "hola mundo", status: int = 200, body: dict | None = None, segments: list[dict] | None = None) -> None:
17
+ self.text = text
18
+ self.status = status
19
+ self.body = body
20
+ self.segments = segments
21
+ self.requests: list[dict] = []
22
+
23
+ @property
24
+ def http_client(self) -> httpx.AsyncClient:
25
+ return httpx.AsyncClient(transport=httpx.MockTransport(self._handle))
26
+
27
+ def _handle(self, request: httpx.Request) -> httpx.Response:
28
+ content = request.read()
29
+ record = {"path": request.url.path, "content_type": request.headers.get("content-type", "")}
30
+ if record["content_type"].startswith("multipart/form-data"):
31
+ record["filename"] = (FILENAME.search(content) or [None, b""])[1].decode()
32
+ record["fields"] = {k.decode(): v.decode() for k, v in FIELD.findall(content)}
33
+ else:
34
+ record["json"] = json.loads(content or b"{}")
35
+ self.requests.append(record)
36
+ if self.status != 200:
37
+ return httpx.Response(self.status, json=self.body or {"error": {"message": "nope", "type": "x", "param": None, "code": None}})
38
+ if request.url.path.endswith("/audio/transcriptions"):
39
+ if record["fields"].get("response_format") == "verbose_json":
40
+ return httpx.Response(200, json={"text": self.text, "language": "spanish", "duration": 1.0, "segments": self.segments or []})
41
+ return httpx.Response(200, json={"text": self.text})
42
+ if request.url.path.endswith("/audio/speech"):
43
+ return httpx.Response(200, content=b"ID3fake-mp3-bytes", headers={"content-type": "audio/mpeg"})
44
+ return httpx.Response(404, json={"error": {"message": "unknown path"}})