Metadata-Version: 2.4
Name: universal-gear
Version: 0.1.0
Summary: Open-source decision framework for market intelligence under uncertainty
Project-URL: Homepage, https://github.com/bruno-portfolio/universal-gear
Project-URL: Repository, https://github.com/bruno-portfolio/universal-gear
Project-URL: Issues, https://github.com/bruno-portfolio/universal-gear/issues
Author: Bruno Escalhao
License: MIT
License-File: LICENSE
Keywords: agro,decision-framework,market-intelligence,pipeline,uncertainty
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: numpy>=1.26
Requires-Dist: pydantic-settings<3.0,>=2.0
Requires-Dist: pydantic<3.0,>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: structlog>=24.0
Requires-Dist: typer>=0.12
Provides-Extra: agro
Requires-Dist: agrobr>=0.7; extra == 'agro'
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# Universal Gear

*[Leia em Portugues](README.pt-BR.md)*

[![Tests](https://img.shields.io/badge/tests-118%20passing-brightgreen)](.)
[![Version](https://img.shields.io/badge/version-0.1.0-blue)](.)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)

**Open-source Python decision framework for market intelligence under uncertainty.**

```mermaid
flowchart LR
    A["Observation\n(Imperfect)"] -->|CollectionResult| B[Compression]
    B -->|CompressionResult| C[Hypothesis]
    C -->|HypothesisResult| D[Simulation]
    D -->|SimulationResult| E[Decision]
    E -->|DecisionResult| F[Feedback]
    F -->|FeedbackResult| A
```

## Quick Start

```bash
pip install -e .
ugear run toy
```

```
┌──────── Universal Gear - toy pipeline ────────┐
│ OK  Observation  90 events │ reliability: 0.93 │
│ OK  Compression  13 states │ weekly            │
│ OK  Hypothesis   1 hypotheses                  │
│ OK  Simulation   baseline + 10 scenarios       │
│ OK  Decision     9 decisions │ alert            │
│ OK  Feedback     9 scorecards │ hit_rate: 1.00  │
└────── SUCCESS - total: 0.0s ──────────────────┘
```

## Who Is This For

1. **Developers building decision pipelines** -- Wire up the six-stage loop with async stages, Pydantic v2 contracts, and structlog observability. Swap any stage without touching the rest.

2. **Data scientists exploring market signals** -- Run `ugear run toy` for a synthetic sandbox or `ugear run agro` against real Brazilian agricultural data via agrobr. Inspect every intermediate result through typed contracts.

3. **Domain experts adding plugins for specific markets** -- Register custom collectors, compressors, or simulators with decorators (`@register_collector`, etc.) or via `entry_points`. No framework internals required.

## Pipelines

| Pipeline | Data Source | Use Case |
|----------|-------------|----------|
| `toy` | Synthetic (offline) | Learning, testing, CI |
| `agro` | Real Brazilian agricultural data (agrobr) | Production market intelligence |

## Key Features

- **6-stage feedback loop** -- Observation, Compression, Hypothesis, Simulation, Decision, Feedback
- **Pydantic v2 contracts** -- Every stage boundary is a typed, validated result object
- **Async pipeline** -- Stages run asynchronously for I/O-heavy collectors
- **Plugin system** -- Decorators (`@register_collector`, `@register_compressor`, ...) and setuptools `entry_points`
- **structlog observability** -- Structured logging across the full pipeline
- **118 tests passing** -- Comprehensive coverage across all stages

## Documentation

- [MANIFESTO.md](MANIFESTO.md) -- Design philosophy and architectural rationale
- [docs/](docs/) -- Full documentation

## License

MIT
