Implement RPC contract validation baseline

agent.md

@@ -1,9 +1,27 @@
-# Agent Instructions
+# MosaicIQ - Agent Instructions & Project Documentation
 
 You are helping implement **MosaicIQ**, an AI-native equity research workspace.
 
 Use the attached **MosaicIQ Design Document v3** as the primary reference for product intent, UX direction, architecture, screen specs, agent behavior, and implementation details. This file is intentionally light; the design doc contains the fuller guidance.
 
+## Required Environment Variables
+
+**`PI_API_KEY` is required.** This application uses the Pi API (Inflection AI) for all LLM operations. The application will not function without this key set.
+
+```bash
+export PI_API_KEY=your_pi_api_key_here
+```
+
+### API Details
+
+- **Provider**: Pi (Inflection AI)
+- **Base URL**: `https://api.pi.ai/v1/chat/completions`
+- **Client**: Custom fetch-based client in `packages/shared/src/llm/client.ts`
+- **Model**: `pi` (default)
+- **Features**: Streaming and non-streaming completions, structured JSON responses
+
+All agent execution, memo generation, and AI-powered features depend on this API key.
+
 ## Core Direction
 
 Build a clean, fast, local-first equity research application with a **t3-code-style architecture**:
@@ -109,3 +127,157 @@ Refer back to the MosaicIQ Design Document v3. It contains additional helpful in
 - Accessibility and keyboard shortcuts
 
 Default to the design doc unless it conflicts with a newer explicit instruction.
+
+---
+
+# LLM Client Reference
+
+The Pi API client is located at `packages/shared/src/llm/client.ts`.
+
+## Available Functions
+
+### `streamResponse(prompt, options)`
+Stream a response from Pi with progress callbacks.
+
+```typescript
+import { streamResponse } from "@mosaiciq/shared/llm";
+
+const response = await streamResponse("Analyze this data", {
+  model: "pi",              // Optional, defaults to "pi"
+  maxTokens: 4096,          // Optional, defaults to 4096
+  temperature: 0,           // Optional, defaults to 0
+  onProgress: (text) => console.log(text),  // Optional progress callback
+  signal: abortSignal,      // Optional AbortSignal for cancellation
+});
+```
+
+### `complete(prompt, options)`
+Get a complete response without streaming.
+
+```typescript
+import { complete } from "@mosaiciq/shared/llm";
+
+const response = await complete("Summarize this report", {
+  model: "pi",
+  maxTokens: 2048,
+  temperature: 0.5,
+});
+```
+
+### `streamStructuredResponse(prompt, schema, options)`
+Stream a response and parse as JSON using the provided schema.
+
+```typescript
+import { streamStructuredResponse } from "@mosaiciq/shared/llm";
+
+const result = await streamStructuredResponse(
+  "Extract financial metrics",
+  {
+    revenue: "number",
+    growth: "number",
+    margin: "number",
+  },
+  {
+    onProgress: (text) => updateUI(text),
+    signal,
+  }
+);
+```
+
+### `completeStructured(prompt, schema, options)`
+Get a complete structured JSON response.
+
+```typescript
+import { completeStructured } from "@mosaiciq/shared/llm";
+
+const data = await completeStructured(
+  "Parse this earnings report",
+  {
+    eps: "number",
+    revenue: "string",
+    guidance: "string",
+  }
+);
+```
+
+### `isConfigured()`
+Check if the Pi API key is properly configured.
+
+```typescript
+import { isConfigured } from "@mosaiciq/shared/llm";
+
+if (!isConfigured()) {
+  console.error("PI_API_KEY is not set");
+}
+```
+
+## Usage in Agents
+
+When implementing agents that use the Pi API:
+
+```typescript
+import { streamResponse, isConfigured } from "../llm/client.js";
+
+export async function executeMyAgent(db: Db, companyId: string) {
+  if (!isConfigured()) {
+    throw new Error("PI_API_KEY is not configured");
+  }
+
+  const prompt = buildAgentPrompt(context);
+
+  const result = await streamResponse(prompt, {
+    onProgress: (text) => updateProgress(text),
+    signal,
+  });
+
+  return result;
+}
+```
+
+---
+
+# Monorepo Structure
+
+```
+local_research_app/
+├── apps/
+│   ├── desktop/          # Electron main process (RPC server, file I/O)
+│   └── web/              # React web UI (client)
+├── packages/
+│   ├── contracts/        # Shared TypeScript types (RPC, domain models)
+│   └── shared/           # Shared utilities, DB, LLM client, agents
+├── docs/
+│   └── architecture.md   # Architecture documentation
+├── agent.md              # This file - agent instructions
+├── pnpm-workspace.yaml   # PNPM workspace configuration
+└── package.json          # Root package.json
+```
+
+---
+
+# Key Files by Concern
+
+## RPC Layer
+- `packages/contracts/src/rpc.ts` - RPC method definitions and types
+- `apps/desktop/src/rpc.ts` - RPC server implementation
+- `apps/web/src/rpcClient.ts` - RPC client wrapper
+
+## Data Layer
+- `packages/shared/src/db/database.ts` - SQLite database setup
+- `packages/shared/src/db/schema.ts` - Database schema
+- `packages/shared/src/db/queries.ts` - Database query functions
+
+## LLM Layer
+- `packages/shared/src/llm/client.ts` - Pi API client
+- `packages/shared/src/llm/prompts.ts` - Agent prompt templates
+- `packages/shared/src/llm/context.ts` - Context building for agents
+
+## Agents
+- `packages/shared/src/agents/runner.ts` - Individual agent execution
+- `packages/shared/src/agents/executor.ts` - Agent pipeline orchestration
+- `packages/shared/src/agents/index.ts` - Agent registry and exports
+
+## Export
+- `packages/shared/src/export/excel.ts` - Excel export (ExcelJS)
+- `packages/shared/src/export/pdf.ts` - PDF export
+- `packages/shared/src/export/pptx.ts` - PowerPoint export (PptxGenJS)