universal-gear 0.2.0
Open-source decision framework for market intelligence under uncertainty
License: MIT
Requires Python: >=3.11
Keywords: agro, decision-framework, market-intelligence, pipeline, uncertainty

# Universal Gear

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

[![CI](https://github.com/bruno-portfolio/Universal-Gear/actions/workflows/ci.yml/badge.svg)](https://github.com/bruno-portfolio/Universal-Gear/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/universal-gear)](https://pypi.org/project/universal-gear/)
[![Python](https://img.shields.io/pypi/pyversions/universal-gear)](https://pypi.org/project/universal-gear/)
[![License](https://img.shields.io/github/license/bruno-portfolio/Universal-Gear)](LICENSE)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

Every week you make decisions based on incomplete data.
Universal Gear structures that process -- so you can decide better, explain why, and learn from mistakes.

## What Does It Do?

Universal Gear runs a six-stage decision loop on real market data and returns structured, auditable results.

**Commodity trader** -- "Soy prices dropped three weeks in a row. Is it seasonal or a trend? Should I hedge?"
Run `ugear run agro` against live Brazilian agricultural data. The pipeline detects anomalies, simulates scenarios, and tells you whether the signal is worth acting on.

**Financial analyst** -- "USD/BRL spiked overnight. Noise or regime change?"
Run `ugear run finance` on Central Bank data. Same six stages, different domain -- observation, compression, hypothesis, simulation, decision, feedback.

**Anyone with recurring decisions** -- You do not need to be a trader. Any decision you make repeatedly under uncertainty (procurement, pricing, inventory) fits this loop. The framework forces you to show your work: what you observed, what you assumed, what you decided, and whether it worked.

## The Six Stages

Every pipeline follows the same loop:

```
  Observe --> Compress --> Hypothesize --> Simulate --> Decide --> Feedback
     ^                                                              |
     +--------------------------------------------------------------+
```

| Stage | What it answers |
|-------|-----------------|
| **Observe** | What is happening in the market right now? |
| **Compress** | What is the pattern over the last weeks? |
| **Hypothesize** | Is this normal or something unusual? |
| **Simulate** | If this continues, what could happen? |
| **Decide** | What should I do about it? |
| **Feedback** | Did my last decision work? |

No stage pretends to be perfect. Each one carries its limitations forward so you always know what you are working with.

## Install and Run

```bash
pip install universal-gear
ugear run toy          # try it now -- offline, no setup needed
ugear run agro         # real soy price data from Brazil
ugear run finance      # USD/BRL exchange rates from BCB
```

Output looks like this:

```
┌──────── Universal Gear - agro 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 ──────────────────┘
```

Every stage reports what it did and how long it took. If something fails, it fails loud -- no silent errors.

## Who Is This For

- **Commodity analysts and traders** -- Structured market intelligence for agricultural products, with real data from Brazilian sources.
- **Financial and macro analysts** -- Decision pipelines for exchange rates, interest rates, and macroeconomic indicators.
- **Business intelligence teams** -- Export results as JSON and import into Power BI, Tableau, or any BI tool.
- **Anyone who makes recurring decisions under uncertainty** -- Procurement, pricing, inventory, logistics -- any domain where you decide regularly with imperfect information.
- **Developers building custom decision pipelines** -- Swap any stage, add new data sources, or build an entirely new domain plugin.

## Export for BI Tools

Use `--output json` to get structured output you can feed into dashboards and reports:

```bash
ugear run agro --output json
```

The output is structured JSON that can be imported directly into Power BI, Tableau, Metabase, or any tool that consumes JSON data. CSV is also available via `--output csv`.

## Don't Code? Start Here

You don't need to know how to program. Universal Gear includes a spreadsheet that walks you through the same decision process, step by step.

**What you get:** An Excel file with seven tabs. Each tab is one step of the process. Each tab has instructions at the top telling you exactly what to do. Green cells are yours to fill. There is a complete example already filled in (buying coffee for an office) so you can see what a finished cycle looks like before you start your own.

The seven steps:

| Tab | What you do |
|-----|-------------|
| **OBSERVAR** | Write down what you see: prices, quantities, news. One row per observation. |
| **COMPRIMIR** | Summarize: what is the average? Is it going up or down? How much did it change? |
| **HIPOTESE** | Write what you think is happening -- and what would prove you wrong. |
| **SIMULAR** | Imagine at least two futures: one where things go well, one where they don't. |
| **DECIDIR** | Make your decision. How confident are you? What happens if you're wrong? |
| **FEEDBACK** | After time passes: what actually happened? Were you right? What did you learn? |
| **DASHBOARD** | Your score over time. How many decisions did you get right? |

To generate the spreadsheet:

```bash
pip install universal-gear[sheets]
ugear template
```

This creates `ugear-decisao.xlsx`. Open it in Excel or Google Sheets and start filling in.

When you're ready to try the code version, you can export your spreadsheet to a format the CLI understands:

```bash
ugear import-sheet my-decisions.xlsx
```

## Build Your Own Plugin

Universal Gear is domain-agnostic at its core. The `toy` and `agro` pipelines are plugins -- and you can build your own for any domain.

Register a custom collector, processor, analyzer, or any other stage with a single decorator:

```python
from universal_gear.core.registry import register_collector

@register_collector("my_source")
class MyCollector(BaseCollector[MyConfig]):
    async def collect(self) -> CollectionResult:
        ...
```

Full guide: [docs/plugins.md](docs/plugins.md)

## Roadmap

Universal Gear grows in layers -- each one makes the framework accessible to more people:

- ~~**CLI output**~~ -- Decision summary panels, track record display, JSON/CSV export
- ~~**Plugin scaffold**~~ -- `ugear new-plugin` and `ugear check-plugin` for building custom domains
- ~~**Spreadsheet template**~~ -- `ugear template` generates a guided xlsx for non-programmers
- **Content and tutorials** -- Articles explaining the methodology in plain language
- **Web interface** -- A minimal webapp for browser-based decision pipelines

See the [MANIFESTO.md](MANIFESTO.md) for the philosophy behind each layer.

## Documentation

- [MANIFESTO.md](MANIFESTO.md) -- Design philosophy: why every stage acknowledges its limits
- [docs/quickstart.md](docs/quickstart.md) -- Getting started in five minutes
- [docs/architecture.md](docs/architecture.md) -- System architecture and contracts
- [docs/plugins.md](docs/plugins.md) -- Building custom plugins
- [docs/tutorial-first-plugin.md](docs/tutorial-first-plugin.md) -- Step-by-step: your first plugin
- [docs/cli.md](docs/cli.md) -- Full CLI reference

## License

MIT -- built in Brazil, made for everywhere.