# AGENT.md - Project Context for AI Agents

> This file provides context for AI coding assistants working on this repository.

## Project Overview

**bcra-connector** is a Python library that provides a typed, robust interface to the APIs published by Argentina's Central Bank (Banco Central de la República Argentina - BCRA).

### Purpose

- Simplify access to BCRA public financial data
- Provide strongly-typed dataclasses for all API responses
- Handle rate limiting, retries, and error cases automatically
- Support bilingual contexts (Spanish API / English wrapper)

### Target Users

- Python developers integrating BCRA data into applications
- Data scientists analyzing Argentine economic indicators
- Financial analysts requiring programmatic access to exchange rates

---

## Architecture

```
bcra-connector/
├── src/bcra_connector/
│   ├── __about__.py           # Single source of truth for version
│   ├── bcra_connector.py      # Main BCRAConnector class
│   ├── rate_limiter.py        # Rate limiting configuration
│   ├── timeout_config.py      # Timeout configuration
│   ├── principales_variables/ # Monetary statistics models
│   ├── cheques/               # Check (cheque) data models
│   └── estadisticas_cambiarias/ # Exchange rate models
├── tests/
│   ├── unit/                  # Unit tests with mocks
│   └── integration/           # Live API tests
├── docs/source/               # Sphinx documentation
└── examples/                  # Usage examples
```

### Key Design Decisions

1. **Dataclasses over Dicts**: All API responses are parsed into typed dataclasses
2. **Optional pandas**: DataFrame support via `to_dataframe()` (requires `pip install bcra-connector[pandas]`)
3. **Fail-safe**: Built-in retry logic with exponential backoff
4. **No auth required**: BCRA APIs are public, no tokens needed

---

## Development Conventions

### Versioning

- **Single source**: `src/bcra_connector/__about__.py`
- `docs/source/conf.py` imports version automatically
- Never edit `_version.py` (auto-generated by hatch)

### Branching

- `main`: Stable releases
- `feature/issue-N-description`: Feature branches
- `fix/issue-N-description`: Bug fixes

### Commands

```bash
# Run tests
pytest tests/ -v --cov=bcra_connector

# Lint and format
pre-commit run --all-files

# Build docs
cd docs && sphinx-build -b html source build/html
```

### Release Process

See [AGENT_WORKFLOW.md](.github/AGENT_WORKFLOW.md) for detailed SOP.

---

## BCRA APIs Covered

| API | Version | Status |
|-----|---------|--------|
| Estadísticas Monetarias (Principales Variables) | v4.0 | ✅ Implemented |
| Cheques Denunciados | v1.0 | ✅ Implemented |
| Estadísticas Cambiarias | v1.0 | ✅ Implemented |
| Central de Deudores | v1.0 | ❌ Not yet |

---

## Dependencies

### Runtime

- `requests` - HTTP client
- `numpy`, `scipy` - Numerical operations
- `pandas` (optional) - DataFrame support

### Dev

- `pytest`, `pytest-cov` - Testing
- `sphinx`, `sphinx_rtd_theme` - Documentation
- `black`, `isort`, `mypy` - Code quality
- `pre-commit` - Git hooks

---

## Links

- [PyPI Package](https://pypi.org/project/bcra-connector/)
- [Documentation](https://bcra-connector.readthedocs.io/)
- [BCRA API Catalog](https://www.bcra.gob.ar/Catalogo/apis.asp)
