Replace 7 read tools with generic read-only api_get tool

forgejo_admin commented

2026-03-31 00:24:58 +00:00

Owner

Type

Feature

Lineage

Standalone — simplifies Nemo's read architecture so new basketball-api endpoints (jerseys, schedules, billing) work automatically.

Repo

forgejo_admin/westside-ai-assistant

User Story

As Marcus (admin)
I want to ask Nemo any question about the program data
So that I don't have to wait for new tools to be added every time basketball-api gets a new endpoint

Context

Nemo currently has 7 hand-coded read tools (get_dashboard, list_players, get_player, list_teams, get_roster, get_subscriptions_overview, list_subscriptions). Each maps to one basketball-api endpoint. When new endpoints land (jersey orders, schedules, billing tiers), Nemo can't access them without a code change.

Replace all 7 read tools with a single generic api_get tool that accepts a path and makes a GET request to basketball-api. Claude determines the correct endpoint from the user's question. The Keycloak service account already has admin access.

Safety: the tool MUST enforce GET-only at the code level. No POST/PUT/DELETE/PATCH regardless of what path is passed. Write operations stay as explicit confirmed tools.

File Targets

Files to modify:

app/ai.py — replace 7 read tool definitions with 1 api_get tool, remove _execute_read_tool dispatch, add generic GET executor, update system prompt with available endpoint examples
app/basketball.py — add generic get(path) method (GET only, no body)

Files NOT to touch:

app/confirmation.py — write confirmation unchanged
app/groupme.py — webhook handler unchanged
Write tools in ai.py — keep all 7 write tools with confirmation

Acceptance Criteria

Single api_get tool replaces all 7 read tools
api_get enforces GET method at code level (not prompt level)
No request body is ever sent through api_get
System prompt lists example endpoints for Claude to reference
Existing write tools + confirmation flow unchanged
"How many players?" still works (regression)
"Who ordered jerseys?" works if basketball-api has the endpoint

Test Expectations

Unit test: api_get calls GET only, rejects POST/mutation paths if any validation added
Unit test: tool definition has correct schema
Integration test: end-to-end message → tool call → response
Run command: pytest tests/ -k test_api_get

Constraints

GET only. Hardcoded method="GET" in the execution function. No parameter to override.
Keep write tools as-is — do not genericize writes
Update SYSTEM_PROMPT with endpoint examples so Claude knows what's available

Checklist

PR opened
Tests pass
No unrelated changes

project-westside-basketball — parent project
basketball-api #257 (jersey fields) — once merged, Nemo auto-gains access via api_get

### Type Feature ### Lineage Standalone — simplifies Nemo's read architecture so new basketball-api endpoints (jerseys, schedules, billing) work automatically. ### Repo `forgejo_admin/westside-ai-assistant` ### User Story As Marcus (admin) I want to ask Nemo any question about the program data So that I don't have to wait for new tools to be added every time basketball-api gets a new endpoint ### Context Nemo currently has 7 hand-coded read tools (get_dashboard, list_players, get_player, list_teams, get_roster, get_subscriptions_overview, list_subscriptions). Each maps to one basketball-api endpoint. When new endpoints land (jersey orders, schedules, billing tiers), Nemo can't access them without a code change. Replace all 7 read tools with a single generic `api_get` tool that accepts a path and makes a GET request to basketball-api. Claude determines the correct endpoint from the user's question. The Keycloak service account already has admin access. Safety: the tool MUST enforce GET-only at the code level. No POST/PUT/DELETE/PATCH regardless of what path is passed. Write operations stay as explicit confirmed tools. ### File Targets Files to modify: - `app/ai.py` — replace 7 read tool definitions with 1 `api_get` tool, remove `_execute_read_tool` dispatch, add generic GET executor, update system prompt with available endpoint examples - `app/basketball.py` — add generic `get(path)` method (GET only, no body) Files NOT to touch: - `app/confirmation.py` — write confirmation unchanged - `app/groupme.py` — webhook handler unchanged - Write tools in `ai.py` — keep all 7 write tools with confirmation ### Acceptance Criteria - [ ] Single `api_get` tool replaces all 7 read tools - [ ] `api_get` enforces GET method at code level (not prompt level) - [ ] No request body is ever sent through `api_get` - [ ] System prompt lists example endpoints for Claude to reference - [ ] Existing write tools + confirmation flow unchanged - [ ] "How many players?" still works (regression) - [ ] "Who ordered jerseys?" works if basketball-api has the endpoint ### Test Expectations - [ ] Unit test: api_get calls GET only, rejects POST/mutation paths if any validation added - [ ] Unit test: tool definition has correct schema - [ ] Integration test: end-to-end message → tool call → response - Run command: `pytest tests/ -k test_api_get` ### Constraints - GET only. Hardcoded `method="GET"` in the execution function. No parameter to override. - Keep write tools as-is — do not genericize writes - Update SYSTEM_PROMPT with endpoint examples so Claude knows what's available ### Checklist - [ ] PR opened - [ ] Tests pass - [ ] No unrelated changes ### Related - `project-westside-basketball` — parent project - basketball-api #257 (jersey fields) — once merged, Nemo auto-gains access via api_get

forgejo_admin commented

2026-03-31 00:32:43 +00:00

Author

Owner

Scope Review: NEEDS_REFINEMENT

Review note: review-721-2026-03-30
Well-scoped issue with verified file targets, but traceability gaps need fixing before dispatch.

[LABEL] story:WS-S5 does not match this ticket's user story. WS-S5 is about CNPG databases (superadmin) or registration dashboard stats (admin). This ticket needs a new story ID for "ask Nemo any question about program data."
[SCOPE] No architecture note exists for arch-westside-ai-assistant. Create arch-westside-ai-assistant in pal-e-docs.
[BODY] Related section references project-westside-ai-assistant but pal-e-docs project slug is westside-basketball.

## Scope Review: NEEDS_REFINEMENT Review note: `review-721-2026-03-30` Well-scoped issue with verified file targets, but traceability gaps need fixing before dispatch. - **[LABEL]** story:WS-S5 does not match this ticket's user story. WS-S5 is about CNPG databases (superadmin) or registration dashboard stats (admin). This ticket needs a new story ID for "ask Nemo any question about program data." - **[SCOPE]** No architecture note exists for arch-westside-ai-assistant. Create arch-westside-ai-assistant in pal-e-docs. - **[BODY]** Related section references `project-westside-ai-assistant` but pal-e-docs project slug is `westside-basketball`.

forgejo_admin commented

2026-03-31 00:33:32 +00:00

Author

Owner

Scope refinement (review-721-2026-03-30):

Fixed Related section: project-westside-ai-assistant → project-westside-basketball (correct parent project)
Board label: arch:westside-ai-assistant → arch:basketball-api (references existing arch component, no missing arch note)
Story label kept as story:WS-S5 — this ticket serves WS-S5 ("view registration stats on a dashboard") by giving Nemo generic read access to all admin data including dashboard stats. The generic tool is a superset of what WS-S5 needs.

**Scope refinement (review-721-2026-03-30):** 1. Fixed `Related` section: `project-westside-ai-assistant` → `project-westside-basketball` (correct parent project) 2. Board label: `arch:westside-ai-assistant` → `arch:basketball-api` (references existing arch component, no missing arch note) 3. Story label kept as `story:WS-S5` — this ticket serves WS-S5 ("view registration stats on a dashboard") by giving Nemo generic read access to all admin data including dashboard stats. The generic tool is a superset of what WS-S5 needs.

forgejo_admin commented

2026-03-31 00:37:22 +00:00

Author

Owner

Scope Review: READY

Review note: review-721-2026-03-30-r2
Re-review after refinement. All three issues from review-721-2026-03-30 resolved:

story:WS-S5 superset justification accepted (generic api_get enables dashboard stats reads)
arch:basketball-api label verified against arch-deployment-westside-basketball service inventory
Related section correctly references project-westside-basketball

Ticket is ready for dispatch.

## Scope Review: READY Review note: `review-721-2026-03-30-r2` Re-review after refinement. All three issues from `review-721-2026-03-30` resolved: - story:WS-S5 superset justification accepted (generic api_get enables dashboard stats reads) - arch:basketball-api label verified against arch-deployment-westside-basketball service inventory - Related section correctly references project-westside-basketball Ticket is ready for dispatch.