fastapi-fullstack 0.2.11__tar.gz → 0.2.12__tar.gz

{fastapi_fullstack-0.2.11 → fastapi_fullstack-0.2.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-fullstack
-Version: 0.2.11
+Version: 0.2.12
 Summary: Full-stack FastAPI + Next.js template generator with PydanticAI/LangChain agents, WebSocket streaming, 20+ enterprise integrations, and Logfire/LangSmith observability. Ship AI apps fast. CLI tool to generate production-ready FastAPI + Next.js projects with AI agents, auth, and observability.
 Project-URL: Homepage, https://github.com/vstorm-co/full-stack-ai-agent-template
 Project-URL: Documentation, https://github.com/vstorm-co/full-stack-ai-agent-template#readme

{fastapi_fullstack-0.2.11 → fastapi_fullstack-0.2.12}/fastapi_gen/cli.py

@@ -490,6 +490,12 @@ def new(output: Path | None, no_input: bool, name: str | None, minimal: bool) ->
     default=False,
     help="Enable the skills system (SkillsToolset loads SKILL.md files from backend/skills/, PydanticAI only)",
 )
+@click.option(
+    "--deep-research",
+    is_flag=True,
+    default=False,
+    help="Enable the deep research agent (TODO planner + subagents + context manager, PydanticAI only)",
+)
 @click.option("--session-management", is_flag=True, help="Enable session management")
 @click.option(
     "--reverse-proxy",
@@ -768,6 +774,7 @@ def create(
     antv_charts: bool,
     code_execution: bool,
     skills: bool,
+    deep_research: bool,
     session_management: bool,
     reverse_proxy: str,
     kubernetes: bool,
@@ -1199,6 +1206,7 @@ def create(
                 enable_antv_charts=antv_charts,
                 enable_code_execution=code_execution,
                 enable_skills=skills,
+                enable_deep_research=deep_research,
                 enable_session_management=session_management,
                 reverse_proxy=_rp_map[reverse_proxy],
                 enable_kubernetes=kubernetes,

{fastapi_fullstack-0.2.11 → fastapi_fullstack-0.2.12}/fastapi_gen/config.py

@@ -328,6 +328,7 @@ class ProjectConfig(BaseModel):
     enable_antv_charts: bool = False
     enable_code_execution: bool = False
     enable_skills: bool = False
+    enable_deep_research: bool = False
     use_telegram: bool = False
     use_slack: bool = False
     enable_cors: bool = True
@@ -490,6 +491,12 @@ class ProjectConfig(BaseModel):
                 "PydanticDeep uses Logfire for observability."
             )
 
+        if self.enable_deep_research and self.ai_framework != AIFrameworkType.PYDANTIC_AI:
+            raise ValueError(
+                "Deep research requires the PydanticAI framework. "
+                "Quick fix: set --ai-framework pydantic_ai, or drop --deep-research."
+            )
+
         # CrewAI 1.13.x pins opentelemetry-sdk<1.35 which conflicts with
         # logfire>=4.30 (needs opentelemetry-sdk>=1.39). Disable logfire when
         # using CrewAI to keep dependencies resolvable.
@@ -817,6 +824,7 @@ class ProjectConfig(BaseModel):
             "enable_antv_charts": self.enable_antv_charts,
             "enable_code_execution": self.enable_code_execution,
             "enable_skills": self.enable_skills,
+            "enable_deep_research": self.enable_deep_research,
             "enable_webhooks": self.enable_webhooks,
             # Legacy fixed values (WebSocket always uses JWT)
             "websocket_auth": "jwt",

{fastapi_fullstack-0.2.11 → fastapi_fullstack-0.2.12}/fastapi_gen/prompts.py

@@ -970,6 +970,30 @@ def prompt_skills() -> bool:
     )
 
 
+def prompt_deep_research() -> bool:
+    """Prompt for the deep research agent (PydanticAI only)."""
+    console.print()
+    console.print("[bold cyan]Deep Research Agent[/]")
+    console.print(
+        "Turns the assistant into a deep research agent: a TODO planner, "
+        "researcher/analyst/writer subagents, and an automatic context manager. "
+        "The planner delegates web work to subagents and surfaces progress in a "
+        "live research panel. PydanticAI only. Activate at runtime with "
+        "ENABLE_DEEP_RESEARCH=true."
+    )
+    console.print()
+
+    return cast(
+        bool,
+        _check_cancelled(
+            questionary.confirm(
+                "Enable the deep research agent (PydanticAI only)?",
+                default=False,
+            ).ask()
+        ),
+    )
+
+
 def prompt_langsmith() -> bool:
     """Prompt for LangSmith observability."""
     return cast(
@@ -1482,6 +1506,7 @@ def run_interactive_prompts() -> ProjectConfig:
         "enable_antv_charts": False,
         "enable_code_execution": False,
         "enable_skills": False,
+        "enable_deep_research": False,
         "rag_features": RAGFeatures(),
         "orm_type": OrmType.SQLALCHEMY,
         "sandbox_backend": "state",
@@ -1658,6 +1683,12 @@ def run_interactive_prompts() -> ProjectConfig:
         else:
             state["enable_skills"] = False
 
+    def step_deep_research() -> None:
+        if state["ai_framework"] == AIFrameworkType.PYDANTIC_AI:
+            state["enable_deep_research"] = prompt_deep_research()
+        else:
+            state["enable_deep_research"] = False
+
     def step_langsmith() -> None:
         if state["ai_framework"] in (
             AIFrameworkType.LANGCHAIN,
@@ -1731,6 +1762,7 @@ def run_interactive_prompts() -> ProjectConfig:
         ("AntV Diagrams & Maps", step_antv_charts),
         ("Code Execution", step_code_execution),
         ("Skills System", step_skills),
+        ("Deep Research", step_deep_research),
         ("LangSmith", step_langsmith),
         ("Messaging Channels", step_channels),
         ("Teams & Billing", step_teams_billing),
@@ -1780,6 +1812,7 @@ def run_interactive_prompts() -> ProjectConfig:
     enable_antv_charts = state["enable_antv_charts"]
     enable_code_execution = state["enable_code_execution"]
     enable_skills = state["enable_skills"]
+    enable_deep_research = state["enable_deep_research"]
     rag_features = state["rag_features"]
     enable_langsmith = state["enable_langsmith"]
     use_telegram = state["use_telegram"]
@@ -1825,6 +1858,7 @@ def run_interactive_prompts() -> ProjectConfig:
         enable_antv_charts=enable_antv_charts,
         enable_code_execution=enable_code_execution,
         enable_skills=enable_skills,
+        enable_deep_research=enable_deep_research,
         use_telegram=use_telegram,
         use_slack=use_slack,
         rate_limit_requests=rate_limit_requests,

{fastapi_fullstack-0.2.11 → fastapi_fullstack-0.2.12}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-fullstack"
-version = "0.2.11"
+version = "0.2.12"
 description = "Full-stack FastAPI + Next.js template generator with PydanticAI/LangChain agents, WebSocket streaming, 20+ enterprise integrations, and Logfire/LangSmith observability. Ship AI apps fast. CLI tool to generate production-ready FastAPI + Next.js projects with AI agents, auth, and observability."
 readme = "README.md"
 requires-python = ">=3.11"

{fastapi_fullstack-0.2.11 → fastapi_fullstack-0.2.12}/template/VARIABLES.md

@@ -289,6 +289,7 @@ These variables are set automatically by the generator.
 | `enable_antv_charts` | bool | `false` | Adds the interactive `create_map` tool (Leaflet/OpenStreetMap, works out of the box) plus AntV advanced-diagram tools (flowchart, mind-map, org-chart, sankey, ...) via an `mcp-server-chart` Docker sidecar. Wired into all 5 frameworks. The AntV diagrams need the sidecar running (`docker compose --profile antv up -d`) and `ENABLE_ANTV_CHARTS=true` at runtime; maps work without it. Present in the production compose but profile-gated — off by default and publishes no host port, so it's opt-in per environment; for prod, self-host GPT-Vis-SSR via `ANTV_VIS_REQUEST_SERVER` rather than AntV's public render backend | Requires an AI framework |
 | `enable_code_execution` | bool | `false` | Adds a `run_python` tool backed by the Monty sandboxed Python interpreter (`pydantic-monty`). The model can compute projections, run aggregations, and call `create_chart`/`create_map` from inside the sandbox — charts render as interactive Recharts cards immediately. Sandbox allows `math`, `asyncio`, `json`, `datetime`, `re`; no `statistics`, `random`, `itertools`, numpy/pandas. Activated at runtime with `ENABLE_CODE_EXECUTION=true`. **PydanticAI only.** Temporary shim — swap to the official `CodeExecutionToolset` when it ships in pydantic-ai | Requires `use_pydantic_ai` |
 | `enable_skills` | bool | `false` | Adds a `pydantic-ai-skills` `SkillsToolset` that loads `SKILL.md` files from `backend/skills/` as agent tools (the model picks a skill, then follows its instructions). Ships the loader only — drop your own skills into `backend/skills/`; the toolset no-ops when the directory is empty. Pairs well with `enable_code_execution` for skills that compute. **PydanticAI only.** | Requires `use_pydantic_ai` |
+| `enable_deep_research` | bool | `false` | Turns the assistant into a deep research agent: a TODO planner (`pydantic-ai-todo`), researcher/analyst/writer subagents (`subagents-pydantic-ai`), and an automatic context manager (`summarization-pydantic-ai`). The planner delegates web work to subagents and streams a live research panel (plan checklist, subagent status, context-usage meter). TODO state persists in PostgreSQL when available, else in memory. Activated at runtime with `ENABLE_DEEP_RESEARCH=true`; the client can opt a single turn out with `deep_research=false`. **PydanticAI only.** | Requires `use_pydantic_ai` |
 
 **Notes:**
 

{fastapi_fullstack-0.2.11 → fastapi_fullstack-0.2.12}/template/cookiecutter.json

@@ -94,6 +94,7 @@
   "enable_antv_charts": false,
   "enable_code_execution": false,
   "enable_skills": false,
+  "enable_deep_research": false,
   "enable_webhooks": false,
   "websocket_auth": "jwt",
   "websocket_auth_jwt": true,

{fastapi_fullstack-0.2.11 → fastapi_fullstack-0.2.12}/template/hooks/post_gen_project.py

@@ -50,6 +50,7 @@ enable_charts = "{{ cookiecutter.enable_charts }}" == "True"
 charts_channel_png = "{{ cookiecutter.charts_channel_png }}" == "True"
 enable_antv_charts = "{{ cookiecutter.enable_antv_charts }}" == "True"
 enable_code_execution = "{{ cookiecutter.enable_code_execution }}" == "True"
+enable_deep_research = "{{ cookiecutter.enable_deep_research }}" == "True"
 use_pydantic_deep = "{{ cookiecutter.use_pydantic_deep }}" == "True"
 use_telegram = "{{ cookiecutter.use_telegram }}" == "True"
 use_slack = "{{ cookiecutter.use_slack }}" == "True"
@@ -156,6 +157,14 @@ if not enable_antv_charts:
         remove_file(os.path.join(frontend_src, "components", "chat", "map-message.tsx"))
 if not enable_code_execution:
     remove_file(os.path.join(backend_app, "agents", "tools", "code_execution.py"))
+if not enable_deep_research:
+    remove_file(os.path.join(backend_app, "services", "research.py"))
+    remove_file(os.path.join(backend_app, "db", "todo_pool.py"))
+    if use_frontend:
+        frontend_src = os.path.join(os.getcwd(), "frontend", "src")
+        remove_file(os.path.join(frontend_src, "components", "chat", "research-panel.tsx"))
+        remove_file(os.path.join(frontend_src, "stores", "research-store.ts"))
+        remove_file(os.path.join(frontend_src, "stores", "chat-mode-store.ts"))
 
 # --- No-AI mode: remove all AI/chat/conversation files ---
 if not use_ai:
@@ -440,12 +449,14 @@ if not use_any_background_tasks:
     remove_file(os.path.join(worker_dir, "taskiq_app.py"))
     remove_file(os.path.join(worker_dir, "arq_app.py"))
     remove_dir(os.path.join(worker_dir, "tasks"))
+    remove_file(os.path.join(backend_tests, "test_worker_taskiq.py"))
 else:
     if not use_celery:
         remove_file(os.path.join(worker_dir, "celery_app.py"))
     if not use_taskiq:
         remove_file(os.path.join(worker_dir, "taskiq_app.py"))
         remove_file(os.path.join(worker_dir, "tasks", "schedules.py"))
+        remove_file(os.path.join(backend_tests, "test_worker_taskiq.py"))
     if not use_arq:
         remove_file(os.path.join(worker_dir, "arq_app.py"))
 

{fastapi_fullstack-0.2.11 → fastapi_fullstack-0.2.12}/template/{{cookiecutter.project_slug}}/Makefile

@@ -283,8 +283,8 @@ taskiq-scheduler:
 
 # === Docker: Backend (Development) ===
 docker-up:
-	docker-compose build app
-	docker-compose up -d
+	docker compose build app
+	docker compose up -d
 	@echo ""
 	@echo "✅ Backend services started!"
 	@echo "   API: http://localhost:{{ cookiecutter.backend_port }}"
@@ -300,25 +300,25 @@ docker-up:
 {%- endif %}
 
 docker-down:
-	docker-compose down
+	docker compose down
 {%- if cookiecutter.use_frontend %}
-	docker-compose -f docker-compose.frontend.yml down 2>/dev/null || true
+	docker compose -f docker-compose.frontend.yml down 2>/dev/null || true
 {%- endif %}
 
 docker-logs:
-	docker-compose logs -f
+	docker compose logs -f
 
 docker-build:
-	docker-compose build
+	docker compose build
 
 docker-shell:
-	docker-compose exec app /bin/bash
+	docker compose exec app /bin/bash
 
 {%- if cookiecutter.use_frontend %}
 
 # === Docker: Frontend (Development) ===
 docker-frontend:
-	docker-compose -f docker-compose.frontend.yml up -d
+	docker compose -f docker-compose.frontend.yml up -d
 	@echo ""
 	@echo "✅ Frontend started!"
 	@echo "   URL: http://localhost:{{ cookiecutter.frontend_port }}"
@@ -326,18 +326,18 @@ docker-frontend:
 	@echo "Note: Backend must be running (make docker-up)"
 
 docker-frontend-down:
-	docker-compose -f docker-compose.frontend.yml down
+	docker compose -f docker-compose.frontend.yml down
 
 docker-frontend-logs:
-	docker-compose -f docker-compose.frontend.yml logs -f
+	docker compose -f docker-compose.frontend.yml logs -f
 
 docker-frontend-build:
-	docker-compose -f docker-compose.frontend.yml build
+	docker compose -f docker-compose.frontend.yml build
 {%- endif %}
 
 # === Docker: Production (with Traefik) ===
 docker-prod:
-	docker-compose -f docker-compose.prod.yml up -d
+	docker compose -f docker-compose.prod.yml up -d
 	@echo ""
 	@echo "✅ Production services started with Traefik!"
 	@echo ""
@@ -352,36 +352,36 @@ docker-prod:
 	@echo "   Traefik: https://traefik.$$DOMAIN"
 
 docker-prod-down:
-	docker-compose -f docker-compose.prod.yml down
+	docker compose -f docker-compose.prod.yml down
 
 docker-prod-logs:
-	docker-compose -f docker-compose.prod.yml logs -f
+	docker compose -f docker-compose.prod.yml logs -f
 
 docker-prod-build:
-	docker-compose -f docker-compose.prod.yml build
+	docker compose -f docker-compose.prod.yml build
 
 {%- if cookiecutter.use_postgresql %}
 
 # === Docker: Individual Services ===
 docker-db:
-	docker-compose up -d db
+	docker compose up -d db
 	@echo ""
 	@echo "✅ PostgreSQL started on port 5432"
 	@echo "   Connection: postgresql://postgres:postgres@localhost:5432/{{ cookiecutter.project_slug }}"
 
 docker-db-stop:
-	docker-compose stop db
+	docker compose stop db
 {%- endif %}
 
 {%- if cookiecutter.enable_redis %}
 
 docker-redis:
-	docker-compose up -d redis
+	docker compose up -d redis
 	@echo ""
 	@echo "✅ Redis started on port 6379"
 
 docker-redis-stop:
-	docker-compose stop redis
+	docker compose stop redis
 {%- endif %}
 
 {%- if cookiecutter.use_frontend %}

{fastapi_fullstack-0.2.11 → fastapi_fullstack-0.2.12}/template/{{cookiecutter.project_slug}}/backend/.env.example

@@ -259,6 +259,12 @@ ENABLE_CODE_EXECUTION=true
 CODE_EXECUTION_TIMEOUT_SECS=10
 CODE_EXECUTION_MAX_ALLOCATIONS=50000000
 {%- endif %}
+{%- if cookiecutter.enable_deep_research %}
+
+ENABLE_DEEP_RESEARCH=true
+DEEP_RESEARCH_MAX_TOKENS=120000
+DEEP_RESEARCH_COMPRESS_THRESHOLD=0.8
+{%- endif %}
 {%- if cookiecutter.enable_langsmith %}
 
 # === LangSmith Observability ===

{fastapi_fullstack-0.2.11 → fastapi_fullstack-0.2.12}/template/{{cookiecutter.project_slug}}/backend/app/agents/assistant.py

@@ -48,6 +48,9 @@ from app.agents.prompts import DEFAULT_SYSTEM_PROMPT
 {%- if cookiecutter.enable_rag %}
 from app.agents.prompts import get_system_prompt_with_rag
 {%- endif %}
+{%- if cookiecutter.enable_deep_research %}
+from app.agents.prompts import get_research_prompt
+{%- endif %}
 from app.agents.tools import get_current_datetime
 from app.agents.tools.ask_user_tool import MAX_QUESTIONS, QuestionItem, format_answers
 {%- if cookiecutter.enable_rag %}
@@ -167,6 +170,32 @@ class Deps:
 {%- if cookiecutter.enable_code_execution %}
     emit_tool_event: EmitToolEvent | None = None
 {%- endif %}
+{%- if cookiecutter.enable_deep_research %}
+    # Required by SubAgentDepsProtocol; kept empty (capabilities carry the agents).
+    subagents: dict[str, Any] = field(default_factory=dict)
+
+    def clone_for_subagent(self, max_depth: int = 0) -> "Deps":
+        """Create isolated deps for a delegated subagent.
+
+        Required by ``subagents-pydantic-ai`` (``SubAgentDepsProtocol``). Shares
+        the lightweight context but drops the interactive hooks and hands over an
+        empty ``subagents`` dict when ``max_depth <= 0`` so a subagent cannot
+        recurse.
+        """
+        return Deps(
+            user_id=self.user_id,
+            user_name=self.user_name,
+{%- if cookiecutter.enable_teams and cookiecutter.enable_rag %}
+            kb_collection_names=self.kb_collection_names,
+{%- endif %}
+            metadata=self.metadata,
+            ask_user=None,
+{%- if cookiecutter.enable_code_execution %}
+            emit_tool_event=None,
+{%- endif %}
+            subagents={} if max_depth <= 0 else self.subagents,
+        )
+{%- endif %}
 
 
 class AssistantAgent:
@@ -181,7 +210,15 @@ class AssistantAgent:
         temperature: float | None = None,
         system_prompt: str | None = None,
         thinking_effort: str | None = None,
+{%- if cookiecutter.enable_deep_research %}
+        deep_research: bool = False,
+        research_capabilities: list[Any] | None = None,
+{%- endif %}
     ):
+{%- if cookiecutter.enable_deep_research %}
+        self.deep_research = deep_research
+        self.research_capabilities = research_capabilities or []
+{%- endif %}
         self.model_name = model_name or settings.AI_MODEL
         # ``temperature`` stays ``None`` when caller didn't set it — don't fall
         # back to settings.AI_TEMPERATURE here. Reasoning/o-series models
@@ -191,10 +228,22 @@ class AssistantAgent:
         self.thinking_effort = thinking_effort if thinking_effort is not None else (
             settings.AI_THINKING_EFFORT if settings.AI_THINKING_ENABLED else None
         )
+{%- if cookiecutter.enable_deep_research %}
+        if deep_research:
+            self.system_prompt = system_prompt or get_research_prompt()
+{%- if cookiecutter.enable_rag %}
+        else:
+            self.system_prompt = system_prompt or get_system_prompt_with_rag()
+{%- else %}
+        else:
+            self.system_prompt = system_prompt or DEFAULT_SYSTEM_PROMPT
+{%- endif %}
+{%- else %}
 {%- if cookiecutter.enable_rag %}
         self.system_prompt = system_prompt or get_system_prompt_with_rag()
 {%- else %}
         self.system_prompt = system_prompt or DEFAULT_SYSTEM_PROMPT
+{%- endif %}
 {%- endif %}
         self._agent: Agent[Deps, str] | None = None
 
@@ -202,14 +251,28 @@ class AssistantAgent:
         """Create and configure the PydanticAI agent."""
         model = _build_model(self.model_name)
 
-        capabilities = [ReinjectSystemPrompt()]
+        capabilities: list[Any] = [ReinjectSystemPrompt()]
         if self.thinking_effort:
-            capabilities.append(Thinking(effort=self.thinking_effort))
+            capabilities.append(Thinking(effort=self.thinking_effort))  # ty: ignore[invalid-argument-type]
+{%- if cookiecutter.enable_web_search or cookiecutter.enable_web_fetch %}
+        # Local DuckDuckGo / fetch (the installed extras) — works uniformly across
+        # all providers, unlike provider-native web search.
+{%- if cookiecutter.enable_deep_research %}
+        if not self.deep_research:
+{%- if cookiecutter.enable_web_search %}
+            capabilities.append(WebSearch(native=False, local="duckduckgo"))
+{%- endif %}
+{%- if cookiecutter.enable_web_fetch %}
+            capabilities.append(WebFetch(native=False, local=True))
+{%- endif %}
+{%- else %}
 {%- if cookiecutter.enable_web_search %}
-        capabilities.append(WebSearch())
+        capabilities.append(WebSearch(native=False, local="duckduckgo"))
 {%- endif %}
 {%- if cookiecutter.enable_web_fetch %}
-        capabilities.append(WebFetch())
+        capabilities.append(WebFetch(native=False, local=True))
+{%- endif %}
+{%- endif %}
 {%- endif %}
 
         # The unified ``Thinking()`` capability enables reasoning, but for the
@@ -241,6 +304,10 @@ class AssistantAgent:
         if skills_dir.exists():
             toolsets.append(SkillsToolset(directories=[str(skills_dir)]))
 {%- endif %}
+{%- if cookiecutter.enable_deep_research %}
+
+        capabilities.extend(self.research_capabilities)
+{%- endif %}
 
         agent = Agent[Deps, str](
             model=model,
@@ -530,6 +597,10 @@ def get_agent(
     model_name: str | None = None,
     thinking_effort: str | None = None,
     temperature: float | None = None,
+{%- if cookiecutter.enable_deep_research %}
+    deep_research: bool = False,
+    research_capabilities: list[Any] | None = None,
+{%- endif %}
 ) -> AssistantAgent:
     """Factory function to create an AssistantAgent.
 
@@ -538,6 +609,12 @@ def get_agent(
         thinking_effort: Override thinking effort ("low", "medium", "high", or None to disable).
         temperature: Sampling temperature (typically 0.0-2.0). ``None`` falls back to
             ``settings.AI_TEMPERATURE``.
+{%- if cookiecutter.enable_deep_research %}
+        deep_research: Build the planner persona and drop the planner's own web
+            tools so it delegates to subagents.
+        research_capabilities: Pre-built deep-research capabilities (
+            subagents, context manager), already ordered with the context manager last.
+{%- endif %}
 
     Returns:
         Configured AssistantAgent instance.
@@ -546,6 +623,10 @@ def get_agent(
         model_name=model_name,
         thinking_effort=thinking_effort,
         temperature=temperature,
+{%- if cookiecutter.enable_deep_research %}
+        deep_research=deep_research,
+        research_capabilities=research_capabilities,
+{%- endif %}
     )
 
 

{fastapi_fullstack-0.2.11 → fastapi_fullstack-0.2.12}/template/{{cookiecutter.project_slug}}/backend/app/agents/prompts.py

@@ -171,3 +171,42 @@ Retrieval budget: start with one focused search using short, distinctive keyword
 Citations: when you use retrieved documents, attach numbered references like [1], [2] to the specific claims they support, and list those sources at the end (filename, plus page if available). Cite only sources that appear in the search results — never fabricate citations, filenames, or page numbers.
 
 Missing evidence is not automatically a "no". If the documents don't cover the question, say briefly what you couldn't find, then still help: answer from general knowledge where that's appropriate (and note that you're doing so), or ask for the specific document or detail you'd need."""
+{%- if cookiecutter.enable_deep_research %}
+
+
+RESEARCH_SYSTEM_PROMPT = """You are a deep-research agent. You answer a research question by planning the work, delegating it to specialist subagents in parallel, and composing a well-sourced report. Work as a project lead, not a lone writer.
+
+# How to run a research task
+The user has explicitly switched on deep research, so ALWAYS run the full research flow for their request — plan, delegate to subagents, then synthesize a cited report. Never short-circuit with a quick direct answer, even if you think you already know it.
+
+0. **Clarify the scope with the user first.** Most research requests arrive under-specified, and researching the wrong thing wastes a lot of work. So BEFORE planning, judge whether you have enough to research well — and if not, call the `ask_user` tool ONCE up front with 2-4 batched questions, then wait for the answers before doing anything else. Treat a request as under-specified whenever the user hasn't pinned down the details that would materially change what you research. For a product, topic, or vendor (a car, gadget, software, company…), that usually means: the exact variant/generation and model year, new vs. used (or budget), the region/market, and the decision or use-case they care about (buying, comparing alternatives, reliability, running costs, etc.). Offer sensible `options` on each question so the user can answer in one click, and keep `allow_custom` on. Only skip the questions when the user already supplied those specifics, or explicitly asked for a general/high-level overview. When in doubt, ASK — a quick clarification is far cheaper than a misdirected report.
+1. **Plan.** Break the question into 3 to 6 concrete research steps and record them as a TODO plan. Seed the plan by calling `add_todo` once per step (each with a short `content` and an `active_form`). Do NOT use `write_todos` — it replaces the whole list silently and the user won't see your plan form. As you work, call `update_todo_status` to flip each step pending → in_progress → completed.
+2. **Delegate in parallel.** Use the `task` tool to hand each research step to the right subagent, and ALWAYS pass `mode="async"` so steps run concurrently and the user can watch them progress. Spawn the independent steps together, then call `wait_tasks` (with the returned task ids) to collect their results. Do not delegate the same step twice.
+   - `researcher` — gathers facts from the web; returns findings with source URLs/titles. Use it for anything needing current or external information.
+   - `analyst` — reasons over gathered findings: compares, computes, spots trends and contradictions. Text-only, no web.
+   - `writer` — composes the final structured report from the findings + analysis. Text-only.
+3. **Synthesize.** Once the subagents return, mark the remaining TODOs completed and write the final answer yourself (or via the `writer`), integrating the findings.
+
+# The report
+- Lead with a short direct answer, then the supporting detail.
+- Attach numbered citations `[1]`, `[2]` to specific claims, and end with a `Sources` list (title + URL) drawn ONLY from what the researcher actually returned. Never invent a source, URL, or figure.
+- When the findings contain comparable numbers (a trend, a ranking, a breakdown), render at least one chart so the report has a visual. Describe the chart's takeaway in a sentence; don't paste its JSON.
+
+# Cost discipline
+Keep the plan tight (3 to 6 steps), give each subagent one clear job, and don't spawn more researchers than the question needs — parallel subagents multiply token cost. Prefer one focused web pass per sub-question over many rephrasings."""
+
+
+def get_research_prompt() -> str:
+    """Return the deep-research system prompt, or the default prompt when the
+    feature is disabled at runtime.
+    """
+    from app.core.config import settings
+
+    if not settings.ENABLE_DEEP_RESEARCH:
+{%- if cookiecutter.enable_rag %}
+        return get_system_prompt_with_rag()
+{%- else %}
+        return DEFAULT_SYSTEM_PROMPT
+{%- endif %}
+    return RESEARCH_SYSTEM_PROMPT
+{%- endif %}

{fastapi_fullstack-0.2.11 → fastapi_fullstack-0.2.12}/template/{{cookiecutter.project_slug}}/backend/app/agents/pydantic_deep_assistant.py

@@ -56,7 +56,7 @@ logger = logging.getLogger(__name__)
 
 # Map LLM_PROVIDER settings value → pydantic-ai provider prefix
 _PROVIDER_PREFIXES: dict[str, str] = {
-    "openai": "openai",
+    "openai": "openai-responses",
     "anthropic": "anthropic",
     "google": "google-gla",  # Google AI (Gemini) via GOOGLE_API_KEY
     "openrouter": "openrouter",
@@ -201,16 +201,21 @@ class PydanticDeepAssistant:
     def _get_model_string(self) -> str:
         """Build pydantic-ai model string with provider prefix.
 
-        If the model name already contains ':', returns it unchanged.
-        Otherwise prepends the provider prefix from LLM_PROVIDER setting.
+        If the model name already contains ':', it is used as-is — except a bare
+        ``openai:`` prefix, which is rewritten to ``openai-responses:`` so it hits
+        the Responses API (tools + reasoning models). Otherwise the prefix from the
+        LLM_PROVIDER setting is prepended.
 
         Examples:
-            "gpt-5.5"             → "openai:gpt-5.5"
+            "gpt-5.5"             → "openai-responses:gpt-5.5"
             "claude-opus-4-7"     → "anthropic:claude-opus-4-7"
             "gemini-2.5-flash"    → "google-gla:gemini-2.5-flash"
-            "openai:gpt-5.5"      → "openai:gpt-5.5"  (unchanged)
+            "openai:gpt-5.5"      → "openai-responses:gpt-5.5"  (rewritten)
+            "openai-responses:gpt-5.5" → "openai-responses:gpt-5.5"  (unchanged)
         """
         if ":" in self.model_name:
+            if self.model_name.startswith("openai:"):
+                return f"openai-responses:{self.model_name.removeprefix('openai:')}"
             return self.model_name
         prefix = _PROVIDER_PREFIXES.get(settings.LLM_PROVIDER, settings.LLM_PROVIDER)
         return f"{prefix}:{self.model_name}"

{fastapi_fullstack-0.2.11 → fastapi_fullstack-0.2.12}/template/{{cookiecutter.project_slug}}/backend/app/api/exception_handlers.py

@@ -105,6 +105,8 @@ def register_exception_handlers(app: FastAPI) -> None:
 
     Call this after creating the FastAPI application instance.
     """
-    app.add_exception_handler(AppException, app_exception_handler)
+    # Handler returns None for WebSocket connections (no JSONResponse there),
+    # which Starlette's HTTP-handler type doesn't model.
+    app.add_exception_handler(AppException, app_exception_handler)  # ty: ignore[invalid-argument-type]
     # Uncomment to catch all unhandled exceptions:
     # app.add_exception_handler(Exception, unhandled_exception_handler)

{fastapi_fullstack-0.2.11 → fastapi_fullstack-0.2.12}/template/{{cookiecutter.project_slug}}/backend/app/api/routes/v1/admin_users.py

@@ -138,52 +138,52 @@ async def impersonate_user(
 {%- elif cookiecutter.use_sqlite %}
 
 @router.get("", response_model=AdminUserList)
-def list_users(
+async def list_users(
     _: CurrentAdmin,
     service: UserSvc,
     skip: int = Query(0, ge=0),
     limit: int = Query(50, ge=1, le=500),
     search: str | None = Query(None),
 ) -> Any:
-    return service.admin_list_with_counts(skip=skip, limit=limit, search=search)
+    return await service.admin_list_with_counts(skip=skip, limit=limit, search=search)
 
 
 @router.get("/{user_id}", response_model=UserRead)
-def get_user(
+async def get_user(
     user_id: str,
     _: CurrentAdmin,
     service: UserSvc,
 ) -> Any:
-    return service.get_by_id(user_id)
+    return await service.get_by_id(user_id)
 
 
 @router.patch("/{user_id}", response_model=UserRead)
-def update_user(
+async def update_user(
     user_id: str,
     user_in: UserUpdate,
     _: CurrentAdmin,
     service: UserSvc,
 ) -> Any:
-    return service.update(user_id, user_in)
+    return await service.update(user_id, user_in)
 
 
 @router.delete("/{user_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None)
-def delete_user(
+async def delete_user(
     user_id: str,
     _: CurrentAdmin,
     service: UserSvc,
 ) -> None:
-    service.get_by_id(user_id)
-    service.delete(user_id)
+    await service.get_by_id(user_id)
+    await service.delete(user_id)
 
 
 @router.post("/{user_id}/impersonate", response_model=dict)
-def impersonate_user(
+async def impersonate_user(
     user_id: str,
     admin: CurrentAdmin,
     service: UserSvc,
 ) -> Any:
-    target = service.get_by_id(user_id)
+    target = await service.get_by_id(user_id)
     token = create_access_token(
         subject=str(target.id),
         expires_delta=timedelta(hours=1),