Metadata-Version: 2.4
Name: gildea
Version: 0.8.2
Summary: Python client for the Gildea market data API for AI
Project-URL: Homepage, https://gildea.ai
Project-URL: Documentation, https://docs.gildea.ai
Author: Holly Jones
License-Expression: MIT
Keywords: ai,api-client,competitive-intelligence,market-intelligence
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: 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'
Description-Content-Type: text/markdown

# Gildea

Python client for the [Gildea](https://gildea.ai) market data API for AI.

Gildea turns raw events and expert analysis on the AI economy into verified, atomic intelligence your code can query. We source, structure, and verify signals from 500+ leading sources worldwide, decompose each into individually verified text units, and serve them through a REST API. Every unit is backed by verbatim evidence and a citation to its source. This package is the Python client for that API. (For MCP clients like Claude Desktop, connect to the hosted MCP server; see below, no install needed.)

The standout call is hybrid search (semantic plus keyword) over those verified units, tuned for precise, citable facts. See [How search works](https://docs.gildea.ai/concepts/search).

## Install

```bash
pip install gildea
```

## Quick start

The differentiating call is `search()`. Every hit is a verified atomic fact with an evidence-backed citation back to its source:

```python
from gildea import Gildea

client = Gildea(api_key="gld_your_key_here")

results = client.search(query="the state of the AI market")

for hit in results["results"][:3]:
    print(f"\n{hit['unit']['text']}")
    print(f"  ↳ {hit['citation']['title']} ({hit['citation']['domain']})")
```

```
Combined US investment in data centers, computers, and software surpasses $1T annualized, representing roughly 3.5% of GDP.
  ↳ America's $1T AI Gamble (apricitas.io)

The market cap of SaaS companies fell by over one trillion dollars due to fears about coding agents.
  ↳ 45 Thoughts About Agents (secondthoughts.ai)
```

## Drill into a source

Pass any `signal_id` from a search result to get the full verified decomposition as a flat list of
units — the central statement (`role` `thesis` for analysis, `synopsis` for events), supporting
`argument`s, and atomic `claim`s. Each unit carries its evidence by default:

```python
signal_id = results["results"][0]["citation"]["signal_id"]
signal = client.signals.get(signal_id)

print(f"{signal['title']} — {signal['verified_unit_count']} verified units")
for unit in signal["units"]:
    print(f"  [{unit['role']}] {unit['text']}")
```

## Entity intelligence

Trend direction, scale, and notability across the full corpus:

```python
nvidia = client.entities.get("NVIDIA")
print(f"{nvidia['name']}: {nvidia['direction']} ({nvidia['scale']} scale, {nvidia['notability']} notability)")
# NVIDIA: Declining (Large scale, High notability)
```

## Cross-source consensus

Find verified text units that semantically match a known one — useful for "find more like this" and corroborating a claim across sources:

```python
unit_id = results["results"][0]["unit"]["id"]
similar = client.search(similar_to=unit_id, limit=5)
```

## MCP server

For MCP clients like Claude Desktop or Claude Code, connect to the **hosted** MCP server — paste the URL + your API key, no Python install needed. (This SDK is the REST client; it does not bundle a local MCP server.)

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "gildea": {
      "url": "https://api.gildea.ai/mcp",
      "headers": { "x-api-key": "gld_your_key_here" }
    }
  }
}
```

Restart Claude Desktop. The 7 Gildea tools appear automatically.

### Claude Code

```bash
claude mcp add gildea --transport http https://api.gildea.ai/mcp --header "x-api-key: gld_your_key_here"
```

Verify: `claude mcp list` → `gildea ✓ Connected`.

### Other MCP clients

Any MCP-compliant client with streamable HTTP support can connect to `https://api.gildea.ai/mcp` with `x-api-key` headers. See the [MCP client list](https://modelcontextprotocol.io/clients).

### Available tools

| Tool | What it does |
|------|---|
| `search_text_units` | Hybrid 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 verified decomposition as flat units: thesis/synopsis, arguments, claims, each with evidence |
| `get_entity_profile` | Entity trend analytics, co-occurrence, theme distribution |
| `list_entities` | Discover entities by trend direction, notability, 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 yours at [gildea.ai](https://gildea.ai). Free tier: 5 requests/minute, 200 requests/month, full API + MCP access — no feature gates.

## Documentation

Full API docs at [docs.gildea.ai](https://docs.gildea.ai).

## License

MIT
