Skip to content

README.md

Latest commit

 

History

History
126 lines (92 loc) · 3.6 KB

README.md

File metadata and controls

126 lines (92 loc) · 3.6 KB

Note

Containerized with Docker Commit Style in mind. (2025-10-27) still getting out of the AI rabbit hole about documenting it all

2025-10-23 DBJ : FinAgy - Autonomous Financial Research Agent

2025-10-23 DBJ : Now fully functional with Alpha Vantage API integration! 🎯

FunAgy

Overview

FinAgy 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

  • Python 3.10 or higher
  • uv package manager
  • OpenAI API key (get here)

Installation

  1. Clone the repository:
git clone https://github.com/dbjharmony/finagy.git
cd finagy
  1. Install dependencies with uv:
uv sync
  1. Set up your environment variables:
# Copy the example environment file
cp env.example .env

# Edit .env and add your API keys
# OPENAI_API_KEY=your-openai-api-key
# FINANCIAL_DATASETS_API_KEY=your-financial-datasets-api-key

Usage

Run FinAgy in interactive mode:

uv run finagy-agent

Example Queries

Try asking FinAgy questions like:

  • "What was Apple's revenue growth over the last 4 quarters?"
  • "Compare Microsoft and Google's operating margins for 2023"
  • "Analyze Tesla's cash flow trends over the past year"
  • "What is Amazon's debt-to-equity ratio based on recent financials?"

FinAgy will automatically:

  1. Break down your question into research tasks
  2. Fetch the necessary financial data
  3. Perform calculations and analysis
  4. Provide a comprehensive, data-rich answer

Architecture

FinAgy uses a multi-agent architecture with specialized components:

  • Planning Agent: Analyzes queries and creates structured task lists
  • Action Agent: Selects appropriate tools and executes research steps
  • Validation Agent: Verifies task completion and data sufficiency
  • Answer Agent: Synthesizes findings into comprehensive responses

Project Structure

finagy/
├── src/
│   ├── finagy/
│   │   ├── agent.py      # Main agent orchestration logic
│   │   ├── model.py      # LLM interface
│   │   ├── tools.py      # Financial data tools
│   │   ├── prompts.py    # System prompts for each component
│   │   ├── schemas.py    # Pydantic models
│   │   ├── utils/        # Utility functions
│   │   └── cli.py        # CLI entry point
├── pyproject.toml
└── uv.lock

Configuration

FinAgy supports configuration via the Agent class initialization:

from finagy.agent import Agent

agent = Agent(
    max_steps=20,              # Global safety limit
    max_steps_per_task=5       # Per-task iteration limit
)

How to Contribute

  1. Fork the repository
  2. Create a feature branch
  3. Commit your changes
  4. Push to the branch
  5. 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.