financial-stock-agent 0.1.0

A agent to facilitate querying and processing finance data.

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

---

Tech Stack

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