pal-e-docs

Review: AI engine core (re-review after split)

review-598-2026-03-28-v2 Doc

review ready
Project

Verdict: READY

Template Completeness

  • [x] Type — Feature
  • [x] Lineage — Depends on #4 (scaffold) and #5 (basketball client). Fixed from v1 review.
  • [x] Repo — forgejo_admin/westside-ai-assistant
  • [x] User Story — As Marcus (admin), natural language → basketball-api operations
  • [x] Context — Scoped to AI engine core only; explicitly references #8 for confirmation flow
  • [x] File Targets — 2 creates, 1 modify, 2 do-not-touch
  • [x] Acceptance Criteria — 6 items (down from 9 in original)
  • [x] Test Expectations — 4 items + run command (down from 7 in original)
  • [x] Constraints — SDK, model config, system prompt rules, GroupMe bot post, 1000-char limit
  • [x] Checklist — PR, tests, no unrelated changes
  • [x] Related — project page, architecture diagram, read-ops story

Traceability

  • [x] story:read-ops — read operations story (primary: read tool dispatch)
  • [x] story:write-ops — write operations story (tool definitions with write metadata, gated execution)
  • [x] story:safety — safety story (write tools defined but not executed, confirmation indicator returned)
  • [x] arch:A2 — AI Engine component in arch-dataflow-westside-ai-assistant
  • [x] Forgejo issue — forgejo_admin/westside-ai-assistant#6, state: open

File Targets

  • [x] app/ai.py (create) — repo only has README.md on main. Valid: #4 scaffolds app/ directory.
  • [x] tests/test_ai.py (create) — valid: tests/ created by #4.
  • [x] app/groupme.py (modify) — valid: created by #4, wiring callback + bot post.
  • [x] app/basketball.py (do-not-touch) — correct: consumed as dependency from #5.
  • [x] app/config.py (do-not-touch) — correct: env vars already defined by #4.
All file targets specific and accurate. No ambiguity for the implementing agent.

Repo Placement

OK. Issue filed on forgejo_admin/westside-ai-assistant. All file targets in same repo. No cross-repo work.

Dependencies

  • [x] #4 (FastAPI scaffold) — explicit in Lineage. State: open. Creates app/groupme.py, app/config.py, app/__init__.py, tests/__init__.py. Now documented (was missing in v1).
  • [x] #5 (Basketball-API client) — explicit in Lineage. State: open. Creates app/basketball.py consumed by this ticket.
  • [x] #8 (Confirmation state machine) — downstream dependent on this ticket. Documented in #8's lineage. No circular dependency.
Execution order: #4 → #5 → #6 → #8. All dependencies documented and correctly ordered.

Acceptance Criteria

6 ACs. Testability assessment:
  • AC 1 (read query → tool called → GroupMe post) — testable via mocked Anthropic response + mocked GroupMe POST.
  • AC 2 (14 tool definitions, 7 reads + 7 writes, with metadata) — testable via tool definition introspection. Requires #5 complete to verify function counts.
  • AC 3 (write tools defined but NOT executed, returns confirmation indicator) — testable: mock a write tool_use, assert basketball function NOT called, assert indicator returned.
  • AC 4 (conversation history capped at 20 per group) — testable: clear boundary condition.
  • AC 5 (plain text responses, no HTML/markdown) — testable: assert no HTML tags or markdown syntax in output.
  • AC 6 (truncate at 1000 chars with "...") — testable: boundary condition at 1000/1001 chars.
All criteria are concrete and individually verifiable by an agent.

Blast Radius

  • No other services in the platform use the Anthropic SDK — zero shared-library risk.
  • AI engine is self-contained. Only integration surface: basketball-api (consumed read-only via basketball.py from #5).
  • GroupMe bot posting is net-new — no existing bot behavior to conflict with.
  • Rollback: revert the PR, GroupMe callback falls back to logging-only behavior from #4.

Decomposition

  • File targets: 2 creates + 1 modify in 1 repo. Under 3-file-across-2-repos threshold.
  • Acceptance criteria: 6 items. Marginally above 5-item threshold, but all are cohesive (single-concern: AI engine core).
  • Test expectations: 4 items in 1 test file.
  • Discrete changes: 3 (system prompt + tool definitions, process_message with read dispatch + conversation history, GroupMe wiring). At the 3-thing limit.
  • Estimated agent time: ~5 minutes. Tool definitions are mechanical (mirror basketball.py functions). System prompt is a single string constant. GroupMe wiring is a small modification.
No decomposition needed. The confirmation state machine — the complex, independently testable concern — has been successfully split to #8. Remaining work is cohesive and fits a single agent pass.

Previous Review Issues — Resolution

  • [BODY] Missing #4 dependency — RESOLVED. Lineage now reads: "Depends on forgejo_admin/westside-ai-assistant #4 (scaffold) and #5 (basketball client)."
  • [DECOMPOSE] 9 ACs exceeding threshold — RESOLVED. Confirmation flow (ACs 2-5 from original) moved to #8. This ticket now has 6 ACs, 4 test expectations, ~5 min estimated time.

Recommendation

No action needed. Ticket is ready for dispatch.