forgejo_admin/westside-ai-assistant
1
0
Fork 0
Code Issues 13 Pull requests Projects Releases Packages Wiki Activity Actions

AI engine core: Anthropic integration, tool definitions, GroupMe response posting #6

New issue
Closed
opened 2026-03-28 19:15:32 +00:00 by forgejo_admin · 3 comments
forgejo_admin commented 2026-03-28 19:15:32 +00:00
Owner
Copy link

Type

Feature

Lineage

Depends on forgejo_admin/westside-ai-assistant #4 (scaffold) and #5 (basketball client).

Repo

forgejo_admin/westside-ai-assistant

User Story

As Marcus (admin)
I want to send natural language messages and have the AI interpret them as basketball-api operations
So that I can manage the program without learning API endpoints or UI navigation

Context

This is the AI engine core — Anthropic Claude tool_use integration with read-only dispatch. The system prompt defines the assistant's role and safety rules. Each basketball.py function becomes an Anthropic tool definition. This ticket handles read operations (immediate execution) and the GroupMe response posting. Write confirmation flow is handled in #8 (separate ticket).

File Targets

Files the agent should create:

  • app/ai.py — AI engine: system prompt, 14 tool definitions (7 reads + 7 writes, all tagged with read/write metadata), conversation history (in-memory dict, last 20 messages per group, lost on restart), process_message() entry point that calls Anthropic and executes read tools immediately
  • tests/test_ai.py — tool dispatch, response formatting, conversation history management

Files the agent should modify:

Files the agent should NOT touch:

  • app/basketball.py — consumed as-is from #5
  • app/config.py — should already have all needed env vars from #4

Acceptance Criteria

  • Read query ("What's Jaylen's height?") → correct tool called → response posted to GroupMe
  • Tool definitions for all 14 operations (7 reads, 7 writes) with read/write metadata tag
  • Write tools defined but NOT executed — process_message() returns a "confirmation needed" indicator for writes (actual confirmation handling in #8)
  • Conversation history limited to 20 messages per group, in-memory only
  • GroupMe responses are plain text, concise, no HTML/markdown
  • GroupMe message limit: truncate with "..." if longer than 1000 chars

Test Expectations

  • Unit test: mock Anthropic response with read tool_use, verify correct basketball function called
  • Unit test: mock Anthropic response with write tool_use, verify NOT executed (returns confirmation indicator)
  • Unit test: conversation history capped at 20
  • Unit test: GroupMe post called with correct bot_id and text
  • Run command: pytest tests/test_ai.py -v

Constraints

  • Use anthropic Python SDK
  • Model: configured via ANTHROPIC_MODEL env var (default claude-sonnet-4-6-20250514)
  • System prompt must instruct Claude to: respond concisely for GroupMe, use plain text only, never expose internal tool names to user
  • GroupMe bot post: POST to https://api.groupme.com/v3/bots/post with {"bot_id": GROUPME_BOT_ID, "text": response}
  • Write tools must be DEFINED (so Claude knows about them) but execution is gated — this ticket returns a signal, #8 handles the confirmation UX

Checklist

  • PR opened
  • Tests pass
  • No unrelated changes

Related

  • project-westside-ai-assistant — parent project
  • arch-dataflow-westside-ai-assistant — full message flow
  • story-westside-ai-assistant-read-ops — read operations story
### Type Feature ### Lineage Depends on forgejo_admin/westside-ai-assistant #4 (scaffold) and #5 (basketball client). ### Repo `forgejo_admin/westside-ai-assistant` ### User Story As Marcus (admin) I want to send natural language messages and have the AI interpret them as basketball-api operations So that I can manage the program without learning API endpoints or UI navigation ### Context This is the AI engine core — Anthropic Claude tool_use integration with read-only dispatch. The system prompt defines the assistant's role and safety rules. Each basketball.py function becomes an Anthropic tool definition. This ticket handles read operations (immediate execution) and the GroupMe response posting. Write confirmation flow is handled in #8 (separate ticket). ### File Targets Files the agent should create: - `app/ai.py` — AI engine: system prompt, 14 tool definitions (7 reads + 7 writes, all tagged with read/write metadata), conversation history (in-memory dict, last 20 messages per group, lost on restart), process_message() entry point that calls Anthropic and executes read tools immediately - `tests/test_ai.py` — tool dispatch, response formatting, conversation history management Files the agent should modify: - `app/groupme.py` — wire callback to ai.process_message(), post AI response to GroupMe via bot API (POST https://api.groupme.com/v3/bots/post with bot_id + text) Files the agent should NOT touch: - `app/basketball.py` — consumed as-is from #5 - `app/config.py` — should already have all needed env vars from #4 ### Acceptance Criteria - [ ] Read query ("What's Jaylen's height?") → correct tool called → response posted to GroupMe - [ ] Tool definitions for all 14 operations (7 reads, 7 writes) with read/write metadata tag - [ ] Write tools defined but NOT executed — process_message() returns a "confirmation needed" indicator for writes (actual confirmation handling in #8) - [ ] Conversation history limited to 20 messages per group, in-memory only - [ ] GroupMe responses are plain text, concise, no HTML/markdown - [ ] GroupMe message limit: truncate with "..." if longer than 1000 chars ### Test Expectations - [ ] Unit test: mock Anthropic response with read tool_use, verify correct basketball function called - [ ] Unit test: mock Anthropic response with write tool_use, verify NOT executed (returns confirmation indicator) - [ ] Unit test: conversation history capped at 20 - [ ] Unit test: GroupMe post called with correct bot_id and text - Run command: `pytest tests/test_ai.py -v` ### Constraints - Use `anthropic` Python SDK - Model: configured via ANTHROPIC_MODEL env var (default claude-sonnet-4-6-20250514) - System prompt must instruct Claude to: respond concisely for GroupMe, use plain text only, never expose internal tool names to user - GroupMe bot post: POST to https://api.groupme.com/v3/bots/post with {"bot_id": GROUPME_BOT_ID, "text": response} - Write tools must be DEFINED (so Claude knows about them) but execution is gated — this ticket returns a signal, #8 handles the confirmation UX ### Checklist - [ ] PR opened - [ ] Tests pass - [ ] No unrelated changes ### Related - `project-westside-ai-assistant` — parent project - `arch-dataflow-westside-ai-assistant` — full message flow - `story-westside-ai-assistant-read-ops` — read operations story
forgejo_admin commented 2026-03-28 19:21:11 +00:00
Author
Owner
Copy link

Scope Review: NEEDS_REFINEMENT

Review note: review-598-2026-03-28

Template is complete and traceability triangle is solid (3 story labels + arch:A2 + open issue). File targets verified against repo state. However, 9 ACs + 7 test expectations exceed the 5-item decomposition threshold and estimated agent time is 8-12 minutes.

Issues found:

  • [BODY] Lineage is missing explicit dependency on #4 (FastAPI scaffold). Currently only lists #5 but #4 creates app/groupme.py, app/config.py, and tests/__init__.py which this ticket requires. Update to: "Depends on #4 (scaffold) and #5 (basketball client)."
  • [DECOMPOSE] Recommend splitting into 2 sequential tickets:
    • 6a: AI engine core — system prompt, 14 tool definitions, process_message() with read-only dispatch, conversation history, GroupMe response posting (ACs 1, 6, 7, 8, 9)
    • 6b: Confirmation state machine — pending action store, 5-min expiry, yes/no handling, write tools gated on confirmation (ACs 2, 3, 4, 5)
## Scope Review: NEEDS_REFINEMENT Review note: `review-598-2026-03-28` Template is complete and traceability triangle is solid (3 story labels + arch:A2 + open issue). File targets verified against repo state. However, **9 ACs + 7 test expectations exceed the 5-item decomposition threshold** and estimated agent time is 8-12 minutes. **Issues found:** - **[BODY]** Lineage is missing explicit dependency on #4 (FastAPI scaffold). Currently only lists #5 but #4 creates `app/groupme.py`, `app/config.py`, and `tests/__init__.py` which this ticket requires. Update to: "Depends on #4 (scaffold) and #5 (basketball client)." - **[DECOMPOSE]** Recommend splitting into 2 sequential tickets: - **6a: AI engine core** — system prompt, 14 tool definitions, process_message() with read-only dispatch, conversation history, GroupMe response posting (ACs 1, 6, 7, 8, 9) - **6b: Confirmation state machine** — pending action store, 5-min expiry, yes/no handling, write tools gated on confirmation (ACs 2, 3, 4, 5)
forgejo_admin changed title from Anthropic AI engine with tool definitions and confirmation flow to AI engine core: Anthropic integration, tool definitions, GroupMe response posting 2026-03-28 19:24:52 +00:00
forgejo_admin commented 2026-03-28 19:26:12 +00:00
Author
Owner
Copy link

Scope refinement (review-598-2026-03-28):

  1. Added #4 (scaffold) to dependencies alongside #5
  2. Split ticket: confirmation state machine moved to new #8. This ticket now covers AI engine core only (read dispatch, tool definitions, conversation history, GroupMe response posting). Write tools are defined but execution is gated — #8 handles the confirmation UX.
**Scope refinement (review-598-2026-03-28):** 1. Added #4 (scaffold) to dependencies alongside #5 2. Split ticket: confirmation state machine moved to new #8. This ticket now covers AI engine core only (read dispatch, tool definitions, conversation history, GroupMe response posting). Write tools are defined but execution is gated — #8 handles the confirmation UX.
forgejo_admin commented 2026-03-28 19:30:46 +00:00
Author
Owner
Copy link

Scope Review: READY

Review note: review-598-2026-03-28-v2

Re-review after refinement. Both issues from v1 review resolved:

  • [BODY] Lineage now includes #4 (scaffold) explicitly alongside #5 — fixed.
  • [DECOMPOSE] Confirmation state machine successfully split to #8. This ticket is now 6 ACs, 4 test expectations, 3 discrete changes, ~5 min estimated agent time. Fits a single agent pass.

All template sections complete. Traceability triangle solid (3 story labels + arch:A2 + open issue). File targets verified. Dependencies documented and correctly ordered (#4 → #5 → #6 → #8). No blast radius concerns.

## Scope Review: READY Review note: `review-598-2026-03-28-v2` Re-review after refinement. Both issues from v1 review resolved: - **[BODY]** Lineage now includes #4 (scaffold) explicitly alongside #5 — fixed. - **[DECOMPOSE]** Confirmation state machine successfully split to #8. This ticket is now 6 ACs, 4 test expectations, 3 discrete changes, ~5 min estimated agent time. Fits a single agent pass. All template sections complete. Traceability triangle solid (3 story labels + arch:A2 + open issue). File targets verified. Dependencies documented and correctly ordered (#4 → #5 → #6 → #8). No blast radius concerns.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
No results found.
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
forgejo_admin/westside-ai-assistant#6
No description provided.