Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/astrxnomo/financial-analytics-agent/llms.txt

Use this file to discover all available pages before exploring further.

By the end of this guide you will have a fully working instance of the Financial Analytics Agent running on your local machine — seeded database, live Mistral model, chart-rendering chat UI, and all. The setup requires no paid infrastructure beyond a Mistral API key and a Postgres database; both can be provisioned for free with the services recommended below.

​
Prerequisites

Before you begin, make sure you have the following installed and available:
  • Node.js 24.x — the project’s engines field pins "node": "24.x". Use nvm or fnm to manage versions if needed.
  • pnpm — the project uses pnpm exclusively (pnpm-lock.yaml, pnpm-workspace.yaml). Install with npm install -g pnpm if you don’t have it.
  • A Postgres database — Neon is recommended (it’s what the Vercel deployment uses), but any Postgres 15+ instance works. Neon’s free tier is sufficient for local development.
  • A Mistral API key — create one at console.mistral.ai. The project uses mistral-medium-2508, which is a metered model — keep an eye on your quota if you run evals or high-volume testing.

​
Setup

1

Clone the repository

Clone the repo, move into the project directory, and install all dependencies with pnpm:
git clone https://github.com/astrxnomo/financial-analytics-agent.git
cd financial-analytics-agent
pnpm install
2

Configure environment variables

Create a .env.local file at the project root. This file is gitignored — never commit it.
# .env.local
DATABASE_URL=postgres://user:password@host/dbname   # your Postgres connection string
MISTRAL_API_KEY=your_mistral_api_key_here
If you are using Neon, copy the connection string from your Neon project dashboard. For a local Postgres instance the string typically looks like postgres://postgres:password@localhost:5432/finance.
3

Run database migrations

Apply the schema to your Postgres database:
pnpm db:migrate
This creates the four core tables — departments, categories, transactions, and budgets — as defined in db/schema.sql.
4

Seed the database

Populate the database with synthetic financial data:
pnpm db:seed
The seed script generates approximately 3 years of deterministic synthetic data using a fixed RNG seed (mulberry32 in agent/lib/rng.ts), so re-running the seed always reproduces the exact same numbers. The data is carefully authored — not just random noise — with specific stories baked in: yearly revenue seasonality, compounding subscription growth with a recurring churn dip, recurring marketing campaign spikes, a cloud infrastructure step-change from a platform migration, contractor project ramps, and a handful of deliberate outliers so every chart type and anomaly detector has something real to show.
5

Start the development server

Start the Next.js development server:
pnpm dev
Next.js starts on port 3000. The eve agent is mounted via withEve() in next.config.ts and handles requests at /eve/v1/* automatically — no separate process is needed.
6

Open the chat and try a question

Navigate to http://localhost:3000 in your browser. You should see the Northwind Labs analyst chat interface with suggested question chips populated from your seeded data.Try asking:
“Show me the revenue trend for the last 6 months”
The agent will call get_trend, query Postgres through the shared analytics library, and render an inline Recharts line chart alongside a short written interpretation. Try follow-up questions like “Which department went over budget this month?” or “Any unusual transactions this quarter?” to exercise the other tool types.

​
Verification

After setup, confirm everything is wired up correctly: TypeScript typecheck — verify there are no type errors across the entire project: 
pnpm typecheck
Unit tests — run the test suite (includes both unit tests and database-gated integration tests, so DATABASE_URL must be set in .env.local): 
pnpm test
A passing pnpm test run confirms that the shared analytics library returns correct results against your seeded data and that the Zod schemas for all tool inputs are valid.

​
Headless agent testing

You can verify the agent works in isolation — without starting Next.js — using the eve headless dev runner: 
pnpm exec eve dev --no-ui
This starts only the eve agent runtime and opens an interactive session in your terminal. You can send messages directly to test tool behavior and model responses without the web UI in the loop. This works because the agent’s tools call agent/lib/finance.ts directly against Postgres rather than going through the REST API, so no Next.js process is required.

​
Next steps

Architecture

Deep dive into how the web chat, REST API, and agent share a single analytics library.

Analytics Tools

Learn about all eight analytics functions and the charts they produce.

API Reference

Explore the read-only Finance REST API for direct integration.

Build docs developers (and LLMs) love

Get started for freeTalk to us