circle-intelligence 0.1.0__tar.gz

circle_intelligence-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: circle-intelligence
+Version: 0.1.0
+Summary: Python SDK for Circle Intelligence — F.I.R.E. economy real-time signal detection
+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"
+
+# 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.
+
+## 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
+```
+
+## 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)

circle_intelligence-0.1.0/README.md

@@ -0,0 +1,64 @@
+# 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.
+
+## 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
+```
+
+## 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)

circle_intelligence-0.1.0/circle_intelligence/__init__.py

@@ -0,0 +1,670 @@
+"""
+Circle Intelligence SDK — Programmatic access to The Circle's F.I.R.E. intelligence platform.
+
+This SDK enables AI agents and developers to do everything a human user can do on circle.news:
+authenticate via wallet, purchase Premium with USDC, browse signals, search, chat, explore
+the knowledge graph, run simulations, and manage research requests.
+
+Install:
+    pip install circle-intelligence              # core
+    pip install circle-intelligence[wallet]       # + wallet auth
+    pip install circle-intelligence[payment]      # + USDC payments
+
+Usage:
+    from circle_intelligence import CircleSDK
+
+    # Free tier (no auth)
+    sdk = CircleSDK("https://circle.news")
+    signals = sdk.get_recent_signals(limit=3)
+
+    # Premium tier (with API key)
+    sdk = CircleSDK("https://circle.news", api_key="circ_abc123...")
+    results = sdk.search_signals("bitcoin DeFi hack")
+
+    # Wallet auth flow (for agents with wallet access)
+    sdk = CircleSDK("https://circle.news")
+    sdk.authenticate(wallet_address="0x...", sign_fn=my_signer)
+"""
+
+import time
+import json
+import hashlib
+import hmac
+import base64
+from typing import Optional, Callable, Iterator
+from dataclasses import dataclass
+
+import requests
+
+
+# ---------------------------------------------------------------------------
+# Response types
+# ---------------------------------------------------------------------------
+
+@dataclass
+class Signal:
+    id: int
+    headline: str
+    sector: str
+    confidence: float
+    significance: float
+    category: str
+    timestamp: Optional[str]
+    body: Optional[str] = None
+    source_url: Optional[str] = None
+    source_name: Optional[str] = None
+    cascade_trace: Optional[dict] = None
+    council_output: Optional[dict] = None
+    suggested_market: Optional[str] = None
+    parent_signal_id: Optional[int] = None
+    research_depth: int = 0
+    narrative_durability: float = 0.0
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Signal":
+        return cls(
+            id=d.get("id", 0),
+            headline=d.get("headline", ""),
+            sector=d.get("sector", ""),
+            confidence=d.get("confidence", 0),
+            significance=d.get("significance", 0),
+            category=d.get("category", ""),
+            timestamp=d.get("timestamp"),
+            body=d.get("body"),
+            source_url=d.get("source_url"),
+            source_name=d.get("source_name"),
+            cascade_trace=d.get("cascade_trace"),
+            council_output=d.get("council_output"),
+            suggested_market=d.get("suggested_market"),
+            parent_signal_id=d.get("parent_signal_id"),
+            research_depth=d.get("research_depth", 0),
+            narrative_durability=d.get("narrative_durability", 0),
+        )
+
+
+@dataclass
+class AuthResult:
+    token: str
+    wallet: str
+    tier: str
+    credits_remaining: int
+    api_key: Optional[str]
+
+
+@dataclass
+class PaymentResult:
+    status: str
+    tier: str
+    credits: int
+    api_key: Optional[str]
+    message: str
+
+
+# ---------------------------------------------------------------------------
+# SDK
+# ---------------------------------------------------------------------------
+
+class CircleSDK:
+    """
+    Circle Intelligence SDK.
+
+    Supports three access modes:
+      1. No auth      — free endpoints only (signals with 6h delay, briefs, watchman, KG browsing)
+      2. API key       — pass api_key="circ_..." for Premium endpoints
+      3. Wallet auth   — call authenticate() to get JWT, then all endpoints work
+
+    Args:
+        base_url: API base URL (e.g. "https://circle.news" or "http://localhost:8000")
+        api_key:  Optional Premium API key (circ_... prefix)
+        timeout:  Request timeout in seconds (default 30)
+    """
+
+    def __init__(self, base_url: str, api_key: str = "", timeout: int = 30):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+        self._jwt: Optional[str] = None
+        self._wallet: Optional[str] = None
+        self._tier: Optional[str] = None
+        self._session = requests.Session()
+
+    # ---------------------------------------------------------------------------
+    # Internal helpers
+    # ---------------------------------------------------------------------------
+
+    def _headers(self) -> dict:
+        h = {"Content-Type": "application/json"}
+        if self.api_key:
+            h["X-API-Key"] = self.api_key
+        elif self._jwt:
+            h["Authorization"] = f"Bearer {self._jwt}"
+        return h
+
+    def _get(self, path: str, params: dict = None) -> dict:
+        r = self._session.get(
+            f"{self.base_url}{path}",
+            headers=self._headers(),
+            params=params,
+            timeout=self.timeout,
+        )
+        r.raise_for_status()
+        return r.json()
+
+    def _post(self, path: str, data: dict = None) -> dict:
+        r = self._session.post(
+            f"{self.base_url}{path}",
+            headers=self._headers(),
+            json=data,
+            timeout=self.timeout,
+        )
+        r.raise_for_status()
+        return r.json()
+
+    def _post_sse(self, path: str, data: dict) -> Iterator[str]:
+        """POST with SSE streaming response. Yields content tokens."""
+        r = self._session.post(
+            f"{self.base_url}{path}",
+            headers=self._headers(),
+            json=data,
+            timeout=self.timeout,
+            stream=True,
+        )
+        r.raise_for_status()
+        for line in r.iter_lines(decode_unicode=True):
+            if line and line.startswith("data: "):
+                try:
+                    payload = json.loads(line[6:])
+                    if payload.get("content"):
+                        yield payload["content"]
+                except json.JSONDecodeError:
+                    pass
+
+    # ---------------------------------------------------------------------------
+    # Authentication — wallet-based (for agents with signing capability)
+    # ---------------------------------------------------------------------------
+
+    def authenticate(
+        self,
+        wallet_address: str,
+        sign_fn: Callable[[str], str],
+    ) -> AuthResult:
+        """
+        Authenticate via wallet signature. No passwords, no emails.
+
+        Args:
+            wallet_address: Ethereum/Hedera wallet address (0x...)
+            sign_fn: Function that takes a message string and returns hex signature.
+                     For eth_account: lambda msg: Account.sign_message(
+                         encode_defunct(text=msg), private_key).signature.hex()
+
+        Returns:
+            AuthResult with JWT token, tier, and credits info.
+
+        Example:
+            from eth_account import Account
+            from eth_account.messages import encode_defunct
+
+            key = "0xYOUR_PRIVATE_KEY"
+            sdk.authenticate(
+                wallet_address="0x...",
+                sign_fn=lambda msg: Account.sign_message(
+                    encode_defunct(text=msg), key
+                ).signature.hex()
+            )
+        """
+        wallet = wallet_address.lower().strip()
+
+        # Step 1: Get nonce
+        nonce_resp = self._get("/api/auth/nonce", params={"wallet": wallet})
+        message = nonce_resp["message"]
+
+        # Step 2: Sign
+        signature = sign_fn(message)
+        if not signature.startswith("0x"):
+            signature = "0x" + signature
+
+        # Step 3: Verify
+        verify_resp = self._post("/api/auth/verify", {
+            "wallet_address": wallet,
+            "signature": signature,
+            "message": message,
+        })
+
+        self._jwt = verify_resp["token"]
+        self._wallet = wallet
+        self._tier = verify_resp.get("tier", "free")
+
+        return AuthResult(
+            token=verify_resp["token"],
+            wallet=wallet,
+            tier=verify_resp.get("tier", "free"),
+            credits_remaining=verify_resp.get("credits_remaining", 0),
+            api_key=verify_resp.get("api_key"),
+        )
+
+    def refresh_token(self) -> str:
+        """Refresh JWT token before it expires (24h default TTL)."""
+        resp = self._post("/api/auth/refresh")
+        self._jwt = resp["token"]
+        return resp["token"]
+
+    # ---------------------------------------------------------------------------
+    # Payments — USDC on Hedera
+    # ---------------------------------------------------------------------------
+
+    def get_payment_config(self) -> dict:
+        """Get payment configuration: receiving wallet, chain, tier pricing."""
+        return self._get("/api/payments/config")
+
+    def submit_payment(self, tx_hash: str, tier: str = "premium") -> PaymentResult:
+        """
+        Submit a USDC payment transaction hash for on-chain verification.
+
+        After sending USDC to the receiving wallet on Hedera, call this to verify
+        and activate the Premium tier.
+
+        Args:
+            tx_hash: Hedera transaction hash (0x...)
+            tier: "premium" (only option)
+
+        Returns:
+            PaymentResult with tier, credits, and API key (on first payment).
+        """
+        resp = self._post("/api/payments/submit", {
+            "tx_hash": tx_hash,
+            "tier": tier,
+        })
+        # Store the API key if returned
+        if resp.get("api_key"):
+            self.api_key = resp["api_key"]
+        return PaymentResult(
+            status=resp["status"],
+            tier=resp["tier"],
+            credits=resp["credits"],
+            api_key=resp.get("api_key"),
+            message=resp["message"],
+        )
+
+    def get_usage(self) -> dict:
+        """Get API usage stats: credits, burn rate, daily/hourly breakdown."""
+        return self._get("/api/payments/usage")
+
+    def get_payment_history(self) -> list:
+        """Get payment transaction history."""
+        return self._get("/api/payments/history")
+
+    # ---------------------------------------------------------------------------
+    # API Key management
+    # ---------------------------------------------------------------------------
+
+    def get_me(self) -> dict:
+        """Get current authenticated user profile."""
+        return self._get("/api/auth/me")
+
+    def generate_api_key(self) -> str:
+        """Generate a new API key (Premium tier required). Returns the key string."""
+        resp = self._post("/api/auth/generate-key")
+        key = resp["api_key"]
+        self.api_key = key
+        return key
+
+    def revoke_api_key(self) -> dict:
+        """Revoke the current API key."""
+        resp = self._post("/api/auth/revoke-key")
+        self.api_key = ""
+        return resp
+
+    # ---------------------------------------------------------------------------
+    # Signals — the core intelligence feed
+    # ---------------------------------------------------------------------------
+
+    def get_recent_signals(
+        self, limit: int = 20, offset: int = 0, sector: str = "", category: str = ""
+    ) -> dict:
+        """
+        Get recent published signals.
+
+        Free tier: 6-hour delay, max 3 per request.
+        Premium: real-time, up to 100 per request.
+
+        Args:
+            limit: Number of signals (1-100)
+            offset: Pagination offset
+            sector: Filter by F.I.R.E. sector (finance, insurance, real_infrastructure, electronic_labour)
+            category: "signal" (niche early detection) or "news" (mainstream)
+
+        Returns:
+            Dict with signals[], total, limit, offset, delayed, delay_hours
+        """
+        params = {"limit": limit, "offset": offset}
+        if sector:
+            params["sector"] = sector
+        if category:
+            params["category"] = category
+        return self._get("/api/signals/recent", params)
+
+    def get_signal(self, signal_id: int) -> Signal:
+        """Get full signal details including cascade trace and council analysis."""
+        data = self._get(f"/api/signals/{signal_id}")
+        return Signal.from_dict(data)
+
+    def get_related_signals(self, signal_id: int, limit: int = 4) -> list[dict]:
+        """Get semantically related signals via pgvector cosine similarity."""
+        resp = self._get(f"/api/signals/{signal_id}/related", {"limit": limit})
+        return resp.get("signals", [])
+
+    def search_signals(self, query: str, limit: int = 10, sector: str = "") -> dict:
+        """
+        Semantic search over signals (Premium required).
+
+        Uses hybrid pgvector + knowledge graph retrieval.
+
+        Args:
+            query: Natural language search query
+            limit: Max results (1-20)
+            sector: Optional sector filter
+
+        Returns:
+            Dict with signals[] (includes relevance_score), total, query
+        """
+        params = {"q": query, "limit": limit}
+        if sector:
+            params["sector"] = sector
+        return self._get("/api/signals/search", params)
+
+    def get_signal_feed(self, limit: int = 20, offset: int = 0, sector: str = "") -> dict:
+        """Get niche signal feed (web search, 4chan, RSS — excludes mainstream news)."""
+        params = {"limit": limit, "offset": offset}
+        if sector:
+            params["sector"] = sector
+        return self._get("/api/signals/feed", params)
+
+    # ---------------------------------------------------------------------------
+    # Chat — RAG-powered Q&A grounded in verified intelligence
+    # ---------------------------------------------------------------------------
+
+    def chat(
+        self,
+        signal_id: int,
+        messages: list[dict],
+        signal_text: str = "",
+    ) -> str:
+        """
+        Ask a question about a signal (Premium required).
+
+        The response is grounded in Circle's verified intelligence database via
+        hybrid RAG (pgvector semantic search + knowledge graph traversal).
+
+        Args:
+            signal_id: The signal to ask about
+            messages: Conversation history [{"role": "user", "content": "..."}, ...]
+            signal_text: Fallback signal text (server fetches verified signal by ID)
+
+        Returns:
+            Complete response text.
+
+        Example:
+            response = sdk.chat(
+                signal_id=1744,
+                messages=[{"role": "user", "content": "What related DeFi hacks has Circle documented?"}]
+            )
+        """
+        tokens = list(self.chat_stream(signal_id, messages, signal_text))
+        return "".join(tokens)
+
+    def chat_stream(
+        self,
+        signal_id: int,
+        messages: list[dict],
+        signal_text: str = "",
+    ) -> Iterator[str]:
+        """
+        Streaming version of chat(). Yields tokens as they arrive via SSE.
+
+        Args:
+            signal_id: The signal to ask about
+            messages: Conversation history
+            signal_text: Fallback signal text
+
+        Yields:
+            String tokens as they stream from the server.
+        """
+        yield from self._post_sse("/api/chat", {
+            "signalId": signal_id,
+            "signalText": signal_text,
+            "messages": messages,
+        })
+
+    # ---------------------------------------------------------------------------
+    # Knowledge Graph — entity relationships and intelligence analytics
+    # ---------------------------------------------------------------------------
+
+    def get_kg_entities(
+        self, sector: str = "", type: str = "", limit: int = 100, search: str = ""
+    ) -> dict:
+        """Browse knowledge graph entities with optional filters."""
+        params = {"limit": limit}
+        if sector:
+            params["sector"] = sector
+        if type:
+            params["type"] = type
+        if search:
+            params["search"] = search
+        return self._get("/api/knowledge-graph/entities", params)
+
+    def get_kg_entity(self, entity_id: int) -> dict:
+        """Get entity detail with connected edges and recent signal mentions."""
+        return self._get(f"/api/knowledge-graph/entity/{entity_id}")
+
+    def get_kg_graph(
+        self, sector: str = "", min_weight: int = 1, limit: int = 500,
+        from_date: str = "", to_date: str = ""
+    ) -> dict:
+        """Get D3-compatible graph data (nodes + links) with optional time filtering."""
+        params = {"min_weight": min_weight, "limit": limit}
+        if sector:
+            params["sector"] = sector
+        if from_date:
+            params["from_date"] = from_date
+        if to_date:
+            params["to_date"] = to_date
+        return self._get("/api/knowledge-graph/graph", params)
+
+    def get_kg_neighborhood(
+        self, entity_id: int, depth: int = 1, from_date: str = "", to_date: str = ""
+    ) -> dict:
+        """Get entity and its N-hop connections as a graph."""
+        params = {"depth": depth}
+        if from_date:
+            params["from_date"] = from_date
+        if to_date:
+            params["to_date"] = to_date
+        return self._get(f"/api/knowledge-graph/neighborhood/{entity_id}", params)
+
+    def get_kg_cross_sector(self) -> dict:
+        """Get entities appearing in 2+ F.I.R.E. sectors (Premium required)."""
+        return self._get("/api/knowledge-graph/cross-sector")
+
+    def get_kg_analytics(self, days: int = 7) -> dict:
+        """
+        Get intelligence analytics (Premium required).
+
+        Returns trending entities, emerging connections, ecotone entities
+        (cross-sector bridges), and fading connections.
+        """
+        return self._get("/api/knowledge-graph/analytics", {"days": days})
+
+    # ---------------------------------------------------------------------------
+    # Research — community-driven deep investigation
+    # ---------------------------------------------------------------------------
+
+    def list_research_requests(self) -> list:
+        """List all community research requests with progress metrics."""
+        return self._get("/api/research/requests")
+
+    def get_research_request(self, request_id: int) -> dict:
+        """Get single research request with details."""
+        return self._get(f"/api/research/{request_id}")
+
+    def create_research_request(
+        self, topic: str, description: str = "", provider: str = "",
+        api_key: str = "", model_hint: str = "", **vmosk
+    ) -> dict:
+        """
+        Create a community research request (Premium required).
+
+        The Circle's cascade will investigate this topic using donated API keys.
+
+        Args:
+            topic: What to research (e.g. "DeFi insurance protocols on Solana")
+            description: Detailed description of what to investigate
+            provider: API key provider (groq, openrouter, anthropic, etc.)
+            api_key: Optional API key to donate for this research
+            model_hint: Optional model preference
+            **vmosk: Optional VMOSK framework fields (vision, mission, objectives, strategies, kpis)
+        """
+        body = {
+            "topic": topic,
+            "description": description,
+            "provider": provider,
+            "api_key": api_key,
+            "model_hint": model_hint,
+        }
+        for field in ("vision", "mission", "objectives", "strategies", "kpis"):
+            if field in vmosk:
+                body[field] = vmosk[field]
+        return self._post("/api/research/request", body)
+
+    def get_research_signals(self, request_id: int, limit: int = 50) -> dict:
+        """Get completed signals found by a research request (Premium required)."""
+        return self._get(f"/api/research/{request_id}/signals", {"limit": limit})
+
+    # ---------------------------------------------------------------------------
+    # Depth Trees — recursive intelligence
+    # ---------------------------------------------------------------------------
+
+    def list_depth_trees(self, status: str = "active", limit: int = 20) -> dict:
+        """List depth research trees with stats."""
+        return self._get("/api/enrichment/depth-trees", {"status": status, "limit": limit})
+
+    def get_depth_tree(self, tree_id: int) -> dict:
+        """Get full depth research tree with all child signals (Premium required)."""
+        return self._get(f"/api/enrichment/depth-trees/{tree_id}")
+
+    def get_signal_enrichment(self, signal_id: int) -> dict:
+        """Get all enrichment verdicts and consensus for a signal (Premium required)."""
+        return self._get(f"/api/enrichment/signal/{signal_id}")
+
+    # ---------------------------------------------------------------------------
+    # Simulator — probability market scenarios
+    # ---------------------------------------------------------------------------
+
+    def list_scenarios(self) -> dict:
+        """List available simulation scenarios."""
+        return self._get("/api/simulator/scenarios")
+
+    def run_simulation(self, scenario: str, params: dict = None) -> dict:
+        """
+        Run a market simulation (Premium required).
+
+        Args:
+            scenario: Scenario ID from list_scenarios()
+            params: Optional overrides (initial_liquidity_yes/no, trading_rounds, fee_bps)
+        """
+        return self._post("/api/simulator/run", {
+            "scenario": scenario,
+            "params": params or {},
+        })
+
+    # ---------------------------------------------------------------------------
+    # Cascade
+    # ---------------------------------------------------------------------------
+
+    def get_metrics(self) -> dict:
+        """Get cascade performance metrics (throughput, rejection rates, sectors)."""
+        return self._get("/api/metrics")
+
+    def run_cascade_demo(self) -> dict:
+        """Run cascade demo on a recent signal with timing breakdown (Premium required)."""
+        return self._post("/api/cascade/demo")
+
+    def get_cascade_visualization(self) -> dict:
+        """Get ASCII diagram of the 7-agent cascade architecture."""
+        return self._get("/api/cascade/visualize")
+
+    # ---------------------------------------------------------------------------
+    # Briefs — daily intelligence summaries
+    # ---------------------------------------------------------------------------
+
+    def get_briefs(self, limit: int = 30) -> list:
+        """Get recent daily briefs."""
+        return self._get("/api/briefs", {"limit": limit})
+
+    def get_brief(self, date: str) -> dict:
+        """Get brief for a specific date (ISO format: YYYY-MM-DD)."""
+        return self._get(f"/api/briefs/{date}")
+
+    # ---------------------------------------------------------------------------
+    # Watchman — detection accuracy tracking
+    # ---------------------------------------------------------------------------
+
+    def get_watchman(self) -> dict:
+        """Get current watchman accuracy status."""
+        return self._get("/api/watchman")
+
+    def get_watchman_metrics(self) -> dict:
+        """Get detailed watchman metrics."""
+        return self._get("/api/watchman/metrics")
+
+    def get_watchman_history(self, days: int = 90) -> list:
+        """Get historical accuracy trend."""
+        resp = self._get("/api/watchman/history", {"days": days})
+        return resp.get("history", [])
+
+    def get_gate_b(self) -> dict:
+        """Check Gate B status (21-day accuracy threshold)."""
+        return self._get("/api/watchman/gate-b")
+
+    # ---------------------------------------------------------------------------
+    # Key Donation — contribute API keys to the community pool
+    # ---------------------------------------------------------------------------
+
+    def donate_key(self, provider: str, key: str, model_hint: str = "") -> dict:
+        """
+        Donate an API key to Circle's processing pool.
+
+        Donated keys power the cascade, research, and enrichment engines.
+
+        Args:
+            provider: Key provider (groq, openrouter, anthropic, cerebras, sambanova, etc.)
+            key: The API key
+            model_hint: Optional model preference
+
+        Returns:
+            Dict with status, donor_hash (save this to track your key)
+        """
+        return self._post("/api/keys/donate", {
+            "provider": provider,
+            "key": key,
+            "model_hint": model_hint,
+        })
+
+    def get_key_status(self, donor_hash: str) -> dict:
+        """Check status of a donated key by its donor hash."""
+        return self._get(f"/api/keys/status/{donor_hash}")
+
+    def get_key_pool_stats(self) -> dict:
+        """Get public key pool statistics."""
+        return self._get("/api/keys/pool/stats")
+
+    # ---------------------------------------------------------------------------
+    # Utility
+    # ---------------------------------------------------------------------------
+
+    @property
+    def is_authenticated(self) -> bool:
+        return bool(self._jwt or self.api_key)
+
+    @property
+    def tier(self) -> str:
+        return self._tier or ("premium" if self.api_key else "free")

circle_intelligence-0.1.0/circle_intelligence.egg-info/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: circle-intelligence
+Version: 0.1.0
+Summary: Python SDK for Circle Intelligence — F.I.R.E. economy real-time signal detection
+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"
+
+# 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.
+
+## 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
+```
+
+## 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)

circle_intelligence-0.1.0/circle_intelligence.egg-info/SOURCES.txt

@@ -0,0 +1,8 @@
+README.md
+pyproject.toml
+circle_intelligence/__init__.py
+circle_intelligence.egg-info/PKG-INFO
+circle_intelligence.egg-info/SOURCES.txt
+circle_intelligence.egg-info/dependency_links.txt
+circle_intelligence.egg-info/requires.txt
+circle_intelligence.egg-info/top_level.txt

circle_intelligence-0.1.0/circle_intelligence.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

circle_intelligence-0.1.0/circle_intelligence.egg-info/requires.txt

@@ -0,0 +1,8 @@
+requests>=2.28
+
+[payment]
+eth-account>=0.10
+web3>=6.0
+
+[wallet]
+eth-account>=0.10

circle_intelligence-0.1.0/circle_intelligence.egg-info/top_level.txt

@@ -0,0 +1 @@
+circle_intelligence

circle_intelligence-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "circle-intelligence"
+version = "0.1.0"
+description = "Python SDK for Circle Intelligence — F.I.R.E. economy real-time signal detection"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [
+    {name = "Circle Intelligence", email = "dev@circle.news"},
+]
+keywords = ["circle", "intelligence", "fire", "signals", "knowledge-graph", "defi"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "requests>=2.28",
+]
+
+[project.optional-dependencies]
+wallet = [
+    "eth-account>=0.10",
+]
+payment = [
+    "eth-account>=0.10",
+    "web3>=6.0",
+]
+
+[project.urls]
+Homepage = "https://circle.news"
+Documentation = "https://circle.news/docs"
+Repository = "https://github.com/Menexus-GmbH/circle_platform_backend"
+
+[tool.setuptools]
+packages = ["circle_intelligence"]

circle_intelligence-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+