@manasija/max

v1.1.6

Published

9 days ago

Max - AI agent for deep financial research.

0High
0Medium
0Low

Max 🤖

Max is an autonomous financial research agent that thinks, plans, and learns as it works. It performs analysis using task planning, self-reflection, and real-time market data. Think Claude Code, but built specifically for financial research.

⚠️ Disclaimer

This project is for educational, entertainment, and informational purposes only. It is not intended for real trading or investment.

Not financial, investment, tax, or legal advice
No guarantees of accuracy, completeness, or fitness for any purpose
Outputs may be incorrect, incomplete, or out of date
Creator and contributors assume no liability for any financial losses or damages
Consult a licensed financial advisor before making investment decisions
Past performance does not indicate future results

By using this software, you agree to use it solely for learning and informational purposes and accept all risks associated with its use.

👋 Overview

Max takes complex financial questions and turns them into clear, step-by-step research plans. It runs those tasks using live market data, checks its own work, and refines the results until it has a confident, data-backed answer.

Key Capabilities:

Intelligent Task Planning: Automatically decomposes complex queries into structured research steps
Autonomous Execution: Selects and executes the right tools to gather financial data
Self-Validation: Checks its own work and iterates until tasks are complete
Real-Time Financial Data: Access to income statements, balance sheets, and cash flow statements
Safety Features: Built-in loop detection and step limits to prevent runaway execution

✅ Prerequisites

Bun runtime (v1.0 or higher)
OpenAI API key (get here)
Drishti API key (get one from the Drishti platform console)
Exa API key (get here) - optional, for web search

Installing Bun

If you don't have Bun installed, you can install it using curl:

macOS/Linux:

curl -fsSL https://bun.com/install | bash

Windows:

powershell -c "irm bun.sh/install.ps1|iex"

After installation, restart your terminal and verify Bun is installed:

bun --version

💻 How to Install

Clone the repository:

git clone https://github.com/manasijatech/max.git
cd max

Install dependencies with Bun:

bun install

Set up your environment variables:

# Copy the example environment file
cp env.example .env

# Edit .env and add your API keys (if using cloud providers)
# OPENAI_API_KEY=your-openai-api-key
# ANTHROPIC_API_KEY=your-anthropic-api-key (optional)
# GOOGLE_API_KEY=your-google-api-key (optional)
# XAI_API_KEY=your-xai-api-key (optional)
# OPENROUTER_API_KEY=your-openrouter-api-key (optional)

# Drishti Indian market data
# DRISHTI_API_KEY=your-drishti-api-key
# DRISHTI_BASE_URL=https://developers.manasija.in

# (Optional) If using Ollama locally
# OLLAMA_BASE_URL=http://127.0.0.1:11434

# Web Search (Exa preferred, Tavily fallback)
# EXASEARCH_API_KEY=your-exa-api-key
# TAVILY_API_KEY=your-tavily-api-key

🚀 How to Run

Run instantly with npx (no clone required)

Max is published as a Node CLI, so you can run it without installing anything globally:

npx @manasija/max

This launches the interactive terminal UI under Node (v18+). On first run, Max walks you through adding your API keys — no file editing required (see below).

To install it as a persistent command:

npm install -g @manasija/max
max                  # start the CLI
max gateway login    # link WhatsApp (scan QR), then:
max gateway run      # start the WhatsApp gateway

Run from source (for development)

bun start      # interactive mode
bun dev        # watch mode
bun run build  # produce the Node bundle in dist/

🔑 API Keys & Configuration

You never have to hand-edit a .env file. Max can collect and store keys securely from inside the CLI.

First-run onboarding. If your selected LLM provider key or the Drishti data key is missing, Max automatically opens the key manager on startup.
/keys command. Run /keys anytime to add, update, or remove a key for any LLM provider, Drishti, or a web-search provider. Keys are entered masked.

Where keys are stored. Keys are saved to ~/.max/credentials with owner-only (0600) permissions — not in your project directory. All other config (settings, memory, scratchpad, caches) also lives under ~/.max/.

Precedence. A key set in your shell environment or a project .env always wins over the stored credential, so existing setups keep working. Environment variable names are unchanged (e.g. OPENAI_API_KEY, ANTHROPIC_API_KEY, DRISHTI_API_KEY, EXASEARCH_API_KEY).

MAX_HOME. Override the config directory (e.g. for testing or multiple profiles) by setting MAX_HOME to a directory path:

MAX_HOME=~/.max-work npx @manasija/max

🇮🇳 Drishti Research Tools

Max includes Drishti-native composite tools for Indian-market research:

company_research: one-company dossier across metadata, news, important announcements, earnings, concalls, alerts, and upcoming events.
earnings_analysis: results pack for a symbol and optional quarter, combining earnings filings, earnings tables, concalls, transcript URLs, announcements, news, and alerts.
earnings_metric_comparison: comparison of Drishti earnings_table metrics across companies or quarters, preserving metric keys, units, values, and growth fields.
portfolio_brief: weighted portfolio or watchlist brief across Drishti daily summary, metadata, news, important announcements, alerts, and upcoming events.
peer_group_research: supplied peer-set comparison across Drishti sector/industry/theme metadata, market cap, earnings, concalls, news, filings, alerts, and events.
market_pulse: broad or watchlist pulse across news, important announcements, alerts, upcoming earnings, upcoming concalls, and optional daily summary.
price_volume_signal_explainer: price, volume, relative-volume, and 52-week alert explainer using Drishti alert reasons, primary drivers, news, filings, and optional result context.
result_season_tracker: result-season coverage across reported earnings index, concall index, upcoming events, result announcements, significant earnings details, and news context.
concall_source_pack: multi-company concall source pack with batch transcript/audio URL resolution, concall summaries, earnings context, and result announcements.
filing_source_pack: source-document pack that discovers announcement/earnings records and resolves Drishti attachment URLs for PDFs and filings.
orders_capex_tracker: order-win, tender, capex, expansion, partnership, approval, and business-development tracker with execution context.
corporate_action_monitor: category-aware monitor for dividends, capital actions, M&A, management changes, orders, capex, legal/regulatory updates, and presentations.
governance_monitor: governance pack across management/promoter changes, compliance/legal events, ownership/capital actions, negative news, alerts, and concall commentary.
risk_monitor: risk pack across negative news, legal/regulatory announcements, important alerts, and concall red flags.
event_calendar: event pack across upcoming earnings, upcoming concalls, meeting-intimation announcements, and recent result/call filings.

📊 How to Evaluate

Max includes an evaluation suite that tests the agent against a dataset of financial questions. Evals use LangSmith for tracking and an LLM-as-judge approach for scoring correctness.

Run on all questions:

bun run src/evals/run.ts

Run on a random sample of data:

bun run src/evals/run.ts --sample 10

The eval runner displays a real-time UI showing progress, current question, and running accuracy statistics. Results are logged to LangSmith for analysis.

🐛 How to Debug

Max logs all tool calls to a scratchpad file for debugging and history tracking. Each query creates a new JSONL file in ~/.max/scratchpad/.

Scratchpad location:

~/.max/scratchpad/
├── 2026-01-30-111400_9a8f10723f79.jsonl
├── 2026-01-30-143022_a1b2c3d4e5f6.jsonl
└── ...

Each file contains newline-delimited JSON entries tracking:

init: The original query
tool_result: Each tool call with arguments, raw result, and LLM summary
thinking: Agent reasoning steps

Example scratchpad entry:

{"type":"tool_result","timestamp":"2026-01-30T11:14:05.123Z","toolName":"get_income_statements","args":{"ticker":"AAPL","period":"annual","limit":5},"result":{...},"llmSummary":"Retrieved 5 years of Apple annual income statements showing revenue growth from $274B to $394B"}

This makes it easy to inspect exactly what data the agent gathered and how it interpreted results.

📱 How to Use with WhatsApp

Chat with Max through WhatsApp by linking your phone to the gateway. Messages you send to yourself are processed by Max and responses are sent back to the same chat.

Quick start:

# Link your WhatsApp account (scan QR code)
bun run gateway:login

# Start the gateway
bun run gateway

Then open WhatsApp, go to your own chat (message yourself), and ask Max a question.

For detailed setup instructions, configuration options, and troubleshooting, see the WhatsApp Gateway README.

🤝 How to Contribute

Fork the repository
Create a feature branch
Commit your changes
Push to the branch
Create a Pull Request

Important: Please keep your pull requests small and focused. This will make it easier to review and merge.

📄 License

This project is licensed under the MIT License.

🙏 Credits

This project is forked from virattt/dexter, an autonomous agent for deep financial research.