Skip to main content
The gildea package is a thin Python client that wraps the REST API with typed errors, auto-pagination, and resource namespaces.

​
Installation

pip install gildea
Requires Python 3.9+ and has a single dependency (httpx).

​
Quick start

from gildea_sdk import Gildea

client = Gildea()  # reads GILDEA_API_KEY from env

signals = client.signals.list(entity="NVIDIA", limit=5)
for s in signals["data"]:
    print(s["title"])
You can also pass the key explicitly: 
client = Gildea(api_key="gld_your_key")

​
Resources

The client organizes endpoints into resource namespaces.

​
Signals

# List signals (all filters optional — defaults to most recent)
client.signals.list(entity="NVIDIA", limit=5)
client.signals.list(q="GPU supply chain", content_type="analysis")

# Get full decomposition
client.signals.get("sig_01J...")
client.signals.get("sig_01J...", include="evidence", verification_detail="full")

​
Entities

# List entities
client.entities.list(type_primary="Organization", limit=10)
client.entities.list(q="OpenAI", sort="trend")

# Get entity profile with related entities
client.entities.get("NVIDIA")

# Filter by interpretation fields (composable)
client.entities.list(direction="Rising", confidence="Significant", sort="trend", limit=5)
client.entities.list(scale="High", stability="Steady")
client.entities.list(direction="New", sort="first_seen", limit=10)

​
Themes

# List all themes or filter by axis
client.themes.list()
client.themes.list(axis="value_chain")

# Get theme detail with related themes
client.themes.get("value_chain", "Foundation Models")

# Semantic + keyword search across all verified text units
client.search("AI chip supply constraints", limit=5)
client.search("AI chip supply constraints", unit_type="analysis_claim", entity="NVIDIA")

​
Auto-pagination

List endpoints return one page at a time. Use list_all to iterate through every result automatically: 
for signal in client.signals.list_all(entity="NVIDIA"):
    print(signal["title"])

for entity in client.entities.list_all(type_primary="Organization"):
    print(entity["display_name"])
list_all is a generator — it fetches pages lazily as you iterate, so you can break early without wasting requests.

​
Error handling

The SDK maps HTTP errors to typed exceptions: 
from gildea_sdk import (
    Gildea,
    AuthenticationError,
    NotFoundError,
    RateLimitError,
    BadRequestError,
    APIError,
)

client = Gildea()

try:
    client.signals.get("sig_nonexistent")
except NotFoundError as e:
    print(f"Not found: {e}")
except RateLimitError as e:
    print(f"Rate limited — retry after {e.retry_after}s")
except AuthenticationError as e:
    print(f"Auth failed: {e}")
except APIError as e:
    print(f"API error ({e.status}): {e}")
HTTP StatusExceptionDescription
400BadRequestErrorInvalid parameters
401 / 403AuthenticationErrorInvalid or missing API key
404NotFoundErrorResource not found
429RateLimitErrorRate limit exceeded (.retry_after has seconds)
5xxAPIErrorServer error

​
Configuration

client = Gildea(
    api_key="gld_...",                     # or set GILDEA_API_KEY env var
    base_url="https://api.gildea.ai",      # override for self-hosted
    timeout=30.0,                          # request timeout in seconds
)
The client can be used as a context manager to ensure the connection is closed: 
with Gildea() as client:
    signals = client.signals.list(q="AI", limit=5)