ARGUS is a Python-based market analytics project evolving from a small FX converter into a broader data-oriented platform for exchange rates, market data, analytics, dashboards, and future AI-assisted monitoring workflows.
Note
This project started as FX Converter Lab and is being renamed to ARGUS as the scope grows beyond simple currency conversion.
ARGUS is currently focused on building a clean local foundation:
- currency conversion using live exchange-rate data
- calculator and conversion logic
- input validation and error handling
- Tkinter GUI prototype
- legacy CLI/debug interface
- first pandas/matplotlib-based analytics prototype
- tests and documentation
Important
ARGUS is not a finished trading tool or financial advisor.
It is a portfolio and learning project for building reliable data, analytics, visualization and future automation workflows.
This project is licensed under the Apache License 2.0.
ARGUS is designed to grow step by step from a local Python application into a market analytics and monitoring system.
The long-term direction includes:
- market data ingestion
- historical FX and market data analysis
- reusable analytics and metric layers
- dashboards and visualizations
- local and cloud-based storage
- data quality checks
- reporting workflows
- future AI-assisted research and agentic monitoring
Tip
The goal is to keep each development step usable and testable instead of building a large system all at once.
The full project roadmap is maintained separately in docs/roadmap.md.
Each roadmap phase is treated as a separate development sprint. The roadmap describes how ARGUS is planned to grow from a local Python application into a broader market analytics, data engineering and future AI-assisted monitoring system.
Tip
The README gives a compact project overview.
Detailed planning, sprint scope and long-term architecture notes live in the documentation files.
- Calculator
- Currency conversion using live exchange rates
- Input validation and error handling
- Tkinter GUI prototype
- Legacy CLI/debug interface
- Basic pandas-based trend metrics
- Matplotlib-based trend visualization
- Mock time-series data for early analytics development
- Basic test suite
Caution
Historical market data support is still limited.
The current live exchange-rate client is useful for simple conversion, but future analytics work will require additional data sources such as Frankfurter or yfinance.
docs/
src/
argus/
analytics/
charts/
metrics/
clients/
domain/
gui/
services/
config.py
main.py
legacy/
cli/
tests/
pyproject.toml
README.md
- Python 3.11+
- requests
- python-dotenv
- pandas
- NumPy
- matplotlib
- Tkinter
- pytest
- ExchangeRate API for live currency conversion
ARGUS is expected to grow into a broader data and analytics system.
Planned or likely future technologies include:
- Frankfurter API for historical FX data
- yfinance for broader market data
- possible additional market-data APIs later
- pandas
- NumPy
- possibly Polars later for larger datasets
- PostgreSQL
- DuckDB
- Parquet
- optional cloud storage
- matplotlib
- Plotly
- NiceGUI
- GitHub Actions
- Docker
- Docker Compose
- cloud deployment later
- Azure, GCP or AWS depending on project direction
- scheduled ingestion
- data quality checks
- reporting pipelines
- LLM-assisted summaries
- RAG over stored reports or notes
- agentic data checks
- anomaly monitoring
- human-in-the-loop signal review
Caution
AI and agentic features are future-stage ideas.
They should only be added after the data, storage, service and reporting layers are stable.
Before running ARGUS locally, make sure you have:
- Python 3.11 or newer
- Git
- pip
- an ExchangeRate API key for live currency conversion
Recommended for development:
- VS Code
- a virtual environment
- pytest
Note
Runtime dependencies are managed through pyproject.toml.
Clone the repository:
git clone https://github.com/BytecodeBrewer/argus.git
cd argusCreate a virtual environment:
python -m venv .venvActivate the virtual environment.
On Windows PowerShell:
.venv\Scripts\Activate.ps1On macOS/Linux:
source .venv/bin/activateInstall the project in editable mode:
pip install -e .For development and tests, install the development dependencies:
pip install -e ".[dev]"Tip
Editable install keeps the project linked to your local source files. This means code changes are picked up without reinstalling the project after every edit.
ARGUS currently uses the ExchangeRate API for live currency conversion.
Create a free account at ExchangeRate API and generate your personal API key.
Create a file named .env in the project root:
.env
Add your API key:
api_key=your_api_key_hereThe .env file must stay local and should never be committed.
Warning
Never commit API keys, tokens or secrets to the repository.
Make sure .env is listed in .gitignore.
Start the current Tkinter GUI:
python -m argus.mainThis starts the local ARGUS prototype with calculator, currency conversion and basic analytics views.
The legacy CLI is still available for quick local checks and debugging:
python src/legacy/debug_main.pyNote
The Tkinter GUI is the current main local interface. The CLI is kept as a legacy/debug interface and is not the long-term product interface.
Run the test suite:
pytestTip
Run tests after changing clients, services, validation logic or analytics functions.
More detailed project documentation lives in docs/.
Current documentation:
docs/roadmap.md— sprint-based project roadmapdocs/gui.md— notes about the current Tkinter GUI prototype- metric and UI research notes for future analytics and interface decisions
ARGUS is under active development.
The project is currently transitioning from a small FX converter into a broader market analytics platform.
Current focus:
- finish Sprint 1 foundation
- prepare first public release
- improve README and project documentation
- keep the application runnable and testable
- prepare the next analytics and data-source expansion