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

Search uses modern hybrid retrieval — dense and learned sparse embeddings 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) for details.

## Install

```bash
# Python client only
pip install gildea

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

## Quick Start

```python
from gildea_sdk import Gildea

client = Gildea(api_key="gld_your_key_here")

# Search verified text units
results = client.search(query="data center infrastructure spending")
for hit in results["data"]:
    print(hit["unit"]["text"])
    print(f"  Source: {hit['citation']['signal_title']} ({hit['citation']['registrable_domain']})")

# Get full signal decomposition with evidence
signal = client.signals.get("signal_id", include="evidence")

# Entity intelligence with trend analytics
entity = client.entities.get("NVIDIA")
print(f"{entity['display_name']}: {entity['direction']}, {entity['scale']} scale, {entity['notability']} notability")

# Cross-source consensus mapping
similar = client.search(similar_to="unit_id")

# Embed arbitrary text into Gildea's vector space
vector = client.embed("Data center capex is accelerating.")["embedding"]
```

## Local similarity search

Pair `include="embeddings"` on signal detail with `client.embed()` to compute cosine similarity between user content and verified Gildea units, fully client-side:

```python
import numpy as np
from gildea_sdk import Gildea

client = Gildea(api_key="gld_your_key_here")

# 1. Embed user content
user_vec = np.array(client.embed("I think infrastructure spending will slow in H2.")["embedding"])

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

# 3. Find semantically related text units
def iter_units(decomp):
    for arg in decomp.get("arguments", []):
        yield from arg.get("sentences", []) + arg.get("claims", [])
    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']}")
```

Embeddings are 768-dim `BAAI/bge-base-en-v1.5` vectors. Both endpoints return vectors in the same space. See [docs.gildea.ai/concepts/embeddings](https://docs.gildea.ai/concepts/embeddings) for details.

## MCP Server

Use Gildea as a tool in Claude, ChatGPT, Cursor, VS Code, or any MCP-compatible client.

```bash
# Run directly
gildea-mcp

# Or via uvx (no install needed)
uvx --from gildea[mcp] gildea-mcp
```

Set your API key:
```bash
export GILDEA_API_KEY=gld_your_key_here
```

### Claude Desktop

Add to your `claude_desktop_config.json`:

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

### Available MCP Tools

| Tool | Description |
|------|-------------|
| `search_text_units` | Semantic 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 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 your API key at [gildea.ai](https://gildea.ai). Free tier includes 5 requests/minute and 200 requests/month.

## Documentation

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

## License

MIT
