Metadata-Version: 2.4
Name: circle-intelligence
Version: 0.3.1
Summary: Python SDK for Circle Intelligence — F.I.R.E. economy real-time signal detection + RealityFutures prediction markets
Author-email: Circle Intelligence <dev@circle.news>
License: MIT
Project-URL: Homepage, https://circle.news
Project-URL: Documentation, https://circle.news/docs
Project-URL: Repository, https://github.com/Menexus-GmbH/circle_platform_backend
Keywords: circle,intelligence,fire,signals,knowledge-graph,defi
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28
Provides-Extra: wallet
Requires-Dist: eth-account>=0.10; extra == "wallet"
Provides-Extra: payment
Requires-Dist: eth-account>=0.10; extra == "payment"
Requires-Dist: web3>=6.0; extra == "payment"
Provides-Extra: rf
Requires-Dist: web3>=6.0; extra == "rf"
Requires-Dist: eth-account>=0.10; extra == "rf"
Requires-Dist: eth-abi>=5.0; extra == "rf"

# Circle Intelligence SDK

Python SDK for [Circle Intelligence](https://circle.news) — real-time F.I.R.E. economy signal detection via 7-agent AI cascade.

## What's new in 0.3.1

- **Per-method `timeout` kwarg.** Every RF data-fetch method now accepts a per-call timeout override:
  ```python
  candidates = sdk.rf.list_market_candidates(limit=10, timeout=90)
  config     = sdk.rf._get_config(timeout=60)
  market     = sdk.rf.get_market_intelligence("0x...", timeout=45)
  ```
  Falls back to the SDK-level `timeout` you passed to `CircleSDK(...)`.
- **Auto retry with exponential backoff.** `_get()` now retries up to 2 extra times (3 attempts total) on timeouts, connection errors, 429, and 5xx responses. Backoff is 1s, 2s, 4s. Transient Circle hiccups no longer surface as immediate failures. Override the retry count on any call: `sdk._get(path, retries=5)`.

## What's new in 0.3.0

- **Refreshed RF contract defaults** (`realityFuturesMarkets`, `pScoreOracle`) to match the 2026-04-21 on-chain redeploy. Earlier versions had stale addresses in the fallback path — pin `>=0.3.0` if you transact real USDC.
- **`config["source"]` marker.** `sdk.rf._get_config()` now returns `"source": "fetched"` (from `/api/rf/config`) or `"source": "defaults"` (baked-in fallback). Check this before broadcasting any tx.
- **`strict=True` mode.** `CircleSDK(url, strict=True)` raises `CircleConfigError` on config-fetch failure instead of silently falling back to stale defaults. Recommended for production agents.
- **Louder fallback warning.** If you're in non-strict mode, the log message now says "SDK USING BAKED-IN DEFAULTS" so it's not missed in grep.

The `timeout` kwarg was already configurable in 0.2.0 (`CircleSDK(url, timeout=60)`) — applies to every HTTP call including `/api/rf/config`.

## Install

```bash
pip install circle-intelligence              # core (browsing, search, chat)
pip install circle-intelligence[wallet]       # + wallet authentication
pip install circle-intelligence[payment]      # + USDC payment flow
pip install circle-intelligence[rf]           # + RealityFutures trading
```

## Quick Start

```python
from circle_intelligence import CircleSDK

# Free tier — no auth needed
sdk = CircleSDK("https://circle.news")
signals = sdk.get_recent_signals(limit=3)
entities = sdk.get_kg_entities(search="Bitcoin")
briefs = sdk.get_briefs(limit=5)

# Premium tier — with API key
sdk = CircleSDK("https://circle.news", api_key="circ_your_key")
results = sdk.search_signals("DeFi bridge exploit")
analytics = sdk.get_kg_analytics(days=7)
response = sdk.chat(signal_id=1744, messages=[{"role": "user", "content": "What happened?"}])
```

## Features

| Feature | Free | Premium |
|---------|------|---------|
| Recent signals | 6h delay, 3 max | Real-time, 100 max |
| Daily briefs | Yes | Yes |
| Knowledge graph browsing | Yes | Yes |
| KG analytics + cross-sector | No | Yes |
| Semantic search | No | Yes |
| RAG-powered chat | No | Yes |
| Simulator execution | No | Yes |
| Research creation | No | Yes |
| Depth tree details | No | Yes |

## Wallet Authentication (for agents)

```python
from eth_account import Account
from eth_account.messages import encode_defunct

private_key = "0xYOUR_PRIVATE_KEY"
wallet = Account.from_key(private_key).address

result = sdk.authenticate(
    wallet_address=wallet,
    sign_fn=lambda msg: Account.sign_message(
        encode_defunct(text=msg), private_key
    ).signature.hex(),
)
```

## Documentation

Full API reference and examples at [circle.news/docs](https://circle.news/docs)
