> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gildea.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Install and use the official Python client library

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

## Installation

```bash theme={null}
pip install gildea
```

Requires Python 3.9+ and has a single dependency (`httpx`).

## Quick start

```python theme={null}
from gildea import Gildea

client = Gildea()  # reads GILDEA_API_KEY from env

signals = client.signals.list(entity="NVIDIA", limit=5)
for s in signals["signals"]:
    print(s["title"])
```

You can also pass the key explicitly:

```python theme={null}
client = Gildea(api_key="gld_your_key")
```

## Resources

The client organizes endpoints into resource namespaces.

### Signals

```python theme={null}
# List signals (all filters optional; defaults to most recent)
client.signals.list(entity="NVIDIA", limit=5)
client.signals.list(keyword="GPU supply chain", content_type="analysis")

# Get the full verified units (evidence included by default)
client.signals.get("0001f3a7b9c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7")
```

### Entities

```python theme={null}
# List entities
client.entities.list(type="organization", limit=10)
client.entities.list(name="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="Large", stability="Steady")
client.entities.list(direction="New", sort="first_seen", limit=10)
```

### Themes

```python theme={null}
# 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")
```

### Search

```python theme={null}
# Hybrid dense + sparse search with cross-encoder rerank, over all verified text units
client.search("AI chip supply constraints", limit=5)
client.search("AI chip supply constraints", role="claim", entity="NVIDIA")
```

## Auto-pagination

List endpoints return one page at a time. Use `list_all` to iterate through every result automatically:

```python theme={null}
for signal in client.signals.list_all(entity="NVIDIA"):
    print(signal["title"])

for entity in client.entities.list_all(type="organization"):
    print(entity["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:

```python theme={null}
from gildea 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 Status | Exception             | Description                                      |
| ----------- | --------------------- | ------------------------------------------------ |
| 400         | `BadRequestError`     | Invalid parameters                               |
| 401 / 403   | `AuthenticationError` | Invalid or missing API key                       |
| 404         | `NotFoundError`       | Resource not found                               |
| 429         | `RateLimitError`      | Rate limit exceeded (`.retry_after` has seconds) |
| 5xx         | `APIError`            | Server error                                     |

## Configuration

```python theme={null}
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:

```python theme={null}
with Gildea() as client:
    signals = client.signals.list(keyword="AI", limit=5)
```