building-financial-apps

When to use this skill

• Building or refactoring stock-terminal-next.
• Implementing AI Chat interfaces in financial apps.
• When the user mentions "Zero-Parsing", "Protocol Fragility", or "Vercel AI SDK".
• Streaming structured data (charts, widgets) alongside text.

Workflow

[ ] Backend: Implement AIStreamProtocol in FastAPI (SSE with Type Codes 0, 2, 9). [ ] Agent: Use Gemini 3.0/1.5 with Pydantic schemas (structured output) to enforce valid JSON for widgets. [ ] Frontend: Use ai/react (useChat) and zustand (State) instead of manual fetch loops. [ ] Testing: Verify streaming protocol using httpx (backend) and msw (frontend).

Instructions

1. The Executive Vision: Zero-Parsing

Stop parsing LLM output with Regex. Strictly separate Content (Text) from Data (Tool Calls, Charts).

• Text -> Stream 0: "content"
• Data (Widgets) -> Stream 2: [{"chart": ...}]
• Tool Calls -> Stream 9: {...}

2. Backend Implementation (FastAPI)

Protocol Helper (backend/protocol.py)

import json
from typing import Any

class AIStreamProtocol:
    @staticmethod
    def text(content: str) -> str:
        """Type 0: Text Part"""
        return f'0:{json.dumps(content)}\n'

    @staticmethod
    def data(payload: Any) -> str:
        """Type 2: Data Part (Widgets, Charts). Must be a list."""
        return f'2:{json.dumps([payload])}\n'

    @staticmethod
    def tool_call(call_id: str, name: str, args: dict) -> str:
        """Type 9: Tool Call"""
        payload = {"toolCallId": call_id, "toolName": name, "args": args}
        return f'9:{json.dumps(payload)}\n'

Structured Agent (backend/agent.py)

Use Pydantic V2 to enforce schema.

class AgentResponse(BaseModel):
    part: Union[LineChart, TextResponse]

# When streaming:
# yield AIStreamProtocol.text(chunk.text)
# yield AIStreamProtocol.data(widget_object)

3. Frontend Architecture (React 19)

Global State (src/store/dashboardStore.ts)

Use Zustand to hold the "active chart" state, avoiding prop drilling.

interface DashboardState {
  activeChart: ChartData | null;
  setActiveChart: (chart: ChartData | null) => void;
}
export const useDashboardStore = create<DashboardState>((set) => ({ ... }));

Custom Hook (useTerminalChat.ts)

Use useChat from Vercel AI SDK. Listen for data events to update global state.

import { useChat } from 'ai/react';
export function useTerminalChat() {
  const setActiveChart = useDashboardStore((s) => s.setActiveChart);
  const { messages, data } = useChat({
    api: 'http://localhost:8001/chat',
  });

  // Effect: Update chart when new Data (Type 2) arrives
  useEffect(() => {
    if (!data) return;
    const latest = data[data.length - 1];
    if (latest && latest.type === 'line_chart') setActiveChart(latest);
  }, [data, setActiveChart]);
  
  return { messages };
}

4. Testing Strategy

• Backend: Use httpx to consume the streaming response line-by-line and assert 0: and 2: prefixes.
• Frontend: Use msw to mock the SSE stream (TextEncoder -> controller.enqueue).

Resources

• Vercel AI SDK Docs
• Gemini Structured Outputs