gildea 0.1.0__py3-none-any.whl

gildea-0.1.0.dist-info/METADATA

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: gildea
+Version: 0.1.0
+Summary: Python client and MCP server for the Gildea AI market intelligence API
+Project-URL: Homepage, https://gildea.ai
+Project-URL: Documentation, https://docs.gildea.ai
+Project-URL: Repository, https://github.com/hjones20/gildea-api
+Project-URL: Issues, https://github.com/hjones20/gildea-api/issues
+Author: Holly Jones
+License-Expression: MIT
+Keywords: ai,api-client,competitive-intelligence,market-intelligence,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: mcp[server]>=1.3; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.35; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.15; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp[server]>=1.3; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# Gildea
+
+Python client and MCP server for the [Gildea](https://gildea.ai) AI market intelligence API.
+
+Gildea tracks 500+ expert sources on AI, decomposes every signal into verified reasoning chains (thesis, arguments, claims, evidence), and serves it through a REST API. This package gives you a Python client and an MCP server so AI assistants can use the data directly.
+
+## Install
+
+```bash
+# Python client only
+pip install gildea
+
+# With MCP server
+pip install gildea[mcp]
+```
+
+## Quick Start
+
+```python
+from gildea_sdk import Gildea
+
+client = Gildea(api_key="gld_your_key_here")
+
+# Search verified text units
+results = client.search.query(q="data center infrastructure spending")
+for hit in results.data:
+    print(f"{hit.unit.text}")
+    print(f"  Source: {hit.citation.signal_title} ({hit.citation.registrable_domain})")
+
+# Get full signal decomposition with evidence
+signal = client.signals.get("signal_id", include="evidence")
+
+# Entity intelligence with trend analytics
+entity = client.entities.get("NVIDIA")
+print(f"{entity.display_name}: {entity.direction}, {entity.scale} scale, {entity.priority} priority")
+
+# Cross-source consensus mapping
+similar = client.search.query(similar_to="unit_id")
+```
+
+## MCP Server
+
+Use Gildea as a tool in Claude, ChatGPT, Cursor, VS Code, or any MCP-compatible client.
+
+```bash
+# Run directly
+gildea-mcp
+
+# Or via uvx (no install needed)
+uvx --from gildea[mcp] gildea-mcp
+```
+
+Set your API key:
+```bash
+export GILDEA_API_KEY=gld_your_key_here
+```
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "gildea": {
+      "command": "uvx",
+      "args": ["--from", "gildea[mcp]", "gildea-mcp"],
+      "env": {
+        "GILDEA_API_KEY": "gld_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Available MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `search_text_units` | Semantic search across verified text units, or vector similarity via `similar_to` |
+| `list_signals` | Browse signals by entity, theme, date, content type |
+| `get_signal_detail` | Full decomposition: thesis, arguments, claims, evidence |
+| `get_entity_profile` | Entity trend analytics, co-occurrence, theme distribution |
+| `list_entities` | Discover entities by trend direction, priority, scale |
+| `get_themes` | Theme overview across value chain and market force axes |
+| `get_theme_detail` | Single theme trend analytics and cross-theme relationships |
+
+## API Key
+
+Get your API key at [gildea.ai](https://gildea.ai). Free tier includes 5 requests/minute and 200 requests/month.
+
+## Documentation
+
+Full API docs at [docs.gildea.ai](https://docs.gildea.ai).
+
+## License
+
+MIT

gildea-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+gildea_sdk/__init__.py,sha256=53NUhdCq50QD1meHc_ge5HuLycGkGLM_nQLJ2EUzpAw,407
+gildea_sdk/client.py,sha256=ZD8DkgFNP1qfOdRSU1qUoY-tKVWnhXCH2n_D5ccxNfI,1571
+gildea_sdk/exceptions.py,sha256=NOMrpRwSEn1iBbavmmz0vKBSJl_B8Mv9lEXxaCx6-Qw,857
+gildea_sdk/pagination.py,sha256=h3-swBnUhKm8MRr6cm7SEMJ6shkga14PYZbuETukqn0,2368
+gildea_sdk/mcp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gildea_sdk/mcp/__main__.py,sha256=WMQP7_MpK6gabqrvB1g5Is78a2rAmazjOC9DXG6BBgg,108
+gildea_sdk/mcp/server.py,sha256=AWunr6kPXUWrJendrJ7EGuEYPx_wZ-utdstFxX5Q5Tc,16232
+gildea_sdk/mcp/tools.py,sha256=7DyQWnoytNqCYJw0TBpP_J1UGDZHLUUGWk--CioWNfE,4447
+gildea_sdk/resources/__init__.py,sha256=P27eKn1HiLXW_DC3LWPH915RE3fmncBMzHv7SC6vubw,233
+gildea_sdk/resources/entities.py,sha256=2iigKaVY920ij9Ss8vWXBTds6ehN1IfvjXhMK7E3Igo,1353
+gildea_sdk/resources/search.py,sha256=rpqlUMvE-9popFSoLjyUKpsjOPk6jHKHiAB1lkLhB_A,1254
+gildea_sdk/resources/signals.py,sha256=bEbz3_xPnziolcFOmR83qzAxjD5R0Yee02x2X9GQ7So,1371
+gildea_sdk/resources/themes.py,sha256=HWSmgfzBqdpltSbD4vqZTgAto0peUmg0D2l4MV3Nd8Y,489
+gildea-0.1.0.dist-info/METADATA,sha256=Linn2AV_LnO8rLMMcgV_Yli26gPrZFC2jl9nBN-PSOg,3984
+gildea-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+gildea-0.1.0.dist-info/entry_points.txt,sha256=QiEXWZnOXrTFA63upviecr_w_cOMfwzYUOjSWxgNaZw,58
+gildea-0.1.0.dist-info/RECORD,,

gildea-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

gildea-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gildea-mcp = gildea_sdk.mcp.server:main

gildea_sdk/__init__.py

@@ -0,0 +1,21 @@
+"""Gildea Python SDK — client for the Gildea AI market intelligence API."""
+
+from .client import Gildea
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    GildeaError,
+    NotFoundError,
+    RateLimitError,
+)
+
+__all__ = [
+    "Gildea",
+    "GildeaError",
+    "AuthenticationError",
+    "NotFoundError",
+    "RateLimitError",
+    "BadRequestError",
+    "APIError",
+]

gildea_sdk/client.py

@@ -0,0 +1,49 @@
+"""Main Gildea client."""
+
+from __future__ import annotations
+
+import os
+
+import httpx
+
+from .exceptions import AuthenticationError
+from .resources import EntitiesResource, SearchResource, SignalsResource, ThemesResource
+
+
+class Gildea:
+    """Synchronous client for the Gildea AI market intelligence API."""
+
+    def __init__(self, api_key=None, base_url="https://api.gildea.ai", timeout=30.0):
+        self.api_key = api_key or os.environ.get("GILDEA_API_KEY")
+        if not self.api_key:
+            raise AuthenticationError(
+                "No API key provided. Set GILDEA_API_KEY or pass api_key=."
+            )
+        self._client = httpx.Client(
+            base_url=base_url,
+            headers={"X-API-Key": self.api_key},
+            timeout=timeout,
+        )
+        self.signals = SignalsResource(self._client)
+        self.entities = EntitiesResource(self._client)
+        self.themes = ThemesResource(self._client)
+        self._search = SearchResource(self._client)
+
+    def search(self, query=None, *, similar_to=None, **kwargs):
+        """Search across all verified text units.
+
+        Two modes: pass ``query`` for hybrid semantic + keyword search,
+        or ``similar_to`` with a text unit ID for pure vector similarity.
+        Exactly one is required.
+        """
+        return self._search.query(query, similar_to=similar_to, **kwargs)
+
+    def close(self):
+        """Close the underlying HTTP connection."""
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()

gildea_sdk/exceptions.py

@@ -0,0 +1,34 @@
+"""Exception classes for the Gildea SDK."""
+
+
+class GildeaError(Exception):
+    """Base exception for all Gildea SDK errors."""
+
+    def __init__(self, message, *, code=None, status=None):
+        super().__init__(message)
+        self.code = code
+        self.status = status
+
+
+class AuthenticationError(GildeaError):
+    """Raised on 401/403 responses or missing API key."""
+
+
+class NotFoundError(GildeaError):
+    """Raised on 404 responses."""
+
+
+class RateLimitError(GildeaError):
+    """Raised on 429 responses."""
+
+    def __init__(self, message, *, code=None, status=None, retry_after=None):
+        super().__init__(message, code=code, status=status)
+        self.retry_after = retry_after
+
+
+class BadRequestError(GildeaError):
+    """Raised on 400 responses."""
+
+
+class APIError(GildeaError):
+    """Raised on 5xx or other unexpected responses."""

gildea_sdk/mcp/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running MCP server as: python -m gildea_sdk.mcp"""
+
+from gildea_sdk.mcp.server import main
+
+main()

gildea_sdk/mcp/server.py

@@ -0,0 +1,328 @@
+"""MCP server for Gildea market intelligence data.
+
+Modes:
+    stdio (default): python -m gildea_sdk.mcp
+    sse:             python -m gildea_sdk.mcp --sse
+    sse (custom):    python -m gildea_sdk.mcp --sse --port 8001
+
+Configuration via environment variables:
+    GILDEA_API_KEY       - Required. API key for authentication.
+    GILDEA_API_BASE_URL  - Base URL for the REST API (default: https://api.gildea.ai)
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import os
+
+import httpx
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import TextContent, Tool
+
+from gildea_sdk.mcp import tools
+
+server = Server("gildea")
+_http_client: httpx.AsyncClient | None = None
+
+
+def _json_result(data: dict) -> list[TextContent]:
+    return [TextContent(type="text", text=json.dumps(data, default=str, indent=2))]
+
+
+def _error_result(error: str) -> list[TextContent]:
+    return _json_result({"error": error})
+
+
+def _ensure_client() -> httpx.AsyncClient:
+    global _http_client
+    if _http_client is None:
+        api_key = os.getenv("GILDEA_API_KEY", "")
+        base_url = os.getenv("GILDEA_API_BASE_URL", "https://api.gildea.ai")
+        if not api_key:
+            raise ValueError("GILDEA_API_KEY environment variable is required")
+        _http_client = httpx.AsyncClient(
+            base_url=base_url,
+            headers={"X-API-Key": api_key},
+            timeout=30.0,
+        )
+    return _http_client
+
+
+@server.list_tools()
+async def list_tools() -> list[Tool]:
+    return [
+        Tool(
+            name="search_text_units",
+            description="Semantic search across all of Gildea's verified extractions — thesis sentences, arguments, summaries, and claims. Text units are Gildea's own analytical extractions from source material, independently verified for factual accuracy. They are not direct quotes. Two modes: q='search query' finds text units matching a natural language question; similar_to='unit_id' finds text units semantically similar to a known unit (best for consensus mapping and cross-source synthesis). Use cases: 'What do multiple sources say about X?' → q with broad query. 'Who else is saying something like this claim?' → similar_to with unit ID. Returns sentence-level results with source attribution. Set recency_boost (0-1) to favor newer signals. Set verification_detail=full for complete verification metadata.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "q": {"type": "string", "description": "Search query text. Required unless similar_to is provided."},
+                    "similar_to": {"type": "string", "description": "Text unit ID to find similar units for. Uses the unit's stored embedding for pure vector similarity search. Required unless q is provided."},
+                    "unit_type": {
+                        "type": "string",
+                        "enum": [
+                            "thesis_sentence",
+                            "argument_sentence",
+                            "summary_sentence",
+                            "analysis_claim",
+                            "event_claim",
+                        ],
+                        "description": "Filter by text unit type",
+                    },
+                    "entity": {"type": "string", "description": "Filter by entity ID"},
+                    "theme": {"type": "string", "description": "Filter by theme label"},
+                    "published_after": {"type": "string", "description": "ISO 8601 date — only results published after this date"},
+                    "published_before": {"type": "string", "description": "ISO 8601 date — only results published before this date"},
+                    "recency_boost": {
+                        "type": "number",
+                        "description": "Recency weight (0=none, 1=max). Boosts newer signals in ranking.",
+                        "default": 0.0,
+                        "minimum": 0,
+                        "maximum": 1,
+                    },
+                    "verification_detail": {
+                        "type": "string",
+                        "enum": ["full"],
+                        "description": "Include full verification metadata",
+                    },
+                    "limit": {"type": "integer", "default": 10, "maximum": 25},
+                },
+                "oneOf": [
+                    {"required": ["q"]},
+                    {"required": ["similar_to"]},
+                ],
+            },
+        ),
+        Tool(
+            name="list_signals",
+            description="Find intelligence signals about the AI economy from 500+ expert sources. Each signal is a structured analysis or event report that has been decomposed into verified components (thesis → arguments → claims for analysis; summary → claims for events). This endpoint returns signal metadata — use get_signal_detail to access the full verified decomposition tree. All filters are optional. Without filters, returns the most recent signals sorted by date. Use cases: 'What's happening with [company]?' → filter by entity. 'What's new in AI regulation?' → filter by theme. 'Anything about open source models?' → text query. 'What's new today?' → no filter, most recent. Each result includes title, source, date, tags (value chain + market force), mentioned entities, and count of verified text units.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "entity": {"type": "string", "description": "Entity ID filter"},
+                    "theme": {"type": "string", "description": "Theme label filter"},
+                    "q": {"type": "string", "description": "Text search query"},
+                    "content_type": {"type": "string", "enum": ["analysis", "event"]},
+                    "published_after": {"type": "string", "description": "ISO date"},
+                    "published_before": {"type": "string", "description": "ISO date"},
+                    "limit": {"type": "integer", "default": 25, "maximum": 50},
+                },
+            },
+        ),
+        Tool(
+            name="get_signal_detail",
+            description="Get the full verified reasoning chain for a signal. This is where Gildea's value lives. Analysis signals decompose into: thesis → supporting arguments → verified claims. Event signals decompose into: summary → verified claims. Each piece has been independently verified against source evidence. Use this tool liberally — it's the difference between showing a user metadata and showing them the actual verified intelligence. Set include=evidence to see the source snippets each claim was verified against. Set verification_detail=full for complete verification metadata.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "signal_id": {"type": "string", "description": "Signal ID"},
+                    "include": {
+                        "type": "string",
+                        "enum": ["evidence"],
+                        "description": "Include evidence snippets",
+                    },
+                    "verification_detail": {
+                        "type": "string",
+                        "enum": ["full"],
+                        "description": "Include full verification metadata",
+                    },
+                },
+                "required": ["signal_id"],
+            },
+        ),
+        Tool(
+            name="get_entity_profile",
+            description="Get an intelligence profile for a company, person, or product. Returns: whether the entity is rising, stable, or declining in expert coverage; how much attention it's getting relative to others (scale); whether the trend is statistically significant; and a priority assessment. Use this to understand an entity's trajectory before diving into specific signals. Accepts display name (e.g. 'NVIDIA') or entity ID. Note: entities with fewer than 8 mentions in the 12-week window return limited trend data.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "name_or_id": {
+                        "type": "string",
+                        "description": "Entity name (fuzzy matched) or entity UUID",
+                    },
+                },
+                "required": ["name_or_id"],
+            },
+        ),
+        Tool(
+            name="list_entities",
+            description="Discover which companies, people, and products are getting expert attention in the AI economy. Filter by trend direction (Rising/Stable/Declining), priority level, coverage scale, and more. Use this for discovery — finding what's worth paying attention to. Common patterns: 'What's trending?' → direction=Rising, confidence=Significant. 'What should I watch?' → priority=High. 'Any new entrants?' → direction=New.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "q": {"type": "string", "description": "Fuzzy name search"},
+                    "theme": {"type": "string", "description": "Filter by theme label"},
+                    "type_primary": {
+                        "type": "string",
+                        "description": "Filter by entity type: 'Organization', 'Person', 'Product', etc.",
+                    },
+                    "sort": {
+                        "type": "string",
+                        "enum": ["signal_count", "first_seen", "trend"],
+                        "default": "signal_count",
+                    },
+                    "direction": {
+                        "type": "string",
+                        "enum": ["Rising", "Stable", "Declining", "New"],
+                        "description": "Filter by trend direction",
+                    },
+                    "confidence": {
+                        "type": "string",
+                        "enum": ["Significant", "Insignificant"],
+                        "description": "Filter by trend statistical significance",
+                    },
+                    "stability": {
+                        "type": "string",
+                        "enum": ["Volatile", "Steady"],
+                        "description": "Filter by coverage consistency",
+                    },
+                    "scale": {
+                        "type": "string",
+                        "enum": ["High", "Medium", "Low"],
+                        "description": "Filter by share-of-voice scale",
+                    },
+                    "priority": {
+                        "type": "string",
+                        "enum": ["High", "Medium", "Low", "Negligible"],
+                        "description": "Filter by combined priority assessment",
+                    },
+                    "limit": {"type": "integer", "default": 25, "maximum": 50},
+                },
+            },
+        ),
+        Tool(
+            name="get_themes",
+            description="List all taxonomy themes across two axes that categorize the AI economy. Value chain axis (where in the stack): Infrastructure, Foundation Models, Orchestration, Data & Labeling, Applications, Distribution. Market force axis (what's driving change): Capital & Investment, Regulatory & Legal, Competitive Dynamics, Talent & Labor, Geopolitical Strategy, Trust & Societal Impact. Each theme includes signal counts, trend direction, and priority. Use get_theme_detail for full trend analytics and co-occurring themes.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "axis": {
+                        "type": "string",
+                        "enum": ["value_chain", "market_force"],
+                        "description": "Filter by taxonomy axis",
+                    },
+                },
+            },
+        ),
+        Tool(
+            name="get_theme_detail",
+            description="Get a specific theme's full trend analytics and co-occurring themes from both axes. Returns trend direction, statistical confidence, stability, priority with reasoning, and which themes from the other axis most frequently co-occur. Use this to understand how themes interconnect. Example: 'Foundation Models' co-occurring heavily with 'Competitive Dynamics' signals a competitive landscape shift in the model layer.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "axis": {"type": "string", "enum": ["value_chain", "market_force"]},
+                    "label": {"type": "string", "description": "Theme label"},
+                },
+                "required": ["axis", "label"],
+            },
+        ),
+    ]
+
+
+@server.call_tool()
+async def call_tool(name: str, arguments: dict) -> list[TextContent]:
+    try:
+        client = _ensure_client()
+    except ValueError as e:
+        return _error_result(f"Authentication failed: {e}")
+
+    handlers = {
+        "search_text_units": lambda: tools.search_text_units(client, **arguments),
+        "list_signals": lambda: tools.list_signals(client, **arguments),
+        "get_signal_detail": lambda: tools.get_signal_detail(client, **arguments),
+        "get_entity_profile": lambda: tools.get_entity_profile(client, **arguments),
+        "list_entities": lambda: tools.list_entities(client, **arguments),
+        "get_themes": lambda: tools.get_themes(client, **arguments),
+        "get_theme_detail": lambda: tools.get_theme_detail(client, **arguments),
+    }
+
+    handler = handlers.get(name)
+    if not handler:
+        return _error_result(f"Unknown tool: {name}")
+
+    try:
+        result = await handler()
+        return _json_result(result)
+    except httpx.HTTPStatusError as e:
+        status = e.response.status_code
+        try:
+            body = e.response.json()
+            message = body.get("error", {}).get("message", e.response.text)
+        except Exception:
+            message = e.response.text
+        if status in (401, 403):
+            return _error_result(f"Authentication failed: {message}")
+        if status == 429:
+            return _error_result(f"Rate limit exceeded: {message}")
+        if status == 400:
+            return _error_result(message)
+        return _error_result(f"API error: {message}")
+    except httpx.RequestError as e:
+        return _error_result(f"API connection error: {e}")
+
+
+# --- Transport modes ---
+
+
+async def _run_stdio() -> None:
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(
+            read_stream, write_stream, server.create_initialization_options()
+        )
+
+
+def _create_sse_app(host: str, port: int):
+    """Create a Starlette app that serves the MCP server over SSE."""
+    from mcp.server.sse import SseServerTransport
+    from starlette.applications import Starlette
+    from starlette.routing import Mount, Route
+
+    sse_transport = SseServerTransport("/messages/")
+
+    async def handle_sse(scope, receive, send):
+        async with sse_transport.connect_sse(scope, receive, send) as (
+            read_stream,
+            write_stream,
+        ):
+            await server.run(
+                read_stream, write_stream, server.create_initialization_options()
+            )
+
+    return Starlette(
+        routes=[
+            Route("/sse", app=handle_sse),
+            Mount("/messages/", app=sse_transport.handle_post_message),
+        ],
+    )
+
+
+def _run_sse(host: str, port: int) -> None:
+    import uvicorn
+
+    app = _create_sse_app(host, port)
+    uvicorn.run(app, host=host, port=port)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Gildea MCP Server")
+    parser.add_argument(
+        "--sse", action="store_true", help="Run in SSE mode (HTTP server)"
+    )
+    parser.add_argument("--host", default="0.0.0.0", help="SSE host (default: 0.0.0.0)")
+    parser.add_argument(
+        "--port", type=int, default=8001, help="SSE port (default: 8001)"
+    )
+    args = parser.parse_args()
+
+    if args.sse:
+        _run_sse(args.host, args.port)
+    else:
+        asyncio.run(_run_stdio())
+
+
+if __name__ == "__main__":
+    main()

gildea_sdk/mcp/tools.py

@@ -0,0 +1,164 @@
+"""MCP tool implementations — thin HTTP proxies to the REST API."""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+
+async def search_text_units(
+    client: httpx.AsyncClient,
+    *,
+    q: str | None = None,
+    similar_to: str | None = None,
+    unit_type: str | None = None,
+    entity: str | None = None,
+    theme: str | None = None,
+    published_after: str | None = None,
+    published_before: str | None = None,
+    recency_boost: float | None = None,
+    verification_detail: str | None = None,
+    limit: int = 10,
+) -> dict[str, Any]:
+    params: dict[str, Any] = {"limit": limit}
+    if q:
+        params["q"] = q
+    if similar_to:
+        params["similar_to"] = similar_to
+    if unit_type:
+        params["unit_type"] = unit_type
+    if entity:
+        params["entity"] = entity
+    if theme:
+        params["theme"] = theme
+    if published_after:
+        params["published_after"] = published_after
+    if published_before:
+        params["published_before"] = published_before
+    if recency_boost is not None:
+        params["recency_boost"] = recency_boost
+    if verification_detail:
+        params["verification_detail"] = verification_detail
+    resp = await client.get("/v1/search", params=params)
+    resp.raise_for_status()
+    return resp.json()
+
+
+async def list_signals(
+    client: httpx.AsyncClient,
+    *,
+    entity: str | None = None,
+    theme: str | None = None,
+    q: str | None = None,
+    content_type: str | None = None,
+    published_after: str | None = None,
+    published_before: str | None = None,
+    limit: int = 25,
+) -> dict[str, Any]:
+    params: dict[str, Any] = {"limit": limit}
+    if entity:
+        params["entity"] = entity
+    if theme:
+        params["theme"] = theme
+    if q:
+        params["q"] = q
+    if content_type:
+        params["content_type"] = content_type
+    if published_after:
+        params["published_after"] = published_after
+    if published_before:
+        params["published_before"] = published_before
+    resp = await client.get("/v1/signals", params=params)
+    resp.raise_for_status()
+    return resp.json()
+
+
+async def get_signal_detail(
+    client: httpx.AsyncClient,
+    *,
+    signal_id: str,
+    include: str | None = None,
+    verification_detail: str | None = None,
+) -> dict[str, Any]:
+    params: dict[str, str] = {}
+    if include:
+        params["include"] = include
+    if verification_detail:
+        params["verification_detail"] = verification_detail
+    resp = await client.get(f"/v1/signals/{quote(signal_id, safe='')}", params=params)
+    resp.raise_for_status()
+    return resp.json()
+
+
+async def get_entity_profile(
+    client: httpx.AsyncClient,
+    *,
+    name_or_id: str,
+) -> dict[str, Any]:
+    resp = await client.get(f"/v1/entities/{quote(name_or_id, safe='')}")
+    resp.raise_for_status()
+    return resp.json()
+
+
+async def list_entities(
+    client: httpx.AsyncClient,
+    *,
+    q: str | None = None,
+    theme: str | None = None,
+    type_primary: str | None = None,
+    sort: str = "signal_count",
+    limit: int = 25,
+    direction: str | None = None,
+    confidence: str | None = None,
+    stability: str | None = None,
+    scale: str | None = None,
+    priority: str | None = None,
+) -> dict[str, Any]:
+    params: dict[str, Any] = {"sort": sort, "limit": limit}
+    if q:
+        params["q"] = q
+    if theme:
+        params["theme"] = theme
+    if type_primary:
+        params["type_primary"] = type_primary
+    if direction:
+        params["direction"] = direction
+    if confidence:
+        params["confidence"] = confidence
+    if stability:
+        params["stability"] = stability
+    if scale:
+        params["scale"] = scale
+    if priority:
+        params["priority"] = priority
+    resp = await client.get("/v1/entities", params=params)
+    resp.raise_for_status()
+    return resp.json()
+
+
+async def get_themes(
+    client: httpx.AsyncClient,
+    *,
+    axis: str | None = None,
+) -> dict[str, Any]:
+    params: dict[str, str] = {}
+    if axis:
+        params["axis"] = axis
+    resp = await client.get("/v1/themes", params=params)
+    resp.raise_for_status()
+    return resp.json()
+
+
+async def get_theme_detail(
+    client: httpx.AsyncClient,
+    *,
+    axis: str,
+    label: str,
+) -> dict[str, Any]:
+    resp = await client.get(
+        f"/v1/themes/{quote(axis, safe='')}/{quote(label, safe='')}"
+    )
+    resp.raise_for_status()
+    return resp.json()

gildea_sdk/pagination.py

@@ -0,0 +1,77 @@
+"""Shared request helpers and auto-pagination for the Gildea SDK."""
+
+from __future__ import annotations
+
+from urllib.parse import quote
+
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    NotFoundError,
+    RateLimitError,
+)
+
+__all__ = ["_request", "_paginate", "_clean", "_quote"]
+
+
+def _clean(params: dict) -> dict:
+    """Remove None values from a dict of query parameters."""
+    return {k: v for k, v in params.items() if v is not None}
+
+
+def _quote(segment: str) -> str:
+    """URL-encode a path segment."""
+    return quote(segment, safe="")
+
+
+def _request(client, method: str, path: str, *, params: dict | None = None):
+    """Send a request and return parsed JSON, raising typed errors on failure."""
+    resp = client.request(method, path, params=params)
+
+    if resp.status_code == 204:
+        return None
+
+    try:
+        body = resp.json()
+    except Exception:
+        if resp.is_success:
+            raise APIError(
+                f"Invalid JSON in response: {resp.text[:200]}",
+                code="invalid_response",
+                status=resp.status_code,
+            )
+        raise APIError(resp.text[:200] or "Unknown error", code="server_error", status=resp.status_code)
+
+    if resp.is_success:
+        return body
+
+    error = body.get("error", {})
+    msg = error.get("message", resp.text)
+    code = error.get("code")
+    status = resp.status_code
+
+    if status in (401, 403):
+        raise AuthenticationError(msg, code=code, status=status)
+    if status == 404:
+        raise NotFoundError(msg, code=code, status=status)
+    if status == 429:
+        retry_after = resp.headers.get("Retry-After")
+        if retry_after is not None:
+            retry_after = int(retry_after)
+        raise RateLimitError(msg, code=code, status=status, retry_after=retry_after)
+    if status == 400:
+        raise BadRequestError(msg, code=code, status=status)
+
+    raise APIError(msg, code=code, status=status)
+
+
+def _paginate(client, path: str, params: dict):
+    """Auto-paginating generator that yields items from paginated list endpoints."""
+    params = dict(params)  # copy so we can mutate
+    while True:
+        resp = _request(client, "GET", path, params=_clean(params))
+        yield from resp["data"]
+        if not resp.get("has_more"):
+            break
+        params["cursor"] = resp["cursor"]

gildea_sdk/resources/__init__.py

@@ -0,0 +1,6 @@
+from .entities import EntitiesResource
+from .search import SearchResource
+from .signals import SignalsResource
+from .themes import ThemesResource
+
+__all__ = ["SignalsResource", "EntitiesResource", "ThemesResource", "SearchResource"]

gildea_sdk/resources/entities.py

@@ -0,0 +1,50 @@
+"""Entities resource."""
+
+from __future__ import annotations
+
+from ..pagination import _clean, _paginate, _quote, _request
+
+
+class EntitiesResource:
+    def __init__(self, client):
+        self._client = client
+
+    def list(
+        self,
+        *,
+        theme=None,
+        type_primary=None,
+        q=None,
+        sort="signal_count",
+        cursor=None,
+        limit=25,
+        direction=None,
+        confidence=None,
+        stability=None,
+        scale=None,
+        priority=None,
+    ):
+        params = _clean(
+            {
+                "theme": theme,
+                "type_primary": type_primary,
+                "q": q,
+                "sort": sort,
+                "cursor": cursor,
+                "limit": limit,
+                "direction": direction,
+                "confidence": confidence,
+                "stability": stability,
+                "scale": scale,
+                "priority": priority,
+            }
+        )
+        return _request(self._client, "GET", "/v1/entities", params=params)
+
+    def get(self, name_or_id):
+        path = f"/v1/entities/{_quote(name_or_id)}"
+        return _request(self._client, "GET", path)
+
+    def list_all(self, **kwargs):
+        """Auto-paginating iterator that yields every entity matching the filters."""
+        return _paginate(self._client, "/v1/entities", kwargs)

gildea_sdk/resources/search.py

@@ -0,0 +1,44 @@
+"""Search resource."""
+
+from __future__ import annotations
+
+from ..pagination import _clean, _request
+
+
+class SearchResource:
+    def __init__(self, client):
+        self._client = client
+
+    def query(
+        self,
+        q=None,
+        *,
+        similar_to=None,
+        unit_type=None,
+        entity=None,
+        theme=None,
+        published_after=None,
+        published_before=None,
+        recency_boost=None,
+        verification_detail=None,
+        limit=10,
+    ):
+        if not q and not similar_to:
+            raise ValueError("Exactly one of q or similar_to is required")
+        if q and similar_to:
+            raise ValueError("Exactly one of q or similar_to is required")
+        params = _clean(
+            {
+                "q": q,
+                "similar_to": similar_to,
+                "unit_type": unit_type,
+                "entity": entity,
+                "theme": theme,
+                "published_after": published_after,
+                "published_before": published_before,
+                "recency_boost": recency_boost,
+                "verification_detail": verification_detail,
+                "limit": limit,
+            }
+        )
+        return _request(self._client, "GET", "/v1/search", params=params)

gildea_sdk/resources/signals.py

@@ -0,0 +1,47 @@
+"""Signals resource."""
+
+from __future__ import annotations
+
+from ..pagination import _clean, _paginate, _quote, _request
+
+
+class SignalsResource:
+    def __init__(self, client):
+        self._client = client
+
+    def list(
+        self,
+        *,
+        entity=None,
+        theme=None,
+        q=None,
+        content_type=None,
+        published_after=None,
+        published_before=None,
+        cursor=None,
+        limit=25,
+    ):
+        params = _clean(
+            {
+                "entity": entity,
+                "theme": theme,
+                "q": q,
+                "content_type": content_type,
+                "published_after": published_after,
+                "published_before": published_before,
+                "cursor": cursor,
+                "limit": limit,
+            }
+        )
+        return _request(self._client, "GET", "/v1/signals", params=params)
+
+    def get(self, signal_id, *, include=None, verification_detail=None):
+        path = f"/v1/signals/{_quote(signal_id)}"
+        params = _clean(
+            {"include": include, "verification_detail": verification_detail}
+        )
+        return _request(self._client, "GET", path, params=params)
+
+    def list_all(self, **kwargs):
+        """Auto-paginating iterator that yields every signal matching the filters."""
+        return _paginate(self._client, "/v1/signals", kwargs)

gildea_sdk/resources/themes.py

@@ -0,0 +1,18 @@
+"""Themes resource."""
+
+from __future__ import annotations
+
+from ..pagination import _clean, _quote, _request
+
+
+class ThemesResource:
+    def __init__(self, client):
+        self._client = client
+
+    def list(self, *, axis=None):
+        params = _clean({"axis": axis})
+        return _request(self._client, "GET", "/v1/themes", params=params)
+
+    def get(self, axis, label):
+        path = f"/v1/themes/{_quote(axis)}/{_quote(label)}"
+        return _request(self._client, "GET", path)