Metadata-Version: 2.4
Name: factorguide
Version: 0.1.1
Summary: Client for the FactorGuide decision intelligence oracle
Project-URL: Homepage, https://factorguide.io
Project-URL: Documentation, https://factorguide.io/docs
Project-URL: Repository, https://github.com/Bwana7/factorguide
Author: Aaron Lowry
License-Expression: MIT
License-File: LICENSE
Keywords: bayesian,coupling,decision-intelligence,factorguide,factorization,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24
Description-Content-Type: text/markdown

# FactorGuide

Python client for the [FactorGuide](https://factorguide.io) decision intelligence oracle.

FactorGuide answers one question: **which couplings in your system are load-bearing and which can you safely ignore?** Send a coupling matrix from any domain — portfolios, Bayesian models, sensor networks, multi-agent systems — and get back zone classifications, optimal factorization strategy, and calibrated risk predictions.

## Install

```bash
pip install factorguide
```

## Quick start

```python
from factorguide import FactorGuideClient

fg = FactorGuideClient()

# Full navigation: zone classification + block-diagonal strategy
result = fg.navigate(
    coupling={"correlation_matrix": [[1.0, 0.5], [0.5, 1.0]]},
    sample_size=200,
)

# What zone is the pair in?
pair = result["dipole_analysis"]["pair_classification"][0]
print(f"IC = {pair['ic']}, Zone = {pair['zone']}")

# Quick single-pair diagnostic
diag = fg.diagnose(i="x", j="y", coupling_value=0.3, sample_size=100)
print(f"Constitutive risk: {diag['risk_constitutive']:.1f}x")
print(f"Inductive risk: {diag['risk_inductive']:.1f}x")

# Report outcome to improve future predictions (free)
fg.report_outcome(
    prediction_hash=result["prediction"]["prediction_hash"],
    approach_taken="factorized",
    ess_ratio=0.85,
)
```

## Payment

Trial tier: 15 free queries per wallet, no payment required.

Paid tiers: send stablecoins to the wallet address in the 402 response, then submit the transaction hash via the API. See [factorguide.io](https://factorguide.io) for pricing.

## Links

- **Website:** https://factorguide.io
- **llms.txt:** https://factorguide.io/llms.txt
- **Health:** https://factorguide.io/health
- **Theory:** [Circulatory Fidelity framework](https://circulatoryfidelity.com)

mcp-name: io.factorguide/factorguide
