feat(agents): migrate remaining one-shot LLM calls to Pydantic AI agents (#147)

[Jose-Gael-Cruz-Lopez]

Closes#147 (part of the Agent-migration epic #152, milestone "Agent migration surfaces + staging + performance").

What

Retires the last three direct call_gemini* production call sites onto typed Pydantic AI agents. After this, the only backend gemini_service callers are the intentional legacy chat fallback (routes/learn.py, retired in the #151 cutover) and tests.

Surface	Before	After
routes/study_guide.py	call_gemini_json(prompt)	agents/study_guide.py (study_guide_agent)
routes/social.py	call_gemini(...)	agents/social_summary.py (social_summary_agent)
main.py/api/gemini-test	call_gemini(...)	agents/health.py (health_probe_agent)

Notes

• Contracts unchanged.StudyGuide/Topic mirror the existing exam/due_date/overview/topics JSON; the route model_dump()s straight into study_guides.content, so cached reads and the frontend are unaffected. /overview and /api/gemini-test response shapes are identical.
• Study-guide failures now return 502 (per the issue's audit note) instead of a raw 500.
• Social summary keeps the get_cached_summary → run → save_summary flow and the graceful fallback string (still 200) on agent failure.
• Health probe runs through the shared GoogleProvider from agents/_providers.py, so a green check means the real agent seam reaches Gemini. Admin-before-spend gate preserved.
• Sync→async bridge:agents/_run.py::run_agent_sync wraps asyncio.run for the three sync handlers (their surrounding httpx table() access stays synchronous). Handlers are not converted to async def.
• _providers.py registers study_guide (gemini-2.5-flash) and social_summary (gemini-2.5-flash-lite), both env-overridable via SAPLING_MODEL_*.

Testing

• Updated test_study_guide_routes.py and test_gemini_test_auth.py to mock the agents; added test_oneshot_agents.py covering the 502 path, social cache-hit/miss/agent-failure, and the StudyGuide → legacy-dict shape.
• Full backend suite: 829 passed (the 2 test_storage_service failures are pre-existing on main — missing SUPABASE env — verified by stash-and-run).
• ruff check clean on all changed files.

Out of scope (separate issues): quiz, documents, calendar, flashcards, course_context_service, the learn.py legacy fallback, and deleting gemini_service.py (#151).

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added AI-generated study guides and social room overview summaries using structured, typed outputs.
  • Updated the admin Gemini health check to run through the app’s agent-based flow (preserving {ok, reply} / {ok, error}).
• Bug Fixes
  • Improved resilience: cache-first behavior remains, and summary generation still falls back to the legacy contract when AI fails.
  • Study guide generation now returns a clearer 502 error when generation cannot be completed.
• Tests
  • Expanded and updated tests for agent execution, caching behavior, failure handling, and typed output shape serialization.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 36b5c5f0-1c9e-4623-ba33-a9861a267129

📥 Commits

Reviewing files that changed from the base of the PR and between 1b816cecd1924d4c086d307a58ca5275e00d11c7 and 09ce721.

📒 Files selected for processing (12)

• backend/agents/_providers.py
• backend/agents/_run.py
• backend/agents/health.py
• backend/agents/social_summary.py
• backend/agents/study_guide.py
• backend/main.py
• backend/routes/social.py
• backend/routes/study_guide.py
• backend/tests/test_gemini_test_auth.py
• backend/tests/test_oneshot_agents.py
• backend/tests/test_study_guide_routes.py
• specs/147-oneshot-llm-agents.md

✅ Files skipped from review due to trivial changes (1)

• specs/147-oneshot-llm-agents.md

🚧 Files skipped from review as they are similar to previous changes (10)

• backend/agents/_run.py
• backend/agents/health.py
• backend/agents/study_guide.py
• backend/routes/study_guide.py
• backend/tests/test_study_guide_routes.py
• backend/routes/social.py
• backend/main.py
• backend/tests/test_oneshot_agents.py
• backend/agents/social_summary.py
• backend/agents/_providers.py

---

📝 Walkthrough

Walkthrough

This PR migrates three remaining one-shot Gemini call sites to typed Pydantic AI agents, adds a shared sync bridge, updates provider defaults, and rewires the affected routes, health check, tests, and spec.

Changes

Agent migration

Layer / File(s)	Summary
Task defaults and sync bridge backend/agents/_providers.py, backend/agents/_run.py	Adds study_guide and social_summary to AgentTask and _DEFAULTS, and introduces run_agent_sync for running agent coroutines from sync handlers.
Health probe agent and gemini-test endpoint backend/agents/health.py, backend/main.py, backend/tests/test_gemini_test_auth.py	Adds health_probe_agent, rewires /api/gemini-test to run it via run_agent_sync, and updates auth/success/failure tests.
Social summary agent and room overview route backend/agents/social_summary.py, backend/routes/social.py, backend/tests/test_oneshot_agents.py	Adds SocialSummary and social_summary_agent, switches the overview cache-miss path to agent execution, and adds cache-hit/miss/error coverage.
Study guide agent and generation route backend/agents/study_guide.py, backend/routes/study_guide.py, backend/tests/test_study_guide_routes.py, backend/tests/test_oneshot_agents.py	Adds Topic/StudyGuide and study_guide_agent, rewires generation to agent execution with 502 failure handling, and updates route/output-shape tests.
Migration spec document specs/147-oneshot-llm-agents.md	Documents the migration requirements and acceptance criteria.

Estimated code review effort: 3 (Moderate) | ~30 minutes

Sequence Diagram(s)

sequenceDiagram
participant Client
participant Route as sync route handler
participant run_agent_sync
participant Agent as Pydantic AI agent
participant Supabase
Client->>Route: HTTP request
Route->>Route: build deps / prompt
Route->>run_agent_sync: run_agent_sync(agent.run(...))
run_agent_sync->>Agent: run(input)
alt success
Agent-->>run_agent_sync: typed output
run_agent_sync-->>Route: result
Route->>Supabase: persist or load cached data
Route-->>Client: 200 response
else failure
Agent-->>run_agent_sync: exception
Route-->>Client: 502 or fallback response
end

Loading

Possibly related issues

• [P1] Agent migration: retire call_gemini* + gemini_service.py (final cutover) #151: Directly matches the remaining one-shot Gemini-to-agent migration across routes and the health probe seam.
• [EPIC] Agent migration — retire gemini_service as the primary LLM seam #152: Same code-level cutover for routes/study_guide.py, routes/social.py, and backend/main.py.

Possibly related PRs

• SaplingLearn/Sapling#67: Both change the shared per-task model-selection layer in backend/agents/_providers.py.
• SaplingLearn/Sapling#71: Both extend the shared AgentTask/default-model mapping in _providers.py.
• SaplingLearn/Sapling#219: Both modify /api/gemini-test behavior and its tests.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 23.81% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: migrating remaining one-shot LLM calls to Pydantic AI agents.
Description check	✅ Passed	The description covers the goal, key changes, testing, and related issue, though it doesn't strictly follow the template headings.
Linked Issues check	✅ Passed	The three targeted call sites were migrated off direct call_gemini* usage, error handling matches the issue, and remaining callers are legacy fallback and tests.
Out of Scope Changes check	✅ Passed	The added modules, bridge helper, tests, and spec document all support the stated migration and do not appear unrelated.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/147-oneshot-llm-agents

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cloudflare-workers-and-pages]

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	frontend-staging	09ce721	Commit Preview URL Branch Preview URL	Jul 01 2026, 02:27 PM

[coderabbitai]

🧹 Nitpick comments (2)

backend/agents/social_summary.py (1)

35-35: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Duplicate prompt-hash boilerplate across agents.

The hashlib.sha256(...).hexdigest()[:12] pattern for _PROMPT_HASH is repeated verbatim in backend/agents/study_guide.py. As more agents are added under this pattern, consider extracting a small shared helper (e.g. agents/_providers.py::prompt_version(prompt: str) -> str) to avoid re-implementing this in every new agent module.

♻️ Suggested helper

+# agents/_providers.py+def prompt_version(system_prompt: str) -> str:+ import hashlib+ return hashlib.sha256(system_prompt.encode("utf-8")).hexdigest()[:12]

-import hashlib-
from pydantic import BaseModel, Field
from pydantic_ai import Agent
-from agents._providers import model_for+from agents._providers import model_for, prompt_version
from agents.deps import SaplingDeps
...
-_PROMPT_HASH = hashlib.sha256(_SYSTEM_PROMPT.encode("utf-8")).hexdigest()[:12]+_PROMPT_HASH = prompt_version(_SYSTEM_PROMPT)

Also applies to: 38-44

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@backend/agents/social_summary.py` at line 35, Duplicate prompt-hash
boilerplate is repeated in social_summary and study_guide; extract the shared
SHA-256 truncation logic into a small helper such as
agents/_providers.py::prompt_version(prompt: str) -> str, then update
_PROMPT_HASH in each agent module to call it instead of re-implementing
hashlib.sha256(...).hexdigest()[:12].

backend/agents/study_guide.py (1)

43-62: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

LGTM! Typed output correctly mirrors the legacy JSON contract, matching result.output.model_dump() usage in routes/study_guide.py. Same prompt-hash duplication note as in agents/social_summary.py applies here (see that comment) — extracting a shared helper would avoid re-implementing this in future agents.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@backend/agents/study_guide.py` around lines 43 - 62, The prompt hash logic is
duplicated in study_guide agent setup and should be centralized to match the
shared pattern used by other agents. Extract the SHA-256 prompt-version
calculation into a reusable helper and have study_guide_agent build its metadata
from that helper instead of re-implementing the hash inline. Keep the existing
_SYSTEM_PROMPT, _PROMPT_HASH, and study_guide_agent symbols as the integration
points when refactoring.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@backend/agents/social_summary.py`:
- Line 35: Duplicate prompt-hash boilerplate is repeated in social_summary and
study_guide; extract the shared SHA-256 truncation logic into a small helper
such as agents/_providers.py::prompt_version(prompt: str) -> str, then update
_PROMPT_HASH in each agent module to call it instead of re-implementing
hashlib.sha256(...).hexdigest()[:12].
In `@backend/agents/study_guide.py`:
- Around line 43-62: The prompt hash logic is duplicated in study_guide agent
setup and should be centralized to match the shared pattern used by other
agents. Extract the SHA-256 prompt-version calculation into a reusable helper
and have study_guide_agent build its metadata from that helper instead of
re-implementing the hash inline. Keep the existing _SYSTEM_PROMPT, _PROMPT_HASH,
and study_guide_agent symbols as the integration points when refactoring.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: e33a7124-0193-4aba-988a-15fecc891aae

📥 Commits

Reviewing files that changed from the base of the PR and between d86edde and 1b816cecd1924d4c086d307a58ca5275e00d11c7.

📒 Files selected for processing (12)

• backend/agents/_providers.py
• backend/agents/_run.py
• backend/agents/health.py
• backend/agents/social_summary.py
• backend/agents/study_guide.py
• backend/main.py
• backend/routes/social.py
• backend/routes/study_guide.py
• backend/tests/test_gemini_test_auth.py
• backend/tests/test_oneshot_agents.py
• backend/tests/test_study_guide_routes.py
• specs/147-oneshot-llm-agents.md

[Jose-Gael-Cruz-Lopez]

Closes#147 (part of the Agent-migration epic #152, milestone "Agent migration surfaces + staging + performance").

What

Retires the last three direct call_gemini* production call sites onto typed Pydantic AI agents. After this, the only backend gemini_service callers are the intentional legacy chat fallback (routes/learn.py, retired in the #151 cutover) and tests.

Surface	Before	After
routes/study_guide.py	call_gemini_json(prompt)	agents/study_guide.py (study_guide_agent)
routes/social.py	call_gemini(...)	agents/social_summary.py (social_summary_agent)
main.py/api/gemini-test	call_gemini(...)	agents/health.py (health_probe_agent)

Notes

• Contracts unchanged.StudyGuide/Topic mirror the existing exam/due_date/overview/topics JSON; the route model_dump()s straight into study_guides.content, so cached reads and the frontend are unaffected. /overview and /api/gemini-test response shapes are identical.
• Study-guide failures now return 502 (per the issue's audit note) instead of a raw 500.
• Social summary keeps the get_cached_summary → run → save_summary flow and the graceful fallback string (still 200) on agent failure.
• Health probe runs through the shared GoogleProvider from agents/_providers.py, so a green check means the real agent seam reaches Gemini. Admin-before-spend gate preserved.
• Sync→async bridge:agents/_run.py::run_agent_sync wraps asyncio.run for the three sync handlers (their surrounding httpx table() access stays synchronous). Handlers are not converted to async def.
• _providers.py registers study_guide (gemini-2.5-flash) and social_summary (gemini-2.5-flash-lite), both env-overridable via SAPLING_MODEL_*.

Testing

• Updated test_study_guide_routes.py and test_gemini_test_auth.py to mock the agents; added test_oneshot_agents.py covering the 502 path, social cache-hit/miss/agent-failure, and the StudyGuide → legacy-dict shape.
• Full backend suite: 829 passed (the 2 test_storage_service failures are pre-existing on main — missing SUPABASE env — verified by stash-and-run).
• ruff check clean on all changed files.

Out of scope (separate issues): quiz, documents, calendar, flashcards, course_context_service, the learn.py legacy fallback, and deleting gemini_service.py (#151).

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added AI-generated study guides and social room overview summaries using structured, typed outputs.
  • Updated the admin Gemini health check to run through the app’s agent-based flow (preserving {ok, reply} / {ok, error}).
• Bug Fixes
  • Improved resilience: cache-first behavior remains, and summary generation still falls back to the legacy contract when AI fails.
  • Study guide generation now returns a clearer 502 error when generation cannot be completed.
• Tests
  • Expanded and updated tests for agent execution, caching behavior, failure handling, and typed output shape serialization.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 36b5c5f0-1c9e-4623-ba33-a9861a267129

📥 Commits

Reviewing files that changed from the base of the PR and between 1b816cecd1924d4c086d307a58ca5275e00d11c7 and 09ce721.

📒 Files selected for processing (12)

• backend/agents/_providers.py
• backend/agents/_run.py
• backend/agents/health.py
• backend/agents/social_summary.py
• backend/agents/study_guide.py
• backend/main.py
• backend/routes/social.py
• backend/routes/study_guide.py
• backend/tests/test_gemini_test_auth.py
• backend/tests/test_oneshot_agents.py
• backend/tests/test_study_guide_routes.py
• specs/147-oneshot-llm-agents.md

✅ Files skipped from review due to trivial changes (1)

• specs/147-oneshot-llm-agents.md

🚧 Files skipped from review as they are similar to previous changes (10)

• backend/agents/_run.py
• backend/agents/health.py
• backend/agents/study_guide.py
• backend/routes/study_guide.py
• backend/tests/test_study_guide_routes.py
• backend/routes/social.py
• backend/main.py
• backend/tests/test_oneshot_agents.py
• backend/agents/social_summary.py
• backend/agents/_providers.py

---

📝 Walkthrough

Walkthrough

This PR migrates three remaining one-shot Gemini call sites to typed Pydantic AI agents, adds a shared sync bridge, updates provider defaults, and rewires the affected routes, health check, tests, and spec.

Changes

Agent migration

Layer / File(s)	Summary
Task defaults and sync bridge backend/agents/_providers.py, backend/agents/_run.py	Adds study_guide and social_summary to AgentTask and _DEFAULTS, and introduces run_agent_sync for running agent coroutines from sync handlers.
Health probe agent and gemini-test endpoint backend/agents/health.py, backend/main.py, backend/tests/test_gemini_test_auth.py	Adds health_probe_agent, rewires /api/gemini-test to run it via run_agent_sync, and updates auth/success/failure tests.
Social summary agent and room overview route backend/agents/social_summary.py, backend/routes/social.py, backend/tests/test_oneshot_agents.py	Adds SocialSummary and social_summary_agent, switches the overview cache-miss path to agent execution, and adds cache-hit/miss/error coverage.
Study guide agent and generation route backend/agents/study_guide.py, backend/routes/study_guide.py, backend/tests/test_study_guide_routes.py, backend/tests/test_oneshot_agents.py	Adds Topic/StudyGuide and study_guide_agent, rewires generation to agent execution with 502 failure handling, and updates route/output-shape tests.
Migration spec document specs/147-oneshot-llm-agents.md	Documents the migration requirements and acceptance criteria.

Estimated code review effort: 3 (Moderate) | ~30 minutes

Sequence Diagram(s)

sequenceDiagram
participant Client
participant Route as sync route handler
participant run_agent_sync
participant Agent as Pydantic AI agent
participant Supabase
Client->>Route: HTTP request
Route->>Route: build deps / prompt
Route->>run_agent_sync: run_agent_sync(agent.run(...))
run_agent_sync->>Agent: run(input)
alt success
Agent-->>run_agent_sync: typed output
run_agent_sync-->>Route: result
Route->>Supabase: persist or load cached data
Route-->>Client: 200 response
else failure
Agent-->>run_agent_sync: exception
Route-->>Client: 502 or fallback response
end

Loading

Possibly related issues

• [P1] Agent migration: retire call_gemini* + gemini_service.py (final cutover) #151: Directly matches the remaining one-shot Gemini-to-agent migration across routes and the health probe seam.
• [EPIC] Agent migration — retire gemini_service as the primary LLM seam #152: Same code-level cutover for routes/study_guide.py, routes/social.py, and backend/main.py.

Possibly related PRs

• SaplingLearn/Sapling#67: Both change the shared per-task model-selection layer in backend/agents/_providers.py.
• SaplingLearn/Sapling#71: Both extend the shared AgentTask/default-model mapping in _providers.py.
• SaplingLearn/Sapling#219: Both modify /api/gemini-test behavior and its tests.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 23.81% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: migrating remaining one-shot LLM calls to Pydantic AI agents.
Description check	✅ Passed	The description covers the goal, key changes, testing, and related issue, though it doesn't strictly follow the template headings.
Linked Issues check	✅ Passed	The three targeted call sites were migrated off direct call_gemini* usage, error handling matches the issue, and remaining callers are legacy fallback and tests.
Out of Scope Changes check	✅ Passed	The added modules, bridge helper, tests, and spec document all support the stated migration and do not appear unrelated.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/147-oneshot-llm-agents

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cloudflare-workers-and-pages]

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	frontend-staging	09ce721	Commit Preview URL Branch Preview URL	Jul 01 2026, 02:27 PM

[coderabbitai]

🧹 Nitpick comments (2)

backend/agents/social_summary.py (1)

35-35: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Duplicate prompt-hash boilerplate across agents.

The hashlib.sha256(...).hexdigest()[:12] pattern for _PROMPT_HASH is repeated verbatim in backend/agents/study_guide.py. As more agents are added under this pattern, consider extracting a small shared helper (e.g. agents/_providers.py::prompt_version(prompt: str) -> str) to avoid re-implementing this in every new agent module.

♻️ Suggested helper

+# agents/_providers.py+def prompt_version(system_prompt: str) -> str:+ import hashlib+ return hashlib.sha256(system_prompt.encode("utf-8")).hexdigest()[:12]

-import hashlib-
from pydantic import BaseModel, Field
from pydantic_ai import Agent
-from agents._providers import model_for+from agents._providers import model_for, prompt_version
from agents.deps import SaplingDeps
...
-_PROMPT_HASH = hashlib.sha256(_SYSTEM_PROMPT.encode("utf-8")).hexdigest()[:12]+_PROMPT_HASH = prompt_version(_SYSTEM_PROMPT)

Also applies to: 38-44

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@backend/agents/social_summary.py` at line 35, Duplicate prompt-hash
boilerplate is repeated in social_summary and study_guide; extract the shared
SHA-256 truncation logic into a small helper such as
agents/_providers.py::prompt_version(prompt: str) -> str, then update
_PROMPT_HASH in each agent module to call it instead of re-implementing
hashlib.sha256(...).hexdigest()[:12].

backend/agents/study_guide.py (1)

43-62: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

LGTM! Typed output correctly mirrors the legacy JSON contract, matching result.output.model_dump() usage in routes/study_guide.py. Same prompt-hash duplication note as in agents/social_summary.py applies here (see that comment) — extracting a shared helper would avoid re-implementing this in future agents.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@backend/agents/study_guide.py` around lines 43 - 62, The prompt hash logic is
duplicated in study_guide agent setup and should be centralized to match the
shared pattern used by other agents. Extract the SHA-256 prompt-version
calculation into a reusable helper and have study_guide_agent build its metadata
from that helper instead of re-implementing the hash inline. Keep the existing
_SYSTEM_PROMPT, _PROMPT_HASH, and study_guide_agent symbols as the integration
points when refactoring.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@backend/agents/social_summary.py`:
- Line 35: Duplicate prompt-hash boilerplate is repeated in social_summary and
study_guide; extract the shared SHA-256 truncation logic into a small helper
such as agents/_providers.py::prompt_version(prompt: str) -> str, then update
_PROMPT_HASH in each agent module to call it instead of re-implementing
hashlib.sha256(...).hexdigest()[:12].
In `@backend/agents/study_guide.py`:
- Around line 43-62: The prompt hash logic is duplicated in study_guide agent
setup and should be centralized to match the shared pattern used by other
agents. Extract the SHA-256 prompt-version calculation into a reusable helper
and have study_guide_agent build its metadata from that helper instead of
re-implementing the hash inline. Keep the existing _SYSTEM_PROMPT, _PROMPT_HASH,
and study_guide_agent symbols as the integration points when refactoring.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: e33a7124-0193-4aba-988a-15fecc891aae

📥 Commits

Reviewing files that changed from the base of the PR and between d86edde and 1b816cecd1924d4c086d307a58ca5275e00d11c7.

📒 Files selected for processing (12)

• backend/agents/_providers.py
• backend/agents/_run.py
• backend/agents/health.py
• backend/agents/social_summary.py
• backend/agents/study_guide.py
• backend/main.py
• backend/routes/social.py
• backend/routes/study_guide.py
• backend/tests/test_gemini_test_auth.py
• backend/tests/test_oneshot_agents.py
• backend/tests/test_study_guide_routes.py
• specs/147-oneshot-llm-agents.md

[Jose-Gael-Cruz-Lopez]

Closes#147 (part of the Agent-migration epic #152, milestone "Agent migration surfaces + staging + performance").

What

Retires the last three direct call_gemini* production call sites onto typed Pydantic AI agents. After this, the only backend gemini_service callers are the intentional legacy chat fallback (routes/learn.py, retired in the #151 cutover) and tests.

Surface	Before	After
routes/study_guide.py	call_gemini_json(prompt)	agents/study_guide.py (study_guide_agent)
routes/social.py	call_gemini(...)	agents/social_summary.py (social_summary_agent)
main.py/api/gemini-test	call_gemini(...)	agents/health.py (health_probe_agent)

Notes

• Contracts unchanged.StudyGuide/Topic mirror the existing exam/due_date/overview/topics JSON; the route model_dump()s straight into study_guides.content, so cached reads and the frontend are unaffected. /overview and /api/gemini-test response shapes are identical.
• Study-guide failures now return 502 (per the issue's audit note) instead of a raw 500.
• Social summary keeps the get_cached_summary → run → save_summary flow and the graceful fallback string (still 200) on agent failure.
• Health probe runs through the shared GoogleProvider from agents/_providers.py, so a green check means the real agent seam reaches Gemini. Admin-before-spend gate preserved.
• Sync→async bridge:agents/_run.py::run_agent_sync wraps asyncio.run for the three sync handlers (their surrounding httpx table() access stays synchronous). Handlers are not converted to async def.
• _providers.py registers study_guide (gemini-2.5-flash) and social_summary (gemini-2.5-flash-lite), both env-overridable via SAPLING_MODEL_*.

Testing

• Updated test_study_guide_routes.py and test_gemini_test_auth.py to mock the agents; added test_oneshot_agents.py covering the 502 path, social cache-hit/miss/agent-failure, and the StudyGuide → legacy-dict shape.
• Full backend suite: 829 passed (the 2 test_storage_service failures are pre-existing on main — missing SUPABASE env — verified by stash-and-run).
• ruff check clean on all changed files.

Out of scope (separate issues): quiz, documents, calendar, flashcards, course_context_service, the learn.py legacy fallback, and deleting gemini_service.py (#151).

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added AI-generated study guides and social room overview summaries using structured, typed outputs.
  • Updated the admin Gemini health check to run through the app’s agent-based flow (preserving {ok, reply} / {ok, error}).
• Bug Fixes
  • Improved resilience: cache-first behavior remains, and summary generation still falls back to the legacy contract when AI fails.
  • Study guide generation now returns a clearer 502 error when generation cannot be completed.
• Tests
  • Expanded and updated tests for agent execution, caching behavior, failure handling, and typed output shape serialization.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 36b5c5f0-1c9e-4623-ba33-a9861a267129

📥 Commits

Reviewing files that changed from the base of the PR and between 1b816cecd1924d4c086d307a58ca5275e00d11c7 and 09ce721.

📒 Files selected for processing (12)

• backend/agents/_providers.py
• backend/agents/_run.py
• backend/agents/health.py
• backend/agents/social_summary.py
• backend/agents/study_guide.py
• backend/main.py
• backend/routes/social.py
• backend/routes/study_guide.py
• backend/tests/test_gemini_test_auth.py
• backend/tests/test_oneshot_agents.py
• backend/tests/test_study_guide_routes.py
• specs/147-oneshot-llm-agents.md

✅ Files skipped from review due to trivial changes (1)

• specs/147-oneshot-llm-agents.md

🚧 Files skipped from review as they are similar to previous changes (10)

• backend/agents/_run.py
• backend/agents/health.py
• backend/agents/study_guide.py
• backend/routes/study_guide.py
• backend/tests/test_study_guide_routes.py
• backend/routes/social.py
• backend/main.py
• backend/tests/test_oneshot_agents.py
• backend/agents/social_summary.py
• backend/agents/_providers.py

---

📝 Walkthrough

Walkthrough

This PR migrates three remaining one-shot Gemini call sites to typed Pydantic AI agents, adds a shared sync bridge, updates provider defaults, and rewires the affected routes, health check, tests, and spec.

Changes

Agent migration

Layer / File(s)	Summary
Task defaults and sync bridge backend/agents/_providers.py, backend/agents/_run.py	Adds study_guide and social_summary to AgentTask and _DEFAULTS, and introduces run_agent_sync for running agent coroutines from sync handlers.
Health probe agent and gemini-test endpoint backend/agents/health.py, backend/main.py, backend/tests/test_gemini_test_auth.py	Adds health_probe_agent, rewires /api/gemini-test to run it via run_agent_sync, and updates auth/success/failure tests.
Social summary agent and room overview route backend/agents/social_summary.py, backend/routes/social.py, backend/tests/test_oneshot_agents.py	Adds SocialSummary and social_summary_agent, switches the overview cache-miss path to agent execution, and adds cache-hit/miss/error coverage.
Study guide agent and generation route backend/agents/study_guide.py, backend/routes/study_guide.py, backend/tests/test_study_guide_routes.py, backend/tests/test_oneshot_agents.py	Adds Topic/StudyGuide and study_guide_agent, rewires generation to agent execution with 502 failure handling, and updates route/output-shape tests.
Migration spec document specs/147-oneshot-llm-agents.md	Documents the migration requirements and acceptance criteria.

Estimated code review effort: 3 (Moderate) | ~30 minutes

Sequence Diagram(s)

sequenceDiagram
participant Client
participant Route as sync route handler
participant run_agent_sync
participant Agent as Pydantic AI agent
participant Supabase
Client->>Route: HTTP request
Route->>Route: build deps / prompt
Route->>run_agent_sync: run_agent_sync(agent.run(...))
run_agent_sync->>Agent: run(input)
alt success
Agent-->>run_agent_sync: typed output
run_agent_sync-->>Route: result
Route->>Supabase: persist or load cached data
Route-->>Client: 200 response
else failure
Agent-->>run_agent_sync: exception
Route-->>Client: 502 or fallback response
end

Loading

Possibly related issues

• [P1] Agent migration: retire call_gemini* + gemini_service.py (final cutover) #151: Directly matches the remaining one-shot Gemini-to-agent migration across routes and the health probe seam.
• [EPIC] Agent migration — retire gemini_service as the primary LLM seam #152: Same code-level cutover for routes/study_guide.py, routes/social.py, and backend/main.py.

Possibly related PRs

• SaplingLearn/Sapling#67: Both change the shared per-task model-selection layer in backend/agents/_providers.py.
• SaplingLearn/Sapling#71: Both extend the shared AgentTask/default-model mapping in _providers.py.
• SaplingLearn/Sapling#219: Both modify /api/gemini-test behavior and its tests.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 23.81% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: migrating remaining one-shot LLM calls to Pydantic AI agents.
Description check	✅ Passed	The description covers the goal, key changes, testing, and related issue, though it doesn't strictly follow the template headings.
Linked Issues check	✅ Passed	The three targeted call sites were migrated off direct call_gemini* usage, error handling matches the issue, and remaining callers are legacy fallback and tests.
Out of Scope Changes check	✅ Passed	The added modules, bridge helper, tests, and spec document all support the stated migration and do not appear unrelated.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/147-oneshot-llm-agents

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cloudflare-workers-and-pages]

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	frontend-staging	09ce721	Commit Preview URL Branch Preview URL	Jul 01 2026, 02:27 PM

[coderabbitai]

🧹 Nitpick comments (2)

backend/agents/social_summary.py (1)

35-35: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Duplicate prompt-hash boilerplate across agents.

The hashlib.sha256(...).hexdigest()[:12] pattern for _PROMPT_HASH is repeated verbatim in backend/agents/study_guide.py. As more agents are added under this pattern, consider extracting a small shared helper (e.g. agents/_providers.py::prompt_version(prompt: str) -> str) to avoid re-implementing this in every new agent module.

♻️ Suggested helper

+# agents/_providers.py+def prompt_version(system_prompt: str) -> str:+ import hashlib+ return hashlib.sha256(system_prompt.encode("utf-8")).hexdigest()[:12]

-import hashlib-
from pydantic import BaseModel, Field
from pydantic_ai import Agent
-from agents._providers import model_for+from agents._providers import model_for, prompt_version
from agents.deps import SaplingDeps
...
-_PROMPT_HASH = hashlib.sha256(_SYSTEM_PROMPT.encode("utf-8")).hexdigest()[:12]+_PROMPT_HASH = prompt_version(_SYSTEM_PROMPT)

Also applies to: 38-44

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@backend/agents/social_summary.py` at line 35, Duplicate prompt-hash
boilerplate is repeated in social_summary and study_guide; extract the shared
SHA-256 truncation logic into a small helper such as
agents/_providers.py::prompt_version(prompt: str) -> str, then update
_PROMPT_HASH in each agent module to call it instead of re-implementing
hashlib.sha256(...).hexdigest()[:12].

backend/agents/study_guide.py (1)

43-62: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

LGTM! Typed output correctly mirrors the legacy JSON contract, matching result.output.model_dump() usage in routes/study_guide.py. Same prompt-hash duplication note as in agents/social_summary.py applies here (see that comment) — extracting a shared helper would avoid re-implementing this in future agents.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@backend/agents/study_guide.py` around lines 43 - 62, The prompt hash logic is
duplicated in study_guide agent setup and should be centralized to match the
shared pattern used by other agents. Extract the SHA-256 prompt-version
calculation into a reusable helper and have study_guide_agent build its metadata
from that helper instead of re-implementing the hash inline. Keep the existing
_SYSTEM_PROMPT, _PROMPT_HASH, and study_guide_agent symbols as the integration
points when refactoring.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@backend/agents/social_summary.py`:
- Line 35: Duplicate prompt-hash boilerplate is repeated in social_summary and
study_guide; extract the shared SHA-256 truncation logic into a small helper
such as agents/_providers.py::prompt_version(prompt: str) -> str, then update
_PROMPT_HASH in each agent module to call it instead of re-implementing
hashlib.sha256(...).hexdigest()[:12].
In `@backend/agents/study_guide.py`:
- Around line 43-62: The prompt hash logic is duplicated in study_guide agent
setup and should be centralized to match the shared pattern used by other
agents. Extract the SHA-256 prompt-version calculation into a reusable helper
and have study_guide_agent build its metadata from that helper instead of
re-implementing the hash inline. Keep the existing _SYSTEM_PROMPT, _PROMPT_HASH,
and study_guide_agent symbols as the integration points when refactoring.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: e33a7124-0193-4aba-988a-15fecc891aae

📥 Commits

Reviewing files that changed from the base of the PR and between d86edde and 1b816cecd1924d4c086d307a58ca5275e00d11c7.

📒 Files selected for processing (12)

• backend/agents/_providers.py
• backend/agents/_run.py
• backend/agents/health.py
• backend/agents/social_summary.py
• backend/agents/study_guide.py
• backend/main.py
• backend/routes/social.py
• backend/routes/study_guide.py
• backend/tests/test_gemini_test_auth.py
• backend/tests/test_oneshot_agents.py
• backend/tests/test_study_guide_routes.py
• specs/147-oneshot-llm-agents.md

[Jose-Gael-Cruz-Lopez]

Closes#147 (part of the Agent-migration epic #152, milestone "Agent migration surfaces + staging + performance").

What

Retires the last three direct call_gemini* production call sites onto typed Pydantic AI agents. After this, the only backend gemini_service callers are the intentional legacy chat fallback (routes/learn.py, retired in the #151 cutover) and tests.

Surface	Before	After
routes/study_guide.py	call_gemini_json(prompt)	agents/study_guide.py (study_guide_agent)
routes/social.py	call_gemini(...)	agents/social_summary.py (social_summary_agent)
main.py/api/gemini-test	call_gemini(...)	agents/health.py (health_probe_agent)

Notes

• Contracts unchanged.StudyGuide/Topic mirror the existing exam/due_date/overview/topics JSON; the route model_dump()s straight into study_guides.content, so cached reads and the frontend are unaffected. /overview and /api/gemini-test response shapes are identical.
• Study-guide failures now return 502 (per the issue's audit note) instead of a raw 500.
• Social summary keeps the get_cached_summary → run → save_summary flow and the graceful fallback string (still 200) on agent failure.
• Health probe runs through the shared GoogleProvider from agents/_providers.py, so a green check means the real agent seam reaches Gemini. Admin-before-spend gate preserved.
• Sync→async bridge:agents/_run.py::run_agent_sync wraps asyncio.run for the three sync handlers (their surrounding httpx table() access stays synchronous). Handlers are not converted to async def.
• _providers.py registers study_guide (gemini-2.5-flash) and social_summary (gemini-2.5-flash-lite), both env-overridable via SAPLING_MODEL_*.

Testing

• Updated test_study_guide_routes.py and test_gemini_test_auth.py to mock the agents; added test_oneshot_agents.py covering the 502 path, social cache-hit/miss/agent-failure, and the StudyGuide → legacy-dict shape.
• Full backend suite: 829 passed (the 2 test_storage_service failures are pre-existing on main — missing SUPABASE env — verified by stash-and-run).
• ruff check clean on all changed files.

Out of scope (separate issues): quiz, documents, calendar, flashcards, course_context_service, the learn.py legacy fallback, and deleting gemini_service.py (#151).

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added AI-generated study guides and social room overview summaries using structured, typed outputs.
  • Updated the admin Gemini health check to run through the app’s agent-based flow (preserving {ok, reply} / {ok, error}).
• Bug Fixes
  • Improved resilience: cache-first behavior remains, and summary generation still falls back to the legacy contract when AI fails.
  • Study guide generation now returns a clearer 502 error when generation cannot be completed.
• Tests
  • Expanded and updated tests for agent execution, caching behavior, failure handling, and typed output shape serialization.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 36b5c5f0-1c9e-4623-ba33-a9861a267129

📥 Commits

Reviewing files that changed from the base of the PR and between 1b816cecd1924d4c086d307a58ca5275e00d11c7 and 09ce721.

📒 Files selected for processing (12)

• backend/agents/_providers.py
• backend/agents/_run.py
• backend/agents/health.py
• backend/agents/social_summary.py
• backend/agents/study_guide.py
• backend/main.py
• backend/routes/social.py
• backend/routes/study_guide.py
• backend/tests/test_gemini_test_auth.py
• backend/tests/test_oneshot_agents.py
• backend/tests/test_study_guide_routes.py
• specs/147-oneshot-llm-agents.md

✅ Files skipped from review due to trivial changes (1)

• specs/147-oneshot-llm-agents.md

🚧 Files skipped from review as they are similar to previous changes (10)

• backend/agents/_run.py
• backend/agents/health.py
• backend/agents/study_guide.py
• backend/routes/study_guide.py
• backend/tests/test_study_guide_routes.py
• backend/routes/social.py
• backend/main.py
• backend/tests/test_oneshot_agents.py
• backend/agents/social_summary.py
• backend/agents/_providers.py

---

📝 Walkthrough

Walkthrough

This PR migrates three remaining one-shot Gemini call sites to typed Pydantic AI agents, adds a shared sync bridge, updates provider defaults, and rewires the affected routes, health check, tests, and spec.

Changes

Agent migration

Layer / File(s)	Summary
Task defaults and sync bridge backend/agents/_providers.py, backend/agents/_run.py	Adds study_guide and social_summary to AgentTask and _DEFAULTS, and introduces run_agent_sync for running agent coroutines from sync handlers.
Health probe agent and gemini-test endpoint backend/agents/health.py, backend/main.py, backend/tests/test_gemini_test_auth.py	Adds health_probe_agent, rewires /api/gemini-test to run it via run_agent_sync, and updates auth/success/failure tests.
Social summary agent and room overview route backend/agents/social_summary.py, backend/routes/social.py, backend/tests/test_oneshot_agents.py	Adds SocialSummary and social_summary_agent, switches the overview cache-miss path to agent execution, and adds cache-hit/miss/error coverage.
Study guide agent and generation route backend/agents/study_guide.py, backend/routes/study_guide.py, backend/tests/test_study_guide_routes.py, backend/tests/test_oneshot_agents.py	Adds Topic/StudyGuide and study_guide_agent, rewires generation to agent execution with 502 failure handling, and updates route/output-shape tests.
Migration spec document specs/147-oneshot-llm-agents.md	Documents the migration requirements and acceptance criteria.

Estimated code review effort: 3 (Moderate) | ~30 minutes

Sequence Diagram(s)

sequenceDiagram
participant Client
participant Route as sync route handler
participant run_agent_sync
participant Agent as Pydantic AI agent
participant Supabase
Client->>Route: HTTP request
Route->>Route: build deps / prompt
Route->>run_agent_sync: run_agent_sync(agent.run(...))
run_agent_sync->>Agent: run(input)
alt success
Agent-->>run_agent_sync: typed output
run_agent_sync-->>Route: result
Route->>Supabase: persist or load cached data
Route-->>Client: 200 response
else failure
Agent-->>run_agent_sync: exception
Route-->>Client: 502 or fallback response
end

Loading

Possibly related issues

• [P1] Agent migration: retire call_gemini* + gemini_service.py (final cutover) #151: Directly matches the remaining one-shot Gemini-to-agent migration across routes and the health probe seam.
• [EPIC] Agent migration — retire gemini_service as the primary LLM seam #152: Same code-level cutover for routes/study_guide.py, routes/social.py, and backend/main.py.

Possibly related PRs

• SaplingLearn/Sapling#67: Both change the shared per-task model-selection layer in backend/agents/_providers.py.
• SaplingLearn/Sapling#71: Both extend the shared AgentTask/default-model mapping in _providers.py.
• SaplingLearn/Sapling#219: Both modify /api/gemini-test behavior and its tests.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 23.81% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: migrating remaining one-shot LLM calls to Pydantic AI agents.
Description check	✅ Passed	The description covers the goal, key changes, testing, and related issue, though it doesn't strictly follow the template headings.
Linked Issues check	✅ Passed	The three targeted call sites were migrated off direct call_gemini* usage, error handling matches the issue, and remaining callers are legacy fallback and tests.
Out of Scope Changes check	✅ Passed	The added modules, bridge helper, tests, and spec document all support the stated migration and do not appear unrelated.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/147-oneshot-llm-agents

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cloudflare-workers-and-pages]

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	frontend-staging	09ce721	Commit Preview URL Branch Preview URL	Jul 01 2026, 02:27 PM

[coderabbitai]

🧹 Nitpick comments (2)

backend/agents/social_summary.py (1)

35-35: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Duplicate prompt-hash boilerplate across agents.

The hashlib.sha256(...).hexdigest()[:12] pattern for _PROMPT_HASH is repeated verbatim in backend/agents/study_guide.py. As more agents are added under this pattern, consider extracting a small shared helper (e.g. agents/_providers.py::prompt_version(prompt: str) -> str) to avoid re-implementing this in every new agent module.

♻️ Suggested helper

+# agents/_providers.py+def prompt_version(system_prompt: str) -> str:+ import hashlib+ return hashlib.sha256(system_prompt.encode("utf-8")).hexdigest()[:12]

-import hashlib-
from pydantic import BaseModel, Field
from pydantic_ai import Agent
-from agents._providers import model_for+from agents._providers import model_for, prompt_version
from agents.deps import SaplingDeps
...
-_PROMPT_HASH = hashlib.sha256(_SYSTEM_PROMPT.encode("utf-8")).hexdigest()[:12]+_PROMPT_HASH = prompt_version(_SYSTEM_PROMPT)

Also applies to: 38-44

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@backend/agents/social_summary.py` at line 35, Duplicate prompt-hash
boilerplate is repeated in social_summary and study_guide; extract the shared
SHA-256 truncation logic into a small helper such as
agents/_providers.py::prompt_version(prompt: str) -> str, then update
_PROMPT_HASH in each agent module to call it instead of re-implementing
hashlib.sha256(...).hexdigest()[:12].

backend/agents/study_guide.py (1)

43-62: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

LGTM! Typed output correctly mirrors the legacy JSON contract, matching result.output.model_dump() usage in routes/study_guide.py. Same prompt-hash duplication note as in agents/social_summary.py applies here (see that comment) — extracting a shared helper would avoid re-implementing this in future agents.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@backend/agents/study_guide.py` around lines 43 - 62, The prompt hash logic is
duplicated in study_guide agent setup and should be centralized to match the
shared pattern used by other agents. Extract the SHA-256 prompt-version
calculation into a reusable helper and have study_guide_agent build its metadata
from that helper instead of re-implementing the hash inline. Keep the existing
_SYSTEM_PROMPT, _PROMPT_HASH, and study_guide_agent symbols as the integration
points when refactoring.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@backend/agents/social_summary.py`:
- Line 35: Duplicate prompt-hash boilerplate is repeated in social_summary and
study_guide; extract the shared SHA-256 truncation logic into a small helper
such as agents/_providers.py::prompt_version(prompt: str) -> str, then update
_PROMPT_HASH in each agent module to call it instead of re-implementing
hashlib.sha256(...).hexdigest()[:12].
In `@backend/agents/study_guide.py`:
- Around line 43-62: The prompt hash logic is duplicated in study_guide agent
setup and should be centralized to match the shared pattern used by other
agents. Extract the SHA-256 prompt-version calculation into a reusable helper
and have study_guide_agent build its metadata from that helper instead of
re-implementing the hash inline. Keep the existing _SYSTEM_PROMPT, _PROMPT_HASH,
and study_guide_agent symbols as the integration points when refactoring.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: e33a7124-0193-4aba-988a-15fecc891aae

📥 Commits

Reviewing files that changed from the base of the PR and between d86edde and 1b816cecd1924d4c086d307a58ca5275e00d11c7.

📒 Files selected for processing (12)

• backend/agents/_providers.py
• backend/agents/_run.py
• backend/agents/health.py
• backend/agents/social_summary.py
• backend/agents/study_guide.py
• backend/main.py
• backend/routes/social.py
• backend/routes/study_guide.py
• backend/tests/test_gemini_test_auth.py
• backend/tests/test_oneshot_agents.py
• backend/tests/test_study_guide_routes.py
• specs/147-oneshot-llm-agents.md

[Jose-Gael-Cruz-Lopez]

Closes#147 (part of the Agent-migration epic #152, milestone "Agent migration surfaces + staging + performance").

What

Retires the last three direct call_gemini* production call sites onto typed Pydantic AI agents. After this, the only backend gemini_service callers are the intentional legacy chat fallback (routes/learn.py, retired in the #151 cutover) and tests.

Surface	Before	After
routes/study_guide.py	call_gemini_json(prompt)	agents/study_guide.py (study_guide_agent)
routes/social.py	call_gemini(...)	agents/social_summary.py (social_summary_agent)
main.py/api/gemini-test	call_gemini(...)	agents/health.py (health_probe_agent)

Notes

• Contracts unchanged.StudyGuide/Topic mirror the existing exam/due_date/overview/topics JSON; the route model_dump()s straight into study_guides.content, so cached reads and the frontend are unaffected. /overview and /api/gemini-test response shapes are identical.
• Study-guide failures now return 502 (per the issue's audit note) instead of a raw 500.
• Social summary keeps the get_cached_summary → run → save_summary flow and the graceful fallback string (still 200) on agent failure.
• Health probe runs through the shared GoogleProvider from agents/_providers.py, so a green check means the real agent seam reaches Gemini. Admin-before-spend gate preserved.
• Sync→async bridge:agents/_run.py::run_agent_sync wraps asyncio.run for the three sync handlers (their surrounding httpx table() access stays synchronous). Handlers are not converted to async def.
• _providers.py registers study_guide (gemini-2.5-flash) and social_summary (gemini-2.5-flash-lite), both env-overridable via SAPLING_MODEL_*.

Testing

• Updated test_study_guide_routes.py and test_gemini_test_auth.py to mock the agents; added test_oneshot_agents.py covering the 502 path, social cache-hit/miss/agent-failure, and the StudyGuide → legacy-dict shape.
• Full backend suite: 829 passed (the 2 test_storage_service failures are pre-existing on main — missing SUPABASE env — verified by stash-and-run).
• ruff check clean on all changed files.

Out of scope (separate issues): quiz, documents, calendar, flashcards, course_context_service, the learn.py legacy fallback, and deleting gemini_service.py (#151).

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added AI-generated study guides and social room overview summaries using structured, typed outputs.
  • Updated the admin Gemini health check to run through the app’s agent-based flow (preserving {ok, reply} / {ok, error}).
• Bug Fixes
  • Improved resilience: cache-first behavior remains, and summary generation still falls back to the legacy contract when AI fails.
  • Study guide generation now returns a clearer 502 error when generation cannot be completed.
• Tests
  • Expanded and updated tests for agent execution, caching behavior, failure handling, and typed output shape serialization.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 36b5c5f0-1c9e-4623-ba33-a9861a267129

📥 Commits

Reviewing files that changed from the base of the PR and between 1b816cecd1924d4c086d307a58ca5275e00d11c7 and 09ce721.

📒 Files selected for processing (12)

• backend/agents/_providers.py
• backend/agents/_run.py
• backend/agents/health.py
• backend/agents/social_summary.py
• backend/agents/study_guide.py
• backend/main.py
• backend/routes/social.py
• backend/routes/study_guide.py
• backend/tests/test_gemini_test_auth.py
• backend/tests/test_oneshot_agents.py
• backend/tests/test_study_guide_routes.py
• specs/147-oneshot-llm-agents.md

✅ Files skipped from review due to trivial changes (1)

• specs/147-oneshot-llm-agents.md

🚧 Files skipped from review as they are similar to previous changes (10)

• backend/agents/_run.py
• backend/agents/health.py
• backend/agents/study_guide.py
• backend/routes/study_guide.py
• backend/tests/test_study_guide_routes.py
• backend/routes/social.py
• backend/main.py
• backend/tests/test_oneshot_agents.py
• backend/agents/social_summary.py
• backend/agents/_providers.py

---

📝 Walkthrough

Walkthrough

This PR migrates three remaining one-shot Gemini call sites to typed Pydantic AI agents, adds a shared sync bridge, updates provider defaults, and rewires the affected routes, health check, tests, and spec.

Changes

Agent migration

Layer / File(s)	Summary
Task defaults and sync bridge backend/agents/_providers.py, backend/agents/_run.py	Adds study_guide and social_summary to AgentTask and _DEFAULTS, and introduces run_agent_sync for running agent coroutines from sync handlers.
Health probe agent and gemini-test endpoint backend/agents/health.py, backend/main.py, backend/tests/test_gemini_test_auth.py	Adds health_probe_agent, rewires /api/gemini-test to run it via run_agent_sync, and updates auth/success/failure tests.
Social summary agent and room overview route backend/agents/social_summary.py, backend/routes/social.py, backend/tests/test_oneshot_agents.py	Adds SocialSummary and social_summary_agent, switches the overview cache-miss path to agent execution, and adds cache-hit/miss/error coverage.
Study guide agent and generation route backend/agents/study_guide.py, backend/routes/study_guide.py, backend/tests/test_study_guide_routes.py, backend/tests/test_oneshot_agents.py	Adds Topic/StudyGuide and study_guide_agent, rewires generation to agent execution with 502 failure handling, and updates route/output-shape tests.
Migration spec document specs/147-oneshot-llm-agents.md	Documents the migration requirements and acceptance criteria.

Estimated code review effort: 3 (Moderate) | ~30 minutes

Sequence Diagram(s)

sequenceDiagram
participant Client
participant Route as sync route handler
participant run_agent_sync
participant Agent as Pydantic AI agent
participant Supabase
Client->>Route: HTTP request
Route->>Route: build deps / prompt
Route->>run_agent_sync: run_agent_sync(agent.run(...))
run_agent_sync->>Agent: run(input)
alt success
Agent-->>run_agent_sync: typed output
run_agent_sync-->>Route: result
Route->>Supabase: persist or load cached data
Route-->>Client: 200 response
else failure
Agent-->>run_agent_sync: exception
Route-->>Client: 502 or fallback response
end

Loading

Possibly related issues

• [P1] Agent migration: retire call_gemini* + gemini_service.py (final cutover) #151: Directly matches the remaining one-shot Gemini-to-agent migration across routes and the health probe seam.
• [EPIC] Agent migration — retire gemini_service as the primary LLM seam #152: Same code-level cutover for routes/study_guide.py, routes/social.py, and backend/main.py.

Possibly related PRs

• SaplingLearn/Sapling#67: Both change the shared per-task model-selection layer in backend/agents/_providers.py.
• SaplingLearn/Sapling#71: Both extend the shared AgentTask/default-model mapping in _providers.py.
• SaplingLearn/Sapling#219: Both modify /api/gemini-test behavior and its tests.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 23.81% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: migrating remaining one-shot LLM calls to Pydantic AI agents.
Description check	✅ Passed	The description covers the goal, key changes, testing, and related issue, though it doesn't strictly follow the template headings.
Linked Issues check	✅ Passed	The three targeted call sites were migrated off direct call_gemini* usage, error handling matches the issue, and remaining callers are legacy fallback and tests.
Out of Scope Changes check	✅ Passed	The added modules, bridge helper, tests, and spec document all support the stated migration and do not appear unrelated.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/147-oneshot-llm-agents

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cloudflare-workers-and-pages]

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	frontend-staging	09ce721	Commit Preview URL Branch Preview URL	Jul 01 2026, 02:27 PM

[coderabbitai]

🧹 Nitpick comments (2)

backend/agents/social_summary.py (1)

35-35: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Duplicate prompt-hash boilerplate across agents.

The hashlib.sha256(...).hexdigest()[:12] pattern for _PROMPT_HASH is repeated verbatim in backend/agents/study_guide.py. As more agents are added under this pattern, consider extracting a small shared helper (e.g. agents/_providers.py::prompt_version(prompt: str) -> str) to avoid re-implementing this in every new agent module.

♻️ Suggested helper

+# agents/_providers.py+def prompt_version(system_prompt: str) -> str:+ import hashlib+ return hashlib.sha256(system_prompt.encode("utf-8")).hexdigest()[:12]

-import hashlib-
from pydantic import BaseModel, Field
from pydantic_ai import Agent
-from agents._providers import model_for+from agents._providers import model_for, prompt_version
from agents.deps import SaplingDeps
...
-_PROMPT_HASH = hashlib.sha256(_SYSTEM_PROMPT.encode("utf-8")).hexdigest()[:12]+_PROMPT_HASH = prompt_version(_SYSTEM_PROMPT)

Also applies to: 38-44

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@backend/agents/social_summary.py` at line 35, Duplicate prompt-hash
boilerplate is repeated in social_summary and study_guide; extract the shared
SHA-256 truncation logic into a small helper such as
agents/_providers.py::prompt_version(prompt: str) -> str, then update
_PROMPT_HASH in each agent module to call it instead of re-implementing
hashlib.sha256(...).hexdigest()[:12].

backend/agents/study_guide.py (1)

43-62: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

LGTM! Typed output correctly mirrors the legacy JSON contract, matching result.output.model_dump() usage in routes/study_guide.py. Same prompt-hash duplication note as in agents/social_summary.py applies here (see that comment) — extracting a shared helper would avoid re-implementing this in future agents.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@backend/agents/study_guide.py` around lines 43 - 62, The prompt hash logic is
duplicated in study_guide agent setup and should be centralized to match the
shared pattern used by other agents. Extract the SHA-256 prompt-version
calculation into a reusable helper and have study_guide_agent build its metadata
from that helper instead of re-implementing the hash inline. Keep the existing
_SYSTEM_PROMPT, _PROMPT_HASH, and study_guide_agent symbols as the integration
points when refactoring.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@backend/agents/social_summary.py`:
- Line 35: Duplicate prompt-hash boilerplate is repeated in social_summary and
study_guide; extract the shared SHA-256 truncation logic into a small helper
such as agents/_providers.py::prompt_version(prompt: str) -> str, then update
_PROMPT_HASH in each agent module to call it instead of re-implementing
hashlib.sha256(...).hexdigest()[:12].
In `@backend/agents/study_guide.py`:
- Around line 43-62: The prompt hash logic is duplicated in study_guide agent
setup and should be centralized to match the shared pattern used by other
agents. Extract the SHA-256 prompt-version calculation into a reusable helper
and have study_guide_agent build its metadata from that helper instead of
re-implementing the hash inline. Keep the existing _SYSTEM_PROMPT, _PROMPT_HASH,
and study_guide_agent symbols as the integration points when refactoring.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: e33a7124-0193-4aba-988a-15fecc891aae

📥 Commits

Reviewing files that changed from the base of the PR and between d86edde and 1b816cecd1924d4c086d307a58ca5275e00d11c7.

📒 Files selected for processing (12)

• backend/agents/_providers.py
• backend/agents/_run.py
• backend/agents/health.py
• backend/agents/social_summary.py
• backend/agents/study_guide.py
• backend/main.py
• backend/routes/social.py
• backend/routes/study_guide.py
• backend/tests/test_gemini_test_auth.py
• backend/tests/test_oneshot_agents.py
• backend/tests/test_study_guide_routes.py
• specs/147-oneshot-llm-agents.md

[Jose-Gael-Cruz-Lopez]

Closes#147 (part of the Agent-migration epic #152, milestone "Agent migration surfaces + staging + performance").

What

Retires the last three direct call_gemini* production call sites onto typed Pydantic AI agents. After this, the only backend gemini_service callers are the intentional legacy chat fallback (routes/learn.py, retired in the #151 cutover) and tests.

Surface	Before	After
routes/study_guide.py	call_gemini_json(prompt)	agents/study_guide.py (study_guide_agent)
routes/social.py	call_gemini(...)	agents/social_summary.py (social_summary_agent)
main.py/api/gemini-test	call_gemini(...)	agents/health.py (health_probe_agent)

Notes

• Contracts unchanged.StudyGuide/Topic mirror the existing exam/due_date/overview/topics JSON; the route model_dump()s straight into study_guides.content, so cached reads and the frontend are unaffected. /overview and /api/gemini-test response shapes are identical.
• Study-guide failures now return 502 (per the issue's audit note) instead of a raw 500.
• Social summary keeps the get_cached_summary → run → save_summary flow and the graceful fallback string (still 200) on agent failure.
• Health probe runs through the shared GoogleProvider from agents/_providers.py, so a green check means the real agent seam reaches Gemini. Admin-before-spend gate preserved.
• Sync→async bridge:agents/_run.py::run_agent_sync wraps asyncio.run for the three sync handlers (their surrounding httpx table() access stays synchronous). Handlers are not converted to async def.
• _providers.py registers study_guide (gemini-2.5-flash) and social_summary (gemini-2.5-flash-lite), both env-overridable via SAPLING_MODEL_*.

Testing

• Updated test_study_guide_routes.py and test_gemini_test_auth.py to mock the agents; added test_oneshot_agents.py covering the 502 path, social cache-hit/miss/agent-failure, and the StudyGuide → legacy-dict shape.
• Full backend suite: 829 passed (the 2 test_storage_service failures are pre-existing on main — missing SUPABASE env — verified by stash-and-run).
• ruff check clean on all changed files.

Out of scope (separate issues): quiz, documents, calendar, flashcards, course_context_service, the learn.py legacy fallback, and deleting gemini_service.py (#151).

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added AI-generated study guides and social room overview summaries using structured, typed outputs.
  • Updated the admin Gemini health check to run through the app’s agent-based flow (preserving {ok, reply} / {ok, error}).
• Bug Fixes
  • Improved resilience: cache-first behavior remains, and summary generation still falls back to the legacy contract when AI fails.
  • Study guide generation now returns a clearer 502 error when generation cannot be completed.
• Tests
  • Expanded and updated tests for agent execution, caching behavior, failure handling, and typed output shape serialization.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 36b5c5f0-1c9e-4623-ba33-a9861a267129

📥 Commits

Reviewing files that changed from the base of the PR and between 1b816cecd1924d4c086d307a58ca5275e00d11c7 and 09ce721.

📒 Files selected for processing (12)

• backend/agents/_providers.py
• backend/agents/_run.py
• backend/agents/health.py
• backend/agents/social_summary.py
• backend/agents/study_guide.py
• backend/main.py
• backend/routes/social.py
• backend/routes/study_guide.py
• backend/tests/test_gemini_test_auth.py
• backend/tests/test_oneshot_agents.py
• backend/tests/test_study_guide_routes.py
• specs/147-oneshot-llm-agents.md

✅ Files skipped from review due to trivial changes (1)

• specs/147-oneshot-llm-agents.md

🚧 Files skipped from review as they are similar to previous changes (10)

• backend/agents/_run.py
• backend/agents/health.py
• backend/agents/study_guide.py
• backend/routes/study_guide.py
• backend/tests/test_study_guide_routes.py
• backend/routes/social.py
• backend/main.py
• backend/tests/test_oneshot_agents.py
• backend/agents/social_summary.py
• backend/agents/_providers.py

---

📝 Walkthrough

Walkthrough

This PR migrates three remaining one-shot Gemini call sites to typed Pydantic AI agents, adds a shared sync bridge, updates provider defaults, and rewires the affected routes, health check, tests, and spec.

Changes

Agent migration

Layer / File(s)	Summary
Task defaults and sync bridge backend/agents/_providers.py, backend/agents/_run.py	Adds study_guide and social_summary to AgentTask and _DEFAULTS, and introduces run_agent_sync for running agent coroutines from sync handlers.
Health probe agent and gemini-test endpoint backend/agents/health.py, backend/main.py, backend/tests/test_gemini_test_auth.py	Adds health_probe_agent, rewires /api/gemini-test to run it via run_agent_sync, and updates auth/success/failure tests.
Social summary agent and room overview route backend/agents/social_summary.py, backend/routes/social.py, backend/tests/test_oneshot_agents.py	Adds SocialSummary and social_summary_agent, switches the overview cache-miss path to agent execution, and adds cache-hit/miss/error coverage.
Study guide agent and generation route backend/agents/study_guide.py, backend/routes/study_guide.py, backend/tests/test_study_guide_routes.py, backend/tests/test_oneshot_agents.py	Adds Topic/StudyGuide and study_guide_agent, rewires generation to agent execution with 502 failure handling, and updates route/output-shape tests.
Migration spec document specs/147-oneshot-llm-agents.md	Documents the migration requirements and acceptance criteria.

Estimated code review effort: 3 (Moderate) | ~30 minutes

Sequence Diagram(s)

sequenceDiagram
participant Client
participant Route as sync route handler
participant run_agent_sync
participant Agent as Pydantic AI agent
participant Supabase
Client->>Route: HTTP request
Route->>Route: build deps / prompt
Route->>run_agent_sync: run_agent_sync(agent.run(...))
run_agent_sync->>Agent: run(input)
alt success
Agent-->>run_agent_sync: typed output
run_agent_sync-->>Route: result
Route->>Supabase: persist or load cached data
Route-->>Client: 200 response
else failure
Agent-->>run_agent_sync: exception
Route-->>Client: 502 or fallback response
end

Loading

Possibly related issues

• [P1] Agent migration: retire call_gemini* + gemini_service.py (final cutover) #151: Directly matches the remaining one-shot Gemini-to-agent migration across routes and the health probe seam.
• [EPIC] Agent migration — retire gemini_service as the primary LLM seam #152: Same code-level cutover for routes/study_guide.py, routes/social.py, and backend/main.py.

Possibly related PRs

• SaplingLearn/Sapling#67: Both change the shared per-task model-selection layer in backend/agents/_providers.py.
• SaplingLearn/Sapling#71: Both extend the shared AgentTask/default-model mapping in _providers.py.
• SaplingLearn/Sapling#219: Both modify /api/gemini-test behavior and its tests.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 23.81% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: migrating remaining one-shot LLM calls to Pydantic AI agents.
Description check	✅ Passed	The description covers the goal, key changes, testing, and related issue, though it doesn't strictly follow the template headings.
Linked Issues check	✅ Passed	The three targeted call sites were migrated off direct call_gemini* usage, error handling matches the issue, and remaining callers are legacy fallback and tests.
Out of Scope Changes check	✅ Passed	The added modules, bridge helper, tests, and spec document all support the stated migration and do not appear unrelated.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/147-oneshot-llm-agents

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cloudflare-workers-and-pages]

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	frontend-staging	09ce721	Commit Preview URL Branch Preview URL	Jul 01 2026, 02:27 PM

[coderabbitai]

🧹 Nitpick comments (2)

backend/agents/social_summary.py (1)

35-35: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Duplicate prompt-hash boilerplate across agents.

The hashlib.sha256(...).hexdigest()[:12] pattern for _PROMPT_HASH is repeated verbatim in backend/agents/study_guide.py. As more agents are added under this pattern, consider extracting a small shared helper (e.g. agents/_providers.py::prompt_version(prompt: str) -> str) to avoid re-implementing this in every new agent module.

♻️ Suggested helper

+# agents/_providers.py+def prompt_version(system_prompt: str) -> str:+ import hashlib+ return hashlib.sha256(system_prompt.encode("utf-8")).hexdigest()[:12]

-import hashlib-
from pydantic import BaseModel, Field
from pydantic_ai import Agent
-from agents._providers import model_for+from agents._providers import model_for, prompt_version
from agents.deps import SaplingDeps
...
-_PROMPT_HASH = hashlib.sha256(_SYSTEM_PROMPT.encode("utf-8")).hexdigest()[:12]+_PROMPT_HASH = prompt_version(_SYSTEM_PROMPT)

Also applies to: 38-44

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@backend/agents/social_summary.py` at line 35, Duplicate prompt-hash
boilerplate is repeated in social_summary and study_guide; extract the shared
SHA-256 truncation logic into a small helper such as
agents/_providers.py::prompt_version(prompt: str) -> str, then update
_PROMPT_HASH in each agent module to call it instead of re-implementing
hashlib.sha256(...).hexdigest()[:12].

backend/agents/study_guide.py (1)

43-62: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

LGTM! Typed output correctly mirrors the legacy JSON contract, matching result.output.model_dump() usage in routes/study_guide.py. Same prompt-hash duplication note as in agents/social_summary.py applies here (see that comment) — extracting a shared helper would avoid re-implementing this in future agents.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@backend/agents/study_guide.py` around lines 43 - 62, The prompt hash logic is
duplicated in study_guide agent setup and should be centralized to match the
shared pattern used by other agents. Extract the SHA-256 prompt-version
calculation into a reusable helper and have study_guide_agent build its metadata
from that helper instead of re-implementing the hash inline. Keep the existing
_SYSTEM_PROMPT, _PROMPT_HASH, and study_guide_agent symbols as the integration
points when refactoring.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@backend/agents/social_summary.py`:
- Line 35: Duplicate prompt-hash boilerplate is repeated in social_summary and
study_guide; extract the shared SHA-256 truncation logic into a small helper
such as agents/_providers.py::prompt_version(prompt: str) -> str, then update
_PROMPT_HASH in each agent module to call it instead of re-implementing
hashlib.sha256(...).hexdigest()[:12].
In `@backend/agents/study_guide.py`:
- Around line 43-62: The prompt hash logic is duplicated in study_guide agent
setup and should be centralized to match the shared pattern used by other
agents. Extract the SHA-256 prompt-version calculation into a reusable helper
and have study_guide_agent build its metadata from that helper instead of
re-implementing the hash inline. Keep the existing _SYSTEM_PROMPT, _PROMPT_HASH,
and study_guide_agent symbols as the integration points when refactoring.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: e33a7124-0193-4aba-988a-15fecc891aae

📥 Commits

Reviewing files that changed from the base of the PR and between d86edde and 1b816cecd1924d4c086d307a58ca5275e00d11c7.

📒 Files selected for processing (12)

• backend/agents/_providers.py
• backend/agents/_run.py
• backend/agents/health.py
• backend/agents/social_summary.py
• backend/agents/study_guide.py
• backend/main.py
• backend/routes/social.py
• backend/routes/study_guide.py
• backend/tests/test_gemini_test_auth.py
• backend/tests/test_oneshot_agents.py
• backend/tests/test_study_guide_routes.py
• specs/147-oneshot-llm-agents.md

[Jose-Gael-Cruz-Lopez]

Closes#147 (part of the Agent-migration epic #152, milestone "Agent migration surfaces + staging + performance").

What

Retires the last three direct call_gemini* production call sites onto typed Pydantic AI agents. After this, the only backend gemini_service callers are the intentional legacy chat fallback (routes/learn.py, retired in the #151 cutover) and tests.

Surface	Before	After
routes/study_guide.py	call_gemini_json(prompt)	agents/study_guide.py (study_guide_agent)
routes/social.py	call_gemini(...)	agents/social_summary.py (social_summary_agent)
main.py/api/gemini-test	call_gemini(...)	agents/health.py (health_probe_agent)

Notes

• Contracts unchanged.StudyGuide/Topic mirror the existing exam/due_date/overview/topics JSON; the route model_dump()s straight into study_guides.content, so cached reads and the frontend are unaffected. /overview and /api/gemini-test response shapes are identical.
• Study-guide failures now return 502 (per the issue's audit note) instead of a raw 500.
• Social summary keeps the get_cached_summary → run → save_summary flow and the graceful fallback string (still 200) on agent failure.
• Health probe runs through the shared GoogleProvider from agents/_providers.py, so a green check means the real agent seam reaches Gemini. Admin-before-spend gate preserved.
• Sync→async bridge:agents/_run.py::run_agent_sync wraps asyncio.run for the three sync handlers (their surrounding httpx table() access stays synchronous). Handlers are not converted to async def.
• _providers.py registers study_guide (gemini-2.5-flash) and social_summary (gemini-2.5-flash-lite), both env-overridable via SAPLING_MODEL_*.

Testing

• Updated test_study_guide_routes.py and test_gemini_test_auth.py to mock the agents; added test_oneshot_agents.py covering the 502 path, social cache-hit/miss/agent-failure, and the StudyGuide → legacy-dict shape.
• Full backend suite: 829 passed (the 2 test_storage_service failures are pre-existing on main — missing SUPABASE env — verified by stash-and-run).
• ruff check clean on all changed files.

Out of scope (separate issues): quiz, documents, calendar, flashcards, course_context_service, the learn.py legacy fallback, and deleting gemini_service.py (#151).

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added AI-generated study guides and social room overview summaries using structured, typed outputs.
  • Updated the admin Gemini health check to run through the app’s agent-based flow (preserving {ok, reply} / {ok, error}).
• Bug Fixes
  • Improved resilience: cache-first behavior remains, and summary generation still falls back to the legacy contract when AI fails.
  • Study guide generation now returns a clearer 502 error when generation cannot be completed.
• Tests
  • Expanded and updated tests for agent execution, caching behavior, failure handling, and typed output shape serialization.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 36b5c5f0-1c9e-4623-ba33-a9861a267129

📥 Commits

Reviewing files that changed from the base of the PR and between 1b816cecd1924d4c086d307a58ca5275e00d11c7 and 09ce721.

📒 Files selected for processing (12)

• backend/agents/_providers.py
• backend/agents/_run.py
• backend/agents/health.py
• backend/agents/social_summary.py
• backend/agents/study_guide.py
• backend/main.py
• backend/routes/social.py
• backend/routes/study_guide.py
• backend/tests/test_gemini_test_auth.py
• backend/tests/test_oneshot_agents.py
• backend/tests/test_study_guide_routes.py
• specs/147-oneshot-llm-agents.md

✅ Files skipped from review due to trivial changes (1)

• specs/147-oneshot-llm-agents.md

🚧 Files skipped from review as they are similar to previous changes (10)

• backend/agents/_run.py
• backend/agents/health.py
• backend/agents/study_guide.py
• backend/routes/study_guide.py
• backend/tests/test_study_guide_routes.py
• backend/routes/social.py
• backend/main.py
• backend/tests/test_oneshot_agents.py
• backend/agents/social_summary.py
• backend/agents/_providers.py

---

📝 Walkthrough

Walkthrough

This PR migrates three remaining one-shot Gemini call sites to typed Pydantic AI agents, adds a shared sync bridge, updates provider defaults, and rewires the affected routes, health check, tests, and spec.

Changes

Agent migration

Layer / File(s)	Summary
Task defaults and sync bridge backend/agents/_providers.py, backend/agents/_run.py	Adds study_guide and social_summary to AgentTask and _DEFAULTS, and introduces run_agent_sync for running agent coroutines from sync handlers.
Health probe agent and gemini-test endpoint backend/agents/health.py, backend/main.py, backend/tests/test_gemini_test_auth.py	Adds health_probe_agent, rewires /api/gemini-test to run it via run_agent_sync, and updates auth/success/failure tests.
Social summary agent and room overview route backend/agents/social_summary.py, backend/routes/social.py, backend/tests/test_oneshot_agents.py	Adds SocialSummary and social_summary_agent, switches the overview cache-miss path to agent execution, and adds cache-hit/miss/error coverage.
Study guide agent and generation route backend/agents/study_guide.py, backend/routes/study_guide.py, backend/tests/test_study_guide_routes.py, backend/tests/test_oneshot_agents.py	Adds Topic/StudyGuide and study_guide_agent, rewires generation to agent execution with 502 failure handling, and updates route/output-shape tests.
Migration spec document specs/147-oneshot-llm-agents.md	Documents the migration requirements and acceptance criteria.

Estimated code review effort: 3 (Moderate) | ~30 minutes

Sequence Diagram(s)

sequenceDiagram
participant Client
participant Route as sync route handler
participant run_agent_sync
participant Agent as Pydantic AI agent
participant Supabase
Client->>Route: HTTP request
Route->>Route: build deps / prompt
Route->>run_agent_sync: run_agent_sync(agent.run(...))
run_agent_sync->>Agent: run(input)
alt success
Agent-->>run_agent_sync: typed output
run_agent_sync-->>Route: result
Route->>Supabase: persist or load cached data
Route-->>Client: 200 response
else failure
Agent-->>run_agent_sync: exception
Route-->>Client: 502 or fallback response
end

Loading

Possibly related issues

• [P1] Agent migration: retire call_gemini* + gemini_service.py (final cutover) #151: Directly matches the remaining one-shot Gemini-to-agent migration across routes and the health probe seam.
• [EPIC] Agent migration — retire gemini_service as the primary LLM seam #152: Same code-level cutover for routes/study_guide.py, routes/social.py, and backend/main.py.

Possibly related PRs

• SaplingLearn/Sapling#67: Both change the shared per-task model-selection layer in backend/agents/_providers.py.
• SaplingLearn/Sapling#71: Both extend the shared AgentTask/default-model mapping in _providers.py.
• SaplingLearn/Sapling#219: Both modify /api/gemini-test behavior and its tests.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 23.81% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: migrating remaining one-shot LLM calls to Pydantic AI agents.
Description check	✅ Passed	The description covers the goal, key changes, testing, and related issue, though it doesn't strictly follow the template headings.
Linked Issues check	✅ Passed	The three targeted call sites were migrated off direct call_gemini* usage, error handling matches the issue, and remaining callers are legacy fallback and tests.
Out of Scope Changes check	✅ Passed	The added modules, bridge helper, tests, and spec document all support the stated migration and do not appear unrelated.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/147-oneshot-llm-agents

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cloudflare-workers-and-pages]

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	frontend-staging	09ce721	Commit Preview URL Branch Preview URL	Jul 01 2026, 02:27 PM

[coderabbitai]

🧹 Nitpick comments (2)

backend/agents/social_summary.py (1)

35-35: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Duplicate prompt-hash boilerplate across agents.

The hashlib.sha256(...).hexdigest()[:12] pattern for _PROMPT_HASH is repeated verbatim in backend/agents/study_guide.py. As more agents are added under this pattern, consider extracting a small shared helper (e.g. agents/_providers.py::prompt_version(prompt: str) -> str) to avoid re-implementing this in every new agent module.

♻️ Suggested helper

+# agents/_providers.py+def prompt_version(system_prompt: str) -> str:+ import hashlib+ return hashlib.sha256(system_prompt.encode("utf-8")).hexdigest()[:12]

-import hashlib-
from pydantic import BaseModel, Field
from pydantic_ai import Agent
-from agents._providers import model_for+from agents._providers import model_for, prompt_version
from agents.deps import SaplingDeps
...
-_PROMPT_HASH = hashlib.sha256(_SYSTEM_PROMPT.encode("utf-8")).hexdigest()[:12]+_PROMPT_HASH = prompt_version(_SYSTEM_PROMPT)

Also applies to: 38-44

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@backend/agents/social_summary.py` at line 35, Duplicate prompt-hash
boilerplate is repeated in social_summary and study_guide; extract the shared
SHA-256 truncation logic into a small helper such as
agents/_providers.py::prompt_version(prompt: str) -> str, then update
_PROMPT_HASH in each agent module to call it instead of re-implementing
hashlib.sha256(...).hexdigest()[:12].

backend/agents/study_guide.py (1)

43-62: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

LGTM! Typed output correctly mirrors the legacy JSON contract, matching result.output.model_dump() usage in routes/study_guide.py. Same prompt-hash duplication note as in agents/social_summary.py applies here (see that comment) — extracting a shared helper would avoid re-implementing this in future agents.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@backend/agents/study_guide.py` around lines 43 - 62, The prompt hash logic is
duplicated in study_guide agent setup and should be centralized to match the
shared pattern used by other agents. Extract the SHA-256 prompt-version
calculation into a reusable helper and have study_guide_agent build its metadata
from that helper instead of re-implementing the hash inline. Keep the existing
_SYSTEM_PROMPT, _PROMPT_HASH, and study_guide_agent symbols as the integration
points when refactoring.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@backend/agents/social_summary.py`:
- Line 35: Duplicate prompt-hash boilerplate is repeated in social_summary and
study_guide; extract the shared SHA-256 truncation logic into a small helper
such as agents/_providers.py::prompt_version(prompt: str) -> str, then update
_PROMPT_HASH in each agent module to call it instead of re-implementing
hashlib.sha256(...).hexdigest()[:12].
In `@backend/agents/study_guide.py`:
- Around line 43-62: The prompt hash logic is duplicated in study_guide agent
setup and should be centralized to match the shared pattern used by other
agents. Extract the SHA-256 prompt-version calculation into a reusable helper
and have study_guide_agent build its metadata from that helper instead of
re-implementing the hash inline. Keep the existing _SYSTEM_PROMPT, _PROMPT_HASH,
and study_guide_agent symbols as the integration points when refactoring.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: e33a7124-0193-4aba-988a-15fecc891aae

📥 Commits

Reviewing files that changed from the base of the PR and between d86edde and 1b816cecd1924d4c086d307a58ca5275e00d11c7.

📒 Files selected for processing (12)

• backend/agents/_providers.py
• backend/agents/_run.py
• backend/agents/health.py
• backend/agents/social_summary.py
• backend/agents/study_guide.py
• backend/main.py
• backend/routes/social.py
• backend/routes/study_guide.py
• backend/tests/test_gemini_test_auth.py
• backend/tests/test_oneshot_agents.py
• backend/tests/test_study_guide_routes.py
• specs/147-oneshot-llm-agents.md

[Jose-Gael-Cruz-Lopez]

Closes#147 (part of the Agent-migration epic #152, milestone "Agent migration surfaces + staging + performance").

What

Retires the last three direct call_gemini* production call sites onto typed Pydantic AI agents. After this, the only backend gemini_service callers are the intentional legacy chat fallback (routes/learn.py, retired in the #151 cutover) and tests.

Surface	Before	After
routes/study_guide.py	call_gemini_json(prompt)	agents/study_guide.py (study_guide_agent)
routes/social.py	call_gemini(...)	agents/social_summary.py (social_summary_agent)
main.py/api/gemini-test	call_gemini(...)	agents/health.py (health_probe_agent)

Notes

• Contracts unchanged.StudyGuide/Topic mirror the existing exam/due_date/overview/topics JSON; the route model_dump()s straight into study_guides.content, so cached reads and the frontend are unaffected. /overview and /api/gemini-test response shapes are identical.
• Study-guide failures now return 502 (per the issue's audit note) instead of a raw 500.
• Social summary keeps the get_cached_summary → run → save_summary flow and the graceful fallback string (still 200) on agent failure.
• Health probe runs through the shared GoogleProvider from agents/_providers.py, so a green check means the real agent seam reaches Gemini. Admin-before-spend gate preserved.
• Sync→async bridge:agents/_run.py::run_agent_sync wraps asyncio.run for the three sync handlers (their surrounding httpx table() access stays synchronous). Handlers are not converted to async def.
• _providers.py registers study_guide (gemini-2.5-flash) and social_summary (gemini-2.5-flash-lite), both env-overridable via SAPLING_MODEL_*.

Testing

• Updated test_study_guide_routes.py and test_gemini_test_auth.py to mock the agents; added test_oneshot_agents.py covering the 502 path, social cache-hit/miss/agent-failure, and the StudyGuide → legacy-dict shape.
• Full backend suite: 829 passed (the 2 test_storage_service failures are pre-existing on main — missing SUPABASE env — verified by stash-and-run).
• ruff check clean on all changed files.

Out of scope (separate issues): quiz, documents, calendar, flashcards, course_context_service, the learn.py legacy fallback, and deleting gemini_service.py (#151).

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added AI-generated study guides and social room overview summaries using structured, typed outputs.
  • Updated the admin Gemini health check to run through the app’s agent-based flow (preserving {ok, reply} / {ok, error}).
• Bug Fixes
  • Improved resilience: cache-first behavior remains, and summary generation still falls back to the legacy contract when AI fails.
  • Study guide generation now returns a clearer 502 error when generation cannot be completed.
• Tests
  • Expanded and updated tests for agent execution, caching behavior, failure handling, and typed output shape serialization.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 36b5c5f0-1c9e-4623-ba33-a9861a267129

📥 Commits

Reviewing files that changed from the base of the PR and between 1b816cecd1924d4c086d307a58ca5275e00d11c7 and 09ce721.

📒 Files selected for processing (12)

• backend/agents/_providers.py
• backend/agents/_run.py
• backend/agents/health.py
• backend/agents/social_summary.py
• backend/agents/study_guide.py
• backend/main.py
• backend/routes/social.py
• backend/routes/study_guide.py
• backend/tests/test_gemini_test_auth.py
• backend/tests/test_oneshot_agents.py
• backend/tests/test_study_guide_routes.py
• specs/147-oneshot-llm-agents.md

✅ Files skipped from review due to trivial changes (1)

• specs/147-oneshot-llm-agents.md

🚧 Files skipped from review as they are similar to previous changes (10)

• backend/agents/_run.py
• backend/agents/health.py
• backend/agents/study_guide.py
• backend/routes/study_guide.py
• backend/tests/test_study_guide_routes.py
• backend/routes/social.py
• backend/main.py
• backend/tests/test_oneshot_agents.py
• backend/agents/social_summary.py
• backend/agents/_providers.py

---

📝 Walkthrough

Walkthrough

This PR migrates three remaining one-shot Gemini call sites to typed Pydantic AI agents, adds a shared sync bridge, updates provider defaults, and rewires the affected routes, health check, tests, and spec.

Changes

Agent migration

Layer / File(s)	Summary
Task defaults and sync bridge backend/agents/_providers.py, backend/agents/_run.py	Adds study_guide and social_summary to AgentTask and _DEFAULTS, and introduces run_agent_sync for running agent coroutines from sync handlers.
Health probe agent and gemini-test endpoint backend/agents/health.py, backend/main.py, backend/tests/test_gemini_test_auth.py	Adds health_probe_agent, rewires /api/gemini-test to run it via run_agent_sync, and updates auth/success/failure tests.
Social summary agent and room overview route backend/agents/social_summary.py, backend/routes/social.py, backend/tests/test_oneshot_agents.py	Adds SocialSummary and social_summary_agent, switches the overview cache-miss path to agent execution, and adds cache-hit/miss/error coverage.
Study guide agent and generation route backend/agents/study_guide.py, backend/routes/study_guide.py, backend/tests/test_study_guide_routes.py, backend/tests/test_oneshot_agents.py	Adds Topic/StudyGuide and study_guide_agent, rewires generation to agent execution with 502 failure handling, and updates route/output-shape tests.
Migration spec document specs/147-oneshot-llm-agents.md	Documents the migration requirements and acceptance criteria.

Estimated code review effort: 3 (Moderate) | ~30 minutes

Sequence Diagram(s)

sequenceDiagram
participant Client
participant Route as sync route handler
participant run_agent_sync
participant Agent as Pydantic AI agent
participant Supabase
Client->>Route: HTTP request
Route->>Route: build deps / prompt
Route->>run_agent_sync: run_agent_sync(agent.run(...))
run_agent_sync->>Agent: run(input)
alt success
Agent-->>run_agent_sync: typed output
run_agent_sync-->>Route: result
Route->>Supabase: persist or load cached data
Route-->>Client: 200 response
else failure
Agent-->>run_agent_sync: exception
Route-->>Client: 502 or fallback response
end

Loading

Possibly related issues

• [P1] Agent migration: retire call_gemini* + gemini_service.py (final cutover) #151: Directly matches the remaining one-shot Gemini-to-agent migration across routes and the health probe seam.
• [EPIC] Agent migration — retire gemini_service as the primary LLM seam #152: Same code-level cutover for routes/study_guide.py, routes/social.py, and backend/main.py.

Possibly related PRs

• SaplingLearn/Sapling#67: Both change the shared per-task model-selection layer in backend/agents/_providers.py.
• SaplingLearn/Sapling#71: Both extend the shared AgentTask/default-model mapping in _providers.py.
• SaplingLearn/Sapling#219: Both modify /api/gemini-test behavior and its tests.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 23.81% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: migrating remaining one-shot LLM calls to Pydantic AI agents.
Description check	✅ Passed	The description covers the goal, key changes, testing, and related issue, though it doesn't strictly follow the template headings.
Linked Issues check	✅ Passed	The three targeted call sites were migrated off direct call_gemini* usage, error handling matches the issue, and remaining callers are legacy fallback and tests.
Out of Scope Changes check	✅ Passed	The added modules, bridge helper, tests, and spec document all support the stated migration and do not appear unrelated.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/147-oneshot-llm-agents

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cloudflare-workers-and-pages]

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	frontend-staging	09ce721	Commit Preview URL Branch Preview URL	Jul 01 2026, 02:27 PM

[coderabbitai]

🧹 Nitpick comments (2)

backend/agents/social_summary.py (1)

35-35: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Duplicate prompt-hash boilerplate across agents.

The hashlib.sha256(...).hexdigest()[:12] pattern for _PROMPT_HASH is repeated verbatim in backend/agents/study_guide.py. As more agents are added under this pattern, consider extracting a small shared helper (e.g. agents/_providers.py::prompt_version(prompt: str) -> str) to avoid re-implementing this in every new agent module.

♻️ Suggested helper

+# agents/_providers.py+def prompt_version(system_prompt: str) -> str:+ import hashlib+ return hashlib.sha256(system_prompt.encode("utf-8")).hexdigest()[:12]

-import hashlib-
from pydantic import BaseModel, Field
from pydantic_ai import Agent
-from agents._providers import model_for+from agents._providers import model_for, prompt_version
from agents.deps import SaplingDeps
...
-_PROMPT_HASH = hashlib.sha256(_SYSTEM_PROMPT.encode("utf-8")).hexdigest()[:12]+_PROMPT_HASH = prompt_version(_SYSTEM_PROMPT)

Also applies to: 38-44

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@backend/agents/social_summary.py` at line 35, Duplicate prompt-hash
boilerplate is repeated in social_summary and study_guide; extract the shared
SHA-256 truncation logic into a small helper such as
agents/_providers.py::prompt_version(prompt: str) -> str, then update
_PROMPT_HASH in each agent module to call it instead of re-implementing
hashlib.sha256(...).hexdigest()[:12].

backend/agents/study_guide.py (1)

43-62: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

LGTM! Typed output correctly mirrors the legacy JSON contract, matching result.output.model_dump() usage in routes/study_guide.py. Same prompt-hash duplication note as in agents/social_summary.py applies here (see that comment) — extracting a shared helper would avoid re-implementing this in future agents.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@backend/agents/study_guide.py` around lines 43 - 62, The prompt hash logic is
duplicated in study_guide agent setup and should be centralized to match the
shared pattern used by other agents. Extract the SHA-256 prompt-version
calculation into a reusable helper and have study_guide_agent build its metadata
from that helper instead of re-implementing the hash inline. Keep the existing
_SYSTEM_PROMPT, _PROMPT_HASH, and study_guide_agent symbols as the integration
points when refactoring.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@backend/agents/social_summary.py`:
- Line 35: Duplicate prompt-hash boilerplate is repeated in social_summary and
study_guide; extract the shared SHA-256 truncation logic into a small helper
such as agents/_providers.py::prompt_version(prompt: str) -> str, then update
_PROMPT_HASH in each agent module to call it instead of re-implementing
hashlib.sha256(...).hexdigest()[:12].
In `@backend/agents/study_guide.py`:
- Around line 43-62: The prompt hash logic is duplicated in study_guide agent
setup and should be centralized to match the shared pattern used by other
agents. Extract the SHA-256 prompt-version calculation into a reusable helper
and have study_guide_agent build its metadata from that helper instead of
re-implementing the hash inline. Keep the existing _SYSTEM_PROMPT, _PROMPT_HASH,
and study_guide_agent symbols as the integration points when refactoring.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: e33a7124-0193-4aba-988a-15fecc891aae

📥 Commits

Reviewing files that changed from the base of the PR and between d86edde and 1b816cecd1924d4c086d307a58ca5275e00d11c7.

📒 Files selected for processing (12)

• backend/agents/_providers.py
• backend/agents/_run.py
• backend/agents/health.py
• backend/agents/social_summary.py
• backend/agents/study_guide.py
• backend/main.py
• backend/routes/social.py
• backend/routes/study_guide.py
• backend/tests/test_gemini_test_auth.py
• backend/tests/test_oneshot_agents.py
• backend/tests/test_study_guide_routes.py
• specs/147-oneshot-llm-agents.md