Metadata-Version: 2.4
Name: financial-stock-agent
Version: 0.1.0
Summary: A agent to facilitate querying and processing finance data.
Project-URL: Homepage, https://github.com/johnklee/finance_agent
Project-URL: Repository, https://github.com/johnklee/finance_agent
Project-URL: Issues, https://github.com/johnklee/finance_agent/issues
Author-email: "John K. Lee" <puremonkey2007@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agent,finance,stock-market,taiwan,yfinance
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.12
Requires-Dist: html5lib>=1.1
Requires-Dist: ipykernel>=7.2.0
Requires-Dist: jupyter>=1.1.1
Requires-Dist: lxml>=6.1.1
Requires-Dist: matplotlib>=3.10.9
Requires-Dist: pandas-datareader>=0.10.0
Requires-Dist: pandas<3.0.0
Requires-Dist: plotly>=6.8.0
Requires-Dist: twstock>=1.5.1
Requires-Dist: yfinance>=1.3.0
Description-Content-Type: text/markdown

# 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:
    ```bash
    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
