gildea 0.8.0

Python client for the Gildea AI market intelligence API

Gildea

Python client for the Gildea 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 for that API. (For MCP clients like Claude Desktop, connect to the hosted MCP server — see below; no install needed.)

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.

Install

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:

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 arguments, and atomic claims. Each unit carries its evidence by default:

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:

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:

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:

{
  "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

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.

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. Free tier: 5 requests/minute, 200 requests/month, full API + MCP access — no feature gates.

Documentation

Full API docs at docs.gildea.ai.

License

MIT