Metadata-Version: 2.4
Name: gildea
Version: 0.6.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
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 the AI economy, decomposes each one into verified reasoning chains (thesis, arguments, claims, evidence), and serves them through a REST API. This package gives you a Python client and an MCP server so AI assistants can use the data directly.

Hybrid retrieval — dense neural embeddings + learned sparse, fused via RRF, with cross-encoder reranking — for high precision on verified, citable text units. See [How search works](https://docs.gildea.ai/concepts/search).

## Install

```bash
# Python client only
pip install gildea

# With MCP server
pip install gildea[mcp]
```

## 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="data center power constraints")

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

```
Spending on data center construction has surpassed a $42B annualized pace, a more than 300% increase…
  ↳ America's $1T AI Gamble (apricitas.io)

Major technology companies are projected to spend approximately $650 billion in 2026 on AI data centers…
  ↳ Nebius Plans to Raise $3.75 Billion in Debt After Meta Deal (bloomberg.com)
```

## Drill into a source

Pass any `signal_id` from a search result to get the full verified decomposition — thesis, supporting arguments, evidence-backed claims:

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

for claim in signal["decomposition"].get("claims", []):
    print(claim["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

The hosted MCP server is the simplest path — paste the URL + your API key, no Python install needed. The SDK's `gildea-mcp` binary is for users who want to run the server locally (air-gapped environments, self-hosted Gildea API, SDK development).

### Claude Desktop (hosted, recommended)

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 (hosted)

```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`.

### Local install (advanced)

If you'd rather run the server locally (no remote dependency, custom Gildea API host, etc.):

```bash
# Option A — with uv (recommended; brew install uv)
# Claude Desktop config:
{
  "mcpServers": {
    "gildea": {
      "command": "uvx",
      "args": ["--from", "gildea[mcp]", "gildea-mcp"],
      "env": { "GILDEA_API_KEY": "gld_your_key_here" }
    }
  }
}

# Option B — with pip
pip install "gildea[mcp]"
# Claude Desktop config:
{ "mcpServers": { "gildea": { "command": "gildea-mcp", "env": { "GILDEA_API_KEY": "..." } } } }
```

For Claude Code: `claude mcp add gildea -- uvx --from "gildea[mcp]" gildea-mcp` (or `-- gildea-mcp` for the pip path).

### 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: thesis, arguments, claims, 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
