gildea 0.9.1

Python client for the Gildea market data API for AI

Gildea

Python client for the Gildea 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 Code or Cursor, 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.

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 Code or Cursor, 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 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.

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):

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

The 7 Gildea tools appear in Cursor's MCP settings.

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. Claude Desktop is not currently supported: its connector UI only accepts OAuth, and its config file does not pass custom headers to remote MCP servers. See the MCP guide for current client support.

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

Documentation

Full API docs at docs.gildea.ai.

License

MIT