Skip to main content

Agent AI Assistant — Feature Summary

One-pager for what's shipped on devagentai and how to use it. Branch: devagentai (based on dev). Deployed at https://dev1.strykr.io.

What it is​

An AI assistant FAB (floating action button) embedded in the agent panel that turns plain-English requests into structured actions against the platform's agent surface. Mounted on every /agent/* route. Reuses the existing AI command backend (backend/src/ai) and adds an agent-specific tool catalogue, system prompt, UI cards, report engine, and confirmation flow.

Capabilities​

Read — information retrieval (no confirmation)​

  • Downline view — full agent → sub-agent → player hierarchy with balances.
  • Player search — fuzzy name match scoped to your downline; never invents IDs.
  • Take & credit limit — per-player take/CL/available; positive take = player owes the agent, negative = the agent owes the player.
  • Live exposure — open retained + forwarded liability + potential win, bucketed by scope (sport / market / fixture); optional fixture or market filter.
  • Bet history — recent bets across the downline, filterable by player, fixture, status, date range.

Actions — destructive, confirmation required​

  • Edit player limit — credit limit, per-click win cap, daily win cap, or minimum stake. Returns a diff card (before → after). Stale-read guard rejects replays where the DB drifted between display and confirm.
  • Settle player — show outstanding take + direction (player pays / agent pays) + settlement components; on confirm, delegates to the existing transferSettleService.createSettlement for atomicity.
  • Create player — onboard a new player under the caller agent with optional initial balance debit; same atomic pattern as POST /agent/invite-player.
  • Place hedge bet — reuses existing placeBet; orderService.placeOrder auto-routes agent userIds to their self-player account.

Reports​

  • 4 canonical templates (agent_generateReport):
    • per_player_pnl — Player / Bet count / Stake / Net P&L / Commission / Open bets.
    • bet_log — every bet row with filters for player, fixture, market, date.
    • settlement_log — transfer-settlement rows.
    • pnl_by_match_market — aggregated stake / winnings / P&L / commission per (fixture × market).
  • 3 formats for each: xlsx | csv | pdf (per-template support varies; see the design doc).
  • Custom report (agent_customReport) — when no template fits. The LLM writes a structured spec; an allowlist validator enforces what's queryable. Examples that work: "stake by sport", "players who lost > 5000 last month", "settlements > 500 grouped by counterparty".
  • Share with a player (agent_shareReport) — grants the recipient download permission and sends a notification with the link.
  • Downloadable artifacts persist 24h (Redis TTL on metadata, file on a named Docker volume). Owner + explicit recipients can download; everyone else gets 403.

Proactive notifications (live triggers)​

  • Player login — fires on /credential-login and /dev-login for the player; the player's direct upline agent gets a Player active toast. Per-(agent, player) 24h dedupe.
  • Large bet — fires when a downline player stakes ≥ 500 FP. Notification links into bet history filtered by the order ID.
  • Market settled — fires when settlement.processSettlement completes for a market the downline had exposure on. Aggregates per-upline-agent net P&L and links into bet history filtered by fixture+market.
  • Mute keys — each event can be muted per agent via a Redis key (ai-agent-notif:mute:{agentUserId}:{event}).

UX​

  • Single command window — the agent FAB does not show the player-facing Chat / Commands / Analysis tab strip. It opens directly into the command input + chat history.
  • 11 rich UI cards rendered from structured tool output: downline tree, take table, exposure card, bet table, player picker, P&L table, commission table, settlement table, settlement summary, diff card, report artifact.
  • Page-context injection — every request to /api/ai/command includes the current URL + query params in metadata, so the assistant resolves "this player" or "this market" without re-asking when the user is on a relevant page.

Quick access​

  • URL — https://dev1.strykr.io.
  • Login — Login modal exposes "Dev Login" (form-based, no password). Useful agents to try: pm (full downline), dev1ag1 (separate tree), Platform Treasury (sees everything).
  • Open the FAB — spark/lightning button at bottom-left of any /agent/* page. Mobile: same FAB; opens as a bottom sheet.
  • Example prompts (Commands tab):
    • "show me my downline tree"
    • "what's the take and credit limit for all my players"
    • "show my live exposure on cricket"
    • "show recent bets from my downline"
    • "edit credit limit for pm_player to 1000"
    • "generate per_player_pnl xlsx report"
    • "csv showing total stake grouped by status across my downline"
    • "share the per_player_pnl report with pm_player"
    • "add a new player named p1 under me"

Stack​

  • Backend — Node 20, TypeScript, Express, Prisma, Anthropic SDK (Claude Sonnet 4 for the orchestrator), exceljs + pdfkit for report rendering.
  • Frontend — Next.js, React, Zustand, Tailwind. The FAB reuses the existing AIPanel / AIMobileSheet / CommandChat components.
  • Storage — Postgres for everything durable; Redis for short-lived state (conversation history, artifact metadata, dedupe / mute keys, win-cap aggregates); a named Docker volume strykr-dev1_ai-reports for artifact bytes (24h TTL aligned to Redis).
  • Tests — vitest. 69/69 green across the AI surface (agent tools + custom-report validator). Phase-3 destructive tools have stale-read / drift-rejection coverage.

Out of scope this iteration​

  • Bulk per-player JPEG reports (needs a chart-render lib choice — chartjs-node-canvas vs sharp+canvas vs html→image).
  • Customise report columns UI (needs a column_picker UI component + multi-step generate flow).

Where to read more​

  • Design doc — docs/ai-agent-fab/DESIGN.md — architecture, file map, data flow, tool semantics, security model, pitfalls.
  • Phase 0 spec — docs/ai-agent-fab/PHASE0_SPEC.md — the original contract (mostly historical now; the design doc supersedes it).