gildea 0.4.1

Python client and MCP server for the Gildea AI market intelligence API

Gildea

Python client and MCP server 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 and an MCP server so AI assistants can use the data directly.

Hybrid retrieval — Cohere embed-english-v3.0 dense + Pinecone DeepImpact sparse, fused via RRF, with Cohere cross-encoder reranking — for high precision on verified, citable text units. See How search works.

Install

# 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 carrying a verdict, a similarity score, and an evidence-backed citation:

from gildea_sdk import Gildea

client = Gildea(api_key="gld_your_key_here")

results = client.search(query="data center power constraints")

for hit in results["data"][:3]:
    print(f"\n{hit['unit']['text']}")
    print(f"  ↳ {hit['citation']['signal_title']} ({hit['citation']['registrable_domain']})")
    print(f"  ↳ verdict: {hit['verification']['final_verdict']}, "
          f"score: {hit['verification']['primary_score']:.2f}")

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

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)
  ↳ verdict: pass, score: 0.92

Drill into a source

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

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

for claim in signal["decomposition"].get("claims", []):
    print(f"{claim['unit']['text']}  [{claim['verification']['final_verdict']}]")

Entity intelligence

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

nvidia = client.entities.get("NVIDIA")
print(f"{nvidia['display_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["data"][0]["unit"]["unit_id"]
similar = client.search(similar_to=unit_id, limit=5)

Embed your own content

/v1/embed returns 1024-dim Cohere embed-english-v3.0 vectors in the same space as Gildea's stored unit embeddings. Pair with include="embeddings" on signal detail to compute cosine similarity client-side:

import numpy as np

# Embed user content (memo, draft, query) in Gildea's vector space
user_vec = np.array(client.embed("Infrastructure spending will slow in H2.")["embedding"])

# Fetch a signal with per-unit embeddings
signal = client.signals.get(signal_id, include="embeddings")

# Find related units locally — no extra API calls
def iter_units(decomp):
    for arg in decomp.get("arguments", []):
        yield from arg.get("sentences", [])
    yield from decomp.get("claims", [])
    if "thesis" in decomp:
        yield from decomp["thesis"].get("sentences", [])
    if "summary" in decomp:
        yield from decomp["summary"].get("sentences", [])

for u in iter_units(signal["decomposition"]):
    if "embedding" in u:
        sim = float(np.dot(user_vec, np.array(u["embedding"])))  # both unit-normalized
        if sim > 0.7:
            print(f"[{sim:.3f}] {u['unit']['text']}")

See docs.gildea.ai/concepts/embeddings for the full local-similarity pattern.

MCP server

Use Gildea as a tool inside Claude. The server is a thin proxy over the REST API — same auth, same data.

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "gildea": {
      "command": "uvx",
      "args": ["--from", "gildea[mcp]", "gildea-mcp"],
      "env": {
        "GILDEA_API_KEY": "gld_your_key_here"
      }
    }
  }
}

Restart Claude Desktop. The Gildea tools (search_text_units, get_signal_detail, get_entity_profile, etc.) appear in the tool list automatically.

Claude Code

claude mcp add gildea -- uvx --from gildea[mcp] gildea-mcp

Then set GILDEA_API_KEY in your environment.

Other MCP clients

The server speaks standard MCP and works with any compliant client (Cursor, VS Code via Cline/Continue, ChatGPT Desktop, etc.). Each client has its own config syntax — see your client's MCP documentation.

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