Metadata-Version: 2.4
Name: Back_da_dev
Version: 0.0.1
Summary: Backtesting and data-processing library for financial strategy analysis.
Author: PedroTsuchie1, Rdg-m, lucasnavis, Vicente1526
License-Expression: MIT
Project-URL: Homepage, https://github.com/your-org/fq26gp2
Project-URL: Source, https://github.com/your-org/fq26gp2
Project-URL: Tracker, https://github.com/your-org/fq26gp2/issues
Keywords: backtest,finance,trading,strategy,data-processing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matplotlib
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: requests
Requires-Dist: yfinance
Dynamic: license-file

# Back-da-dev


## FQ26.1-GP2
**FEA.dev Backtesting Lab** — Protótipos rápidos e backtesting quantitativo para estudantes e investidores curiosos.

## Sumário
- [Sobre o Projeto](#sobre-o-projeto)
- [Construído Com](#constru%C3%ADdo-com)
- [Começando](#come%C3%A7ando)
  - [Pré-requisitos](#pr%C3%A9-requisitos)
  - [Instalação](#instala%C3%A7%C3%A3o)
  - [Configuração](#configura%C3%A7%C3%A3o)
- [Uso](#uso)
  - [API Python](#api-python)
  - [CLI](#cli)
- [Documentação da API](#documenta%C3%A7%C3%A3o-da-api)
- [Testes](#testes)
- [Contribuindo](#contribuindo)
- [Licença](#licen%C3%A7a)

## Sobre o Projeto
Este repositório é um projeto de estudante da FEA.dev para backtesting rápido e prototipagem de estratégias quantitativas. O código auxilia membros da liga a explorar ideias de trading, validar sinais e gerar resumos de desempenho a partir de dados históricos.

Ele combina ingestão de dados, limpeza, execução de estratégia e visualização de resultados em um fluxo simples. O objetivo é tornar a pesquisa quant inicial rápida de iterar, mantendo conexão com conceitos reais de mercado como comissão, drawdown e resultados de trades.

## Construído Com
- Python `>=3.11`
- `pandas` para manipulação de séries temporais e pipeline de dados
- `numpy` para operações numéricas
- `matplotlib` para visualização de resultados
- `requests` para acesso a APIs
- `yfinance` para download de histórico de mercado
- `pytest` para cobertura de testes

## Começando

### Pré-requisitos
- Python `3.11` ou superior
- gerenciador de pacotes `pip`
- Opcionalmente, uma ferramenta de ambiente virtual: `venv`, `virtualenv` ou `pipenv`

### Instalação
A partir da raiz do repositório:

```bash
python -m pip install -e .
```

Se preferir um ambiente dedicado:

```bash
python -m venv .venv
source .venv/bin/activate   # Mac/Linux
.\.venv\Scripts\activate  # Windows
python -m pip install -e .
```

### Configuração
Este projeto não requer variáveis de ambiente especiais por padrão.

- Use `yfinance` como fonte padrão de dados
- Coloque arquivos locais em `./data/` ao carregar do disco
- Se precisar de outras fontes de dados, instale dependências opcionais manualmente

> Se seu fluxo de trabalho usar API externa ou credenciais privadas, adicione esses detalhes aqui mais tarde.

## Uso

### API Python
Importe o ponto de entrada público do pacote:

```python
# Example (requires data source or internet for `yfinance`):
from back_da_dev import run_standard_backtest, load_and_clean, list_strategies

result = run_standard_backtest(
  strategy="buy_and_hold",
  initial_capital=10000.0,
  commission=0.001,
  load_kwargs={"indice": "PETR4.SA", "fonte": "yfinance", "tempo": "5y"},
  save_graphs=False,
  save_log=False,
)

print(result.metrics)
```

```python
# Runnable example (no internet). Creates a tiny sample DataFrame and runs a backtest.
from .modelos_pre_implementados import buy_and_hold
initial_capital =10000.0
symbols = ['PETR4', 'VALE5', 'ITUB4']
_config['dado_real'] = False
_config['periodos'] = 15
engine = BacktestEngine(pd.DataFrame(), symbols, initial_capital)


print('Executando backtest browniano com estratégia buy_and_hold...')
strategy = buy_and_hold(initial_capital)
engine.run(strategy)

print('\nRESULTADOS DO BACKTEST')
print('Cash final:', f'R$ {engine.cash:.2f}')
print('Portfolio value final:', f'R$ {engine.portfolio_value:.2f}')
print('Posições abertas:', engine.open_positions)
print('Trades fechados:', len(engine.closed_positions))
print('Dias simulados:', len(engine.daily_history))
```

Gere um relatório após um backtest:

```python
from back_da_dev import generate_backtest_report

report = generate_backtest_report(
    engine=result.engine,
    output_dir="./results",
    prefix="feadev_backtest",
)
print(report.graph_paths)
print(report.log_path)
```

Graphing and report options
---------------------------

The interface supports selecting which charts to export and which output formats to save. Supported chart names include: `equity_curve`, `drawdown`, `cumulative_returns`, `volatility`, `bollinger`, `rsi`, `time_series`.

Example (API):

```python
from back_da_dev import generate_backtest_report

report = generate_backtest_report(
  engine=result.engine,
  output_dir='./results',
  charts=['equity_curve','rsi','bollinger'],
  formats=('png','svg'),
)
```

### CLI

Opções de exemplo:
- `--indice`: símbolo do ticker para carregar via yfinance
- `--strategy`: `buy_and_hold`, `ma` ou `ema`
- `--initial-capital`: capital inicial
- `--commission`: taxa de corretagem por operação
- `--output-dir`: onde gráficos e logs serão salvos
- `--no-graphs`: desativa geração de gráficos
- `--no-log`: desativa geração de arquivo de log

## Documentação da API
O pacote público expõe o fluxo principal de backtesting:

- `BacktestEngine` — motor principal para executar simulações de estratégia
- `load_data(...)` — carrega dados históricos de arquivos locais ou `yfinance`
- `clean_data(...)` — limpa, normaliza e valida dados carregados
- `load_and_clean(...)` — fluxo combinado de carregamento e limpeza
- `resolve_strategy(...)` — instancia uma estratégia embutida pelo nome
- `run_standard_backtest(...)` — executa um backtest e retorna métricas
- `generate_backtest_report(...)` — salva gráficos e logs para uma execução concluída
- `save_backtest_log(...)` — serializa métricas e histórico de trade em `.log`
- `list_strategies()` — lista nomes de estratégias disponíveis

## Testes
Execute a suíte de testes do repositório com:

```bash
pytest -q
```

Este projeto inclui testes para:
- comportamento do motor de backtest
- geração de sinais das estratégias
- imports do pacote
- fluxos da interface
- sanidade de empacotamento

## Contribuindo
Membros da FEA.dev e contribuidores externos são bem-vindos.

- Faça um fork do repositório
- Crie uma branch descritiva
- Abra um pull request com sua feature ou correção
- Inclua testes e atualize a documentação quando necessário
- Reporte bugs via issues se o comportamento diferir do esperado

## Licença
Este projeto é licenciado sob a Licença MIT.

Veja [LICENSE](./LICENSE) para detalhes.

