@pi-stef/finance 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stefano Fiorini
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# @pi-stef/finance
+
+Pi extension client for `@pi-stef/finance-api` — exposes portfolio state, drift, and deterministic suggestions to the pi agent.
+
+## Install
+
+```bash
+pi install npm:@pi-stef/finance
+```
+
+Or via catalog:
+```bash
+/ct add npm:@pi-stef/finance
+```
+
+## Prerequisites
+
+The `@pi-stef/finance-api` service must be running (Docker or native). See the [finance-api README](../finance-api/README.md) for setup.
+
+## Configuration
+
+Set environment variables or create `~/.pi/sf/finance/config.json`:
+
+```json
+{
+  "apiUrl": "http://127.0.0.1:7780",
+  "token": "your-bearer-token"
+}
+```
+
+Environment variables (prefix `SF_FINANCE_`):
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SF_FINANCE_API_URL` | `http://127.0.0.1:7780` | Finance API URL |
+| `SF_FINANCE_TOKEN` | (from `~/.pi/sf/finance/token`) | Bearer token for API auth |
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `sf_fin_market_status` | Get current US market session |
+| `sf_fin_get_holdings` | Get all account holdings |
+| `sf_fin_get_net_worth` | Get total portfolio value |
+| `sf_fin_get_drift` | Get allocation drift vs target |
+| `sf_fin_get_allocation` | Get current asset allocation |
+| `sf_fin_list_goals` | List investment goals |
+| `sf_fin_set_target` | Create/update investment goal |
+| `sf_fin_get_suggestions` | Get pending suggestions |
+| `sf_fin_dismiss_suggestion` | Dismiss a suggestion |
+| `sf_fin_sync_now` | Trigger immediate data sync |
+| `sf_fin_import_file` | Import holdings from CSV/OFX |
+| `sf_fin_history` | Get price history |
+
+## Usage
+
+Ask the pi agent:
+- "What's my current portfolio allocation?"
+- "How far am I from my target allocation?"
+- "What should I buy/sell to rebalance?"
+- "Import my Fidelity positions from ~/Downloads/positions.csv"
+
+## Disclaimer
+
+**This is not financial advice.** The suggestions are computed deterministically from your configured goals and current holdings. The LLM applies judgment but never recomputes the numbers. Always consult a qualified financial advisor before making investment decisions.
+
+## License
+
+[MIT](../../LICENSE)

package/extensions/finance.ts

@@ -0,0 +1,6 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerFinanceTools } from "../src/index";
+
+export default function financeExtension(pi: ExtensionAPI): void {
+  registerFinanceTools(pi);
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@pi-stef/finance",
+  "version": "0.1.1",
+  "description": "Pi extension client for @pi-stef/finance-api: exposes portfolio state, drift, and deterministic suggestions to the pi agent.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sfiorini/pi-stef.git",
+    "directory": "packages/finance"
+  },
+  "homepage": "https://sfiorini.github.io/pi-stef/packages/finance.html",
+  "files": [
+    "src/",
+    "extensions/"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "finance",
+    "portfolio",
+    "investing"
+  ],
+  "dependencies": {
+    "@pi-stef/paths": "^0.3.0",
+    "@pi-stef/finance-api": "^0.1.0",
+    "@sinclair/typebox": "*"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ]
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  }
+}

package/src/client.ts

@@ -0,0 +1,96 @@
+// HTTP client for finance-api service
+// Maps operations to GET/POST methods per the M7 contract table
+
+// Explicit op→path mapping matching server routes exactly
+export const OP_PATH: Record<string, string> = {
+  market_status: "/v1/market-status",
+  get_holdings: "/v1/holdings",
+  get_net_worth: "/v1/net-worth",
+  get_drift: "/v1/drift",
+  get_allocation: "/v1/allocation",
+  list_goals: "/v1/goals",
+  set_target: "/v1/goals",
+  get_suggestions: "/v1/suggestions",
+  dismiss_suggestion: "/v1/suggestions/dismiss",
+  sync_now: "/v1/sync",
+  import_file: "/v1/import",
+  history: "/v1/history",
+  health: "/v1/health",
+  export: "/v1/export",
+};
+
+export const OP_METHOD: Record<string, "GET" | "POST"> = {
+  market_status: "GET",
+  get_holdings: "GET",
+  get_net_worth: "GET",
+  get_drift: "GET",
+  get_allocation: "GET",
+  list_goals: "GET",
+  set_target: "POST",
+  get_suggestions: "GET",
+  dismiss_suggestion: "POST",
+  sync_now: "POST",
+  import_file: "POST",
+  history: "GET",
+  health: "GET",
+  export: "POST",
+};
+
+export interface FinanceClientConfig {
+  apiUrl: string;
+  token: string;
+}
+
+export interface CallResult<T = unknown> {
+  ok: boolean;
+  data?: T;
+  error?: { code: string; message: string };
+  staleAt?: number | null;
+  staleReason?: string | null;
+}
+
+export function createFinanceClient(config: FinanceClientConfig) {
+  const { apiUrl, token } = config;
+
+  async function callOp<T = unknown>(op: string, params?: Record<string, unknown>): Promise<T> {
+    const method = OP_METHOD[op];
+    if (!method) throw new Error(`Unknown operation: ${op}`);
+    const path = OP_PATH[op];
+    if (!path) throw new Error(`No path mapping for operation: ${op}`);
+
+    const url = new URL(`${apiUrl}${path}`);
+    const headers: Record<string, string> = {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json",
+    };
+
+    let body: string | undefined;
+    if (method === "GET" && params) {
+      for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined && value !== null) {
+          url.searchParams.set(key, String(value));
+        }
+      }
+    } else if (method === "POST" && params) {
+      body = JSON.stringify(params);
+    }
+
+    let res: Response;
+    try {
+      res = await fetch(url.toString(), { method, headers, body });
+    } catch (err) {
+      throw new Error(`service_unavailable: ${err instanceof Error ? err.message : String(err)}`);
+    }
+
+    const json = await res.json() as CallResult<T>;
+    if (!json.ok) {
+      throw new Error(`${json.error?.code ?? "unknown"}: ${json.error?.message ?? "Unknown error"}`);
+    }
+
+    return json.data as T;
+  }
+
+  return { callOp };
+}
+
+export type FinanceClient = ReturnType<typeof createFinanceClient>;

package/src/config.ts

@@ -0,0 +1,39 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { globalConfig, globalDir } from "@pi-stef/paths";
+
+export interface FinanceConfig {
+  apiUrl: string;
+  token: string;
+}
+
+export async function loadFinanceConfig(
+  env: Record<string, string | undefined> = process.env,
+  homeDir: string = process.env.HOME ?? process.cwd(),
+): Promise<FinanceConfig> {
+  let fileToken = "";
+  let fileUrl = "";
+  try {
+    const raw = JSON.parse(await readFile(globalConfig("finance", homeDir), "utf8")) as Partial<FinanceConfig>;
+    fileToken = raw.token ?? "";
+    fileUrl = raw.apiUrl ?? "";
+  } catch (e) {
+    if (!(e instanceof Error && "code" in e && (e as { code: string }).code === "ENOENT")) throw e;
+  }
+  
+  // Try to read auto-generated token from ~/.pi/sf/finance/token
+  let autoToken = "";
+  if (!fileToken && !env.SF_FINANCE_TOKEN) {
+    try {
+      const tokenPath = path.join(globalDir("finance", homeDir), "token");
+      autoToken = (await readFile(tokenPath, "utf8")).trim();
+    } catch {
+      // Token file doesn't exist yet (service not started)
+    }
+  }
+  
+  return {
+    apiUrl: env.SF_FINANCE_API_URL || fileUrl || "http://127.0.0.1:7780",
+    token: env.SF_FINANCE_TOKEN || fileToken || autoToken || "",
+  };
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+// Finance extension exports
+export { loadFinanceConfig } from "./config";
+export { registerFinanceTools } from "./tools";
+export { createFinanceClient, OP_METHOD } from "./client";
+export type { FinanceClient, FinanceClientConfig } from "./client";

package/src/output.ts

@@ -0,0 +1,38 @@
+// Format structured service JSON → agent-readable text
+
+export function formatHoldings(data: { accounts: { id: string; name: string; holdings: { symbol: string; quantity: number; asset_class: string }[] }[] }): string {
+  const lines: string[] = [];
+  for (const account of data.accounts) {
+    lines.push(`Account: ${account.name} (${account.id})`);
+    for (const h of account.holdings) {
+      lines.push(`  ${h.symbol}: ${h.quantity} shares (${h.asset_class})`);
+    }
+  }
+  return lines.join("\n") || "No holdings found";
+}
+
+export function formatDrift(data: { drift: { class: string; currentPct: number; targetPct: number; deltaPct: number }[] }): string {
+  const lines: string[] = ["Allocation Drift:"];
+  for (const d of data.drift) {
+    const status = d.deltaPct > 0.02 ? "⚠️ OVER" : d.deltaPct < -0.02 ? "⚠️ UNDER" : "✓";
+    lines.push(`  ${d.class}: ${(d.currentPct * 100).toFixed(1)}% → target ${(d.targetPct * 100).toFixed(1)}% (${status})`);
+  }
+  return lines.join("\n");
+}
+
+export function formatSuggestions(data: { suggestions: { id: string; kind: string; payload: unknown }[] }): string {
+  if (data.suggestions.length === 0) return "No pending suggestions";
+  const lines: string[] = ["Pending Suggestions:"];
+  for (const s of data.suggestions) {
+    lines.push(`  [${s.kind}] ${JSON.stringify(s.payload)}`);
+  }
+  return lines.join("\n");
+}
+
+export function formatGeneric(data: unknown): string {
+  if (typeof data === "string") return data;
+  if (typeof data === "object" && data !== null) {
+    return JSON.stringify(data, null, 2);
+  }
+  return String(data);
+}

package/src/tools.ts

@@ -0,0 +1,226 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadFinanceConfig } from "./config";
+import { createFinanceClient } from "./client";
+import { formatHoldings, formatDrift, formatSuggestions, formatGeneric } from "./output";
+
+const NEVER_RECOMPUTE_GUIDELINE = "These numbers are computed by the service. Never recompute prices, allocations, or drift yourself — cite the returned values verbatim. When recommending an instrument, justify it against the engine's gap.";
+
+export function registerFinanceTools(pi: ExtensionAPI): void {
+  // Helper to get client
+  async function getClient() {
+    const config = await loadFinanceConfig();
+    return createFinanceClient({ apiUrl: config.apiUrl, token: config.token });
+  }
+
+  // Market Status
+  pi.registerTool({
+    name: "sf_fin_market_status",
+    label: "Market Status",
+    description: "Get current US market session (pre/intraday/post/closed)",
+    parameters: {},
+    promptSnippet: "Check if the US stock market is currently open.",
+    promptGuidelines: [NEVER_RECOMPUTE_GUIDELINE],
+    execute: async () => {
+      const client = await getClient();
+      const data = await client.callOp<{ session: string; timestamp: number }>("market_status");
+      return { content: [{ type: "text", text: `Market session: ${data.session}` }], details: { implemented: true } };
+    },
+  });
+
+  // Get Holdings
+  pi.registerTool({
+    name: "sf_fin_get_holdings",
+    label: "Get Holdings",
+    description: "Get all account holdings with quantities and asset classes",
+    parameters: {},
+    promptSnippet: "Retrieve current portfolio holdings across all accounts.",
+    promptGuidelines: [NEVER_RECOMPUTE_GUIDELINE],
+    execute: async () => {
+      const client = await getClient();
+      const data = await client.callOp("get_holdings");
+      return { content: [{ type: "text", text: formatHoldings(data as Parameters<typeof formatHoldings>[0]) }], details: { implemented: true } };
+    },
+  });
+
+  // Get Net Worth
+  pi.registerTool({
+    name: "sf_fin_get_net_worth",
+    label: "Get Net Worth",
+    description: "Get total portfolio value across all accounts",
+    parameters: {},
+    promptSnippet: "Calculate total portfolio value.",
+    promptGuidelines: [NEVER_RECOMPUTE_GUIDELINE],
+    execute: async () => {
+      const client = await getClient();
+      const data = await client.callOp<{ netWorth: number; accountCount: number }>("get_net_worth");
+      return { content: [{ type: "text", text: `Net Worth: $${data.netWorth.toLocaleString()} (${data.accountCount} accounts)` }], details: { implemented: true } };
+    },
+  });
+
+  // Get Drift
+  pi.registerTool({
+    name: "sf_fin_get_drift",
+    label: "Get Drift",
+    description: "Get allocation drift vs target",
+    parameters: {},
+    promptSnippet: "Check portfolio drift from target allocation.",
+    promptGuidelines: [NEVER_RECOMPUTE_GUIDELINE],
+    execute: async () => {
+      const client = await getClient();
+      const data = await client.callOp("get_drift");
+      return { content: [{ type: "text", text: formatDrift(data as Parameters<typeof formatDrift>[0]) }], details: { implemented: true } };
+    },
+  });
+
+  // Get Allocation
+  pi.registerTool({
+    name: "sf_fin_get_allocation",
+    label: "Get Allocation",
+    description: "Get current asset allocation by class",
+    parameters: {},
+    promptSnippet: "View current asset allocation breakdown.",
+    promptGuidelines: [NEVER_RECOMPUTE_GUIDELINE],
+    execute: async () => {
+      const client = await getClient();
+      const data = await client.callOp<{ allocation: Record<string, number>; totalValue: number }>("get_allocation");
+      const lines = Object.entries(data.allocation).map(([cls, pct]) => `  ${cls}: ${(pct * 100).toFixed(1)}%`);
+      return { content: [{ type: "text", text: `Asset Allocation (Total: $${data.totalValue.toLocaleString()}):\n${lines.join("\n")}` }], details: { implemented: true } };
+    },
+  });
+
+  // List Goals
+  pi.registerTool({
+    name: "sf_fin_list_goals",
+    label: "List Goals",
+    description: "List investment goals with target allocations",
+    parameters: {},
+    promptSnippet: "View configured investment goals.",
+    promptGuidelines: [NEVER_RECOMPUTE_GUIDELINE],
+    execute: async () => {
+      const client = await getClient();
+      const data = await client.callOp<{ goals: { id: string; name: string; targetAllocation: Record<string, number> }[] }>("list_goals");
+      if (data.goals.length === 0) return { content: [{ type: "text", text: "No goals configured" }], details: { implemented: true } };
+      const lines = data.goals.map((g) => `${g.name}: ${JSON.stringify(g.targetAllocation)}`);
+      return { content: [{ type: "text", text: `Investment Goals:\n${lines.join("\n")}` }], details: { implemented: true } };
+    },
+  });
+
+  // Set Target
+  pi.registerTool({
+    name: "sf_fin_set_target",
+    label: "Set Target",
+    description: "Create or update an investment goal",
+    parameters: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Goal ID" },
+        name: { type: "string", description: "Goal name" },
+        targetAllocation: { type: "object", description: "Target allocation by asset class (must sum to ~1.0)" },
+        riskLimits: { type: "object", description: "Risk limits (e.g., maxSinglePosition, maxCashDrag)" },
+        horizonYears: { type: "number", description: "Investment horizon in years" },
+      },
+      required: ["id", "name", "targetAllocation"],
+    },
+    promptSnippet: "Create or update an investment goal with target allocation.",
+    promptGuidelines: [NEVER_RECOMPUTE_GUIDELINE],
+    execute: async (params) => {
+      const client = await getClient();
+      const data = await client.callOp<{ id: string }>("set_target", params as unknown as Record<string, unknown>);
+      return { content: [{ type: "text", text: `Goal ${data.id} saved` }], details: { implemented: true } };
+    },
+  });
+
+  // Get Suggestions
+  pi.registerTool({
+    name: "sf_fin_get_suggestions",
+    label: "Get Suggestions",
+    description: "Get pending investment suggestions from the quant engine",
+    parameters: {},
+    promptSnippet: "Retrieve deterministic suggestions from the quant engine.",
+    promptGuidelines: [NEVER_RECOMPUTE_GUIDELINE],
+    execute: async () => {
+      const client = await getClient();
+      const data = await client.callOp("get_suggestions");
+      return { content: [{ type: "text", text: formatSuggestions(data as Parameters<typeof formatSuggestions>[0]) }], details: { implemented: true } };
+    },
+  });
+
+  // Dismiss Suggestion
+  pi.registerTool({
+    name: "sf_fin_dismiss_suggestion",
+    label: "Dismiss Suggestion",
+    description: "Dismiss a pending suggestion",
+    parameters: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Suggestion ID to dismiss" },
+      },
+      required: ["id"],
+    },
+    promptSnippet: "Dismiss a suggestion that's been addressed.",
+    promptGuidelines: [NEVER_RECOMPUTE_GUIDELINE],
+    execute: async (params) => {
+      const client = await getClient();
+      await client.callOp("dismiss_suggestion", params as unknown as Record<string, unknown>);
+      return { content: [{ type: "text", text: `Suggestion dismissed` }], details: { implemented: true } };
+    },
+  });
+
+  // Sync Now
+  pi.registerTool({
+    name: "sf_fin_sync_now",
+    label: "Sync Now",
+    description: "Trigger immediate data sync from all providers",
+    parameters: {},
+    promptSnippet: "Force an immediate sync of account data.",
+    promptGuidelines: [NEVER_RECOMPUTE_GUIDELINE],
+    execute: async () => {
+      const client = await getClient();
+      const data = await client.callOp<{ message: string }>("sync_now");
+      return { content: [{ type: "text", text: data.message }], details: { implemented: true } };
+    },
+  });
+
+  // Import File
+  pi.registerTool({
+    name: "sf_fin_import_file",
+    label: "Import File",
+    description: "Import holdings from a CSV/OFX file",
+    parameters: {
+      type: "object",
+      properties: {
+        filePath: { type: "string", description: "Path to CSV/OFX file" },
+      },
+      required: ["filePath"],
+    },
+    promptSnippet: "Import holdings from a file export.",
+    promptGuidelines: [NEVER_RECOMPUTE_GUIDELINE],
+    execute: async (params) => {
+      const client = await getClient();
+      const data = await client.callOp<{ message: string; filePath: string }>("import_file", params as unknown as Record<string, unknown>);
+      return { content: [{ type: "text", text: `${data.message}: ${data.filePath}` }], details: { implemented: true } };
+    },
+  });
+
+  // History
+  pi.registerTool({
+    name: "sf_fin_history",
+    label: "Price History",
+    description: "Get price history for a symbol",
+    parameters: {
+      type: "object",
+      properties: {
+        symbol: { type: "string", description: "Ticker symbol (e.g., AAPL, CRYPTO:BTC)" },
+        accountId: { type: "string", description: "Optional account ID filter" },
+      },
+      required: ["symbol"],
+    },
+    promptSnippet: "View price history for a security.",
+    promptGuidelines: [NEVER_RECOMPUTE_GUIDELINE],
+    execute: async (params) => {
+      const client = await getClient();
+      const data = await client.callOp("history", params as unknown as Record<string, unknown>);
+      return { content: [{ type: "text", text: formatGeneric(data) }], details: { implemented: true } };
+    },
+  });
+}