universal-gear 0.2.0

Open-source decision framework for market intelligence under uncertainty

Universal Gear

Leia em Portugues

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

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:

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:

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:

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:

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

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 for the philosophy behind each layer.

Documentation

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

License

MIT -- built in Brazil, made for everywhere.