workspace/projects/trading-platform/QUICKSTART_PYTHON.md

# Quick Start - Python Services

Guía rápida para empezar a desarrollar en los servicios Python de OrbiQuant IA.

## Setup Inicial (Una sola vez)

```bash
# 1. Navegar al proyecto
cd /home/isem/workspace/projects/trading-platform

# 2. Crear todos los entornos
./scripts/setup-python-envs.sh all

# 3. Verificar instalación
~/miniconda3/bin/conda env list | grep orbiquant
```

## Data Service

```bash
# Activar entorno
conda activate orbiquant-data-service

# Configurar
cd apps/data-service
cp .env.example .env
# Editar .env con tus configuraciones

# Ejecutar
python -m src.main

# Tests
pytest
```

## ML Engine

```bash
# Activar entorno
conda activate orbiquant-ml-engine

# Configurar
cd apps/ml-engine
cp .env.example .env

# Ejecutar API
uvicorn src.main:app --reload --port 8002

# Jupyter (desarrollo)
jupyter notebook

# Tests
pytest --cov=src
```

## LLM Agent

```bash
# Activar entorno
conda activate orbiquant-llm-agent

# Configurar
cd apps/llm-agent
cp .env.example .env
# IMPORTANTE: Agregar ANTHROPIC_API_KEY

# Ejecutar API
uvicorn src.main:app --reload --port 8003

# Acceder a docs
# http://localhost:8003/docs

# Tests
pytest --cov=src --cov-report=html
```

## Comandos de Desarrollo

### Code Quality

```bash
# Format
black src/
isort src/

# Lint
flake8 src/

# Type check
mypy src/

# Todo junto
black src/ && isort src/ && flake8 src/ && mypy src/
```

### Testing

```bash
# Todos los tests
pytest

# Con coverage
pytest --cov=src --cov-report=html

# Tests específicos
pytest tests/unit/
pytest tests/integration/
pytest tests/unit/test_service.py -v

# Con logs
pytest -v -s
```

### Gestión de Entornos

```bash
# Listar entornos
conda env list

# Activar
conda activate orbiquant-ml-engine

# Desactivar
conda deactivate

# Eliminar
conda env remove -n orbiquant-ml-engine

# Recrear
conda env create -f environment.yml

# Actualizar
conda env update -f environment.yml --prune

# Exportar
conda env export > environment.yml
```

### Dependencias

```bash
# Instalar nueva dependencia
conda install <package>
# o
pip install <package>

# Actualizar requirements.txt
pip freeze > requirements.txt

# Listar instaladas
conda list
pip list

# Buscar paquete
conda search <package>
```

## Acceso Rápido a APIs

Una vez ejecutando los servicios:

- **Data Service**: http://localhost:8001
- **ML Engine**: http://localhost:8002/docs
- **LLM Agent**: http://localhost:8003/docs

## Troubleshooting Rápido

### Error: Conda no encontrado
```bash
# Verificar instalación
ls -la ~/miniconda3/bin/conda

# Si no existe, reinstalar
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh -b -p ~/miniconda3
```

### Error: Puerto en uso
```bash
# Ver qué usa el puerto
lsof -i :8003

# Matar proceso
kill -9 <PID>

# Usar otro puerto
uvicorn src.main:app --port 8004
```

### Error: Import not found
```bash
# Verificar entorno activo
conda info --envs

# Reinstalar paquete
pip install --force-reinstall <package>

# Verificar instalación
python -c "import <package>; print(<package>.__version__)"
```

### Error: PyTorch CUDA
```bash
# Verificar CUDA
nvidia-smi

# Reinstalar PyTorch con CUDA
conda install pytorch torchvision torchaudio pytorch-cuda=11.8 -c pytorch -c nvidia

# Verificar
python -c "import torch; print(torch.cuda.is_available())"
```

## Estructura de Proyecto

```
apps/{service}/
├── src/
│   ├── main.py          # Entry point
│   ├── config.py        # Settings
│   ├── models/          # Pydantic models
│   ├── services/        # Business logic
│   ├── repositories/    # Data access
│   └── api/             # Routes
├── tests/
├── environment.yml
├── requirements.txt
└── .env.example
```

## Workflow de Desarrollo

1. **Activar entorno**
   ```bash
   conda activate orbiquant-<service>
   ```

2. **Crear feature branch**
   ```bash
   git checkout -b feature/nueva-funcionalidad
   ```

3. **Desarrollar**
   - Escribir código en `src/`
   - Seguir principios SOLID
   - Agregar type hints

4. **Tests**
   ```bash
   pytest tests/unit/
   ```

5. **Code quality**
   ```bash
   black src/ && isort src/ && flake8 src/
   ```

6. **Commit**
   ```bash
   git add .
   git commit -m "feat: nueva funcionalidad"
   ```

## Recursos

- **Documentación completa**: `/docs/95-guias-desarrollo/ml-engine/SETUP-PYTHON.md`
- **Resumen setup**: `/PYTHON_SETUP_SUMMARY.md`
- **Scripts**: `/scripts/`

## Comandos de Un Solo Paso

```bash
# Setup completo desde cero
cd /home/isem/workspace/projects/trading-platform && \
./scripts/setup-python-envs.sh all

# Iniciar LLM Agent
conda activate orbiquant-llm-agent && \
cd apps/llm-agent && \
uvicorn src.main:app --reload --port 8003

# Tests completos
conda activate orbiquant-ml-engine && \
cd apps/ml-engine && \
pytest --cov=src --cov-report=html && \
firefox htmlcov/index.html

# Code quality check
black src/ && isort src/ && flake8 src/ && mypy src/ && pytest
```

---

Para más información, consulta la documentación completa en `/docs`.