finance_agent

finance_agent is a Python-based financial data agent designed to collect, cache, analyze, and query stock market data from multiple financial data sources.

The initial implementation focuses on the Taiwan stock market using data from Yahoo Finance.

---

Repo Introduction

Below is the introduction of files in this repo:

./
├── docs
│   └── design_doc_v1.md
├── finance_agent
│   ├── agent
│   │   └── __...
│   ├── config
│   │   └── __...
│   ├── database
│   │   └── __...
│   ├── tools
│   │   └── __...
│   └── utils
│       └── __...
├── labs
│   └── yfinance_study.ipynb
├── LICENSE
├── main.py
├── pyproject.toml
├── README.md
├── tests
└── uv.lock

• finance_agent/

  • Main Python package of the project.
  • Can be installed as a reusable package using:

    pip install financial-stock-agent
    

  • Contains the core implementation of the finance agent system.

• finance_agent/agent/

  • Holds the implementation of AI agents and orchestration logic.
  • Responsible for handling user requests and coordinating tools/services.

• finance_agent/config/

  • Stores configuration-related modules.
  • Used for environment settings, constants, and application configuration management.

• finance_agent/database/

  • Contains database access and persistence logic.
  • Responsible for interacting with SQLite/PostgreSQL and managing cached financial data.

• finance_agent/tools/

  • Provides reusable tools and integrations.
  • Examples include Yahoo Finance data fetchers, stock screeners, or dividend analyzers.

• finance_agent/utils/

  • Utility/helper functions shared across the project.
  • Includes common helpers such as logging, date formatting, and data conversion.

• labs/

  • Used for experimental code, prototypes, and research notebooks.
  • Safe place for trying ideas before moving them into production code.
  • Example:
    • yfinance_study.ipynb — experimentation with the yfinance package.

• docs/

  • Stores project documentation.
  • Includes system design documents, architecture notes, API specs, and development guides.
  • Example:
    • design_doc_v1.md — initial system design document.

• tests/

  • Contains unit tests and integration tests.
  • Used to validate application behavior and ensure code quality.

• pyproject.toml

  • Python project configuration file.
  • Defines dependencies, package metadata, build system, and tooling configuration.

• uv.lock

  • Dependency lock file generated by uv.
  • Ensures reproducible package installation across environments.

• README.md

  • Main project overview and onboarding document.
  • Typically includes setup instructions, usage examples, and project goals.

• LICENSE

  • Defines the software license and usage permissions of the project.

Features

Data Collection

• Pull historical stock market data from Yahoo Finance
• Support Taiwan stock symbols (e.g. 2330.TW, 0050.TW)
• Scheduled or on-demand data synchronization

Local Database Cache

• Store pulled historical data locally
• Initial database backend: SQLite
• Designed for future migration to PostgreSQL or other databases

Agent-Based Query Interface

Users can interact with the agent using natural language queries such as:

• "Stocks that increased over 5% today"
• "Stocks with dividend yield over 5%"
• "Top gaining Taiwan stocks this week"
• "Show historical price trend for TSMC"

Extensible Architecture

Planned future support:

• Multiple financial data providers
• Additional stock markets
• LLM-powered financial analysis
• Technical indicators
• Portfolio tracking
• REST API / Web UI

---

Usages

The finance_agent package exposes a Google Agent Development Kit (ADK) root_agent that can be launched using the adk CLI in three modes:

1. Interactive CLI (adk run)

Run the agent interactively in your terminal or execute a single query:

# Enter interactive chat mode
adk run finance_agent/agent

# Run a single prompt directly
adk run finance_agent/agent "Get stock info of 2330.TW"

Tip: You can suppress framework UserWarning messages by setting PYTHONWARNINGS="ignore::UserWarning":

PYTHONWARNINGS="ignore::UserWarning" adk run finance_agent/agent

---

2. Web Interface (adk web)

Launch the FastAPI server with a built-in Web UI:

adk web finance_agent

By default, the Web UI is available at http://127.0.0.1:8000.

---

3. REST API Server (adk api_server)

Launch the REST API server on a custom port (e.g., port 8888):

adk api_server finance_agent --port 8888

Interacting with the API Server via curl

Step 1: Create a Session

curl -X POST "http://127.0.0.1:8888/apps/agent/users/user1/sessions/session1" \
  -H "Content-Type: application/json" \
  -d '{}'

Step 2: Send a Prompt to /run

curl -X POST "http://127.0.0.1:8888/run" \
  -H "Content-Type: application/json" \
  -d '{
    "appName": "agent",
    "userId": "user1",
    "sessionId": "session1",
    "newMessage": {
      "role": "user",
      "parts": [
        { "text": "Get the stock info of 2330.TW." }
      ]
    }
  }'

---

Tech Stack

• Python
• SQLite
• Yahoo Finance
• yfinance
• SQLAlchemy (planned)
• Pandas