gildea 0.1.0__tar.gz

gildea-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.env
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+*.log
+.DS_Store

gildea-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: gildea
+Version: 0.1.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
+Project-URL: Repository, https://github.com/hjones20/gildea-api
+Project-URL: Issues, https://github.com/hjones20/gildea-api/issues
+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.
+
+## 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(q="data center infrastructure spending")
+for hit in results.data:
+    print(f"{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.priority} priority")
+
+# Cross-source consensus mapping
+similar = client.search.query(similar_to="unit_id")
+```
+
+## 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, priority, 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

gildea-0.1.0/README.md

@@ -0,0 +1,98 @@
+# 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.
+
+## 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(q="data center infrastructure spending")
+for hit in results.data:
+    print(f"{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.priority} priority")
+
+# Cross-source consensus mapping
+similar = client.search.query(similar_to="unit_id")
+```
+
+## 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, priority, 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

gildea-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "gildea"
+version = "0.1.0"
+description = "Python client and MCP server for the Gildea AI market intelligence API"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{name = "Holly Jones"}]
+readme = "README.md"
+keywords = ["ai", "market-intelligence", "mcp", "api-client", "competitive-intelligence"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = ["httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://gildea.ai"
+Documentation = "https://docs.gildea.ai"
+Repository = "https://github.com/hjones20/gildea-api"
+Issues = "https://github.com/hjones20/gildea-api/issues"
+
+[project.optional-dependencies]
+mcp = ["mcp[server]>=1.3"]
+dev = ["pytest>=8", "pytest-httpx>=0.35", "pytest-asyncio>=0.24", "mcp[server]>=1.3", "ruff>=0.15"]
+
+[project.scripts]
+gildea-mcp = "gildea_sdk.mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/gildea_sdk"]
+
+[tool.ruff]
+target-version = "py39"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

gildea-0.1.0/src/gildea_sdk/__init__.py

@@ -0,0 +1,21 @@
+"""Gildea Python SDK — client for the Gildea AI market intelligence API."""
+
+from .client import Gildea
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    GildeaError,
+    NotFoundError,
+    RateLimitError,
+)
+
+__all__ = [
+    "Gildea",
+    "GildeaError",
+    "AuthenticationError",
+    "NotFoundError",
+    "RateLimitError",
+    "BadRequestError",
+    "APIError",
+]

gildea-0.1.0/src/gildea_sdk/client.py

@@ -0,0 +1,49 @@
+"""Main Gildea client."""
+
+from __future__ import annotations
+
+import os
+
+import httpx
+
+from .exceptions import AuthenticationError
+from .resources import EntitiesResource, SearchResource, SignalsResource, ThemesResource
+
+
+class Gildea:
+    """Synchronous client for the Gildea AI market intelligence API."""
+
+    def __init__(self, api_key=None, base_url="https://api.gildea.ai", timeout=30.0):
+        self.api_key = api_key or os.environ.get("GILDEA_API_KEY")
+        if not self.api_key:
+            raise AuthenticationError(
+                "No API key provided. Set GILDEA_API_KEY or pass api_key=."
+            )
+        self._client = httpx.Client(
+            base_url=base_url,
+            headers={"X-API-Key": self.api_key},
+            timeout=timeout,
+        )
+        self.signals = SignalsResource(self._client)
+        self.entities = EntitiesResource(self._client)
+        self.themes = ThemesResource(self._client)
+        self._search = SearchResource(self._client)
+
+    def search(self, query=None, *, similar_to=None, **kwargs):
+        """Search across all verified text units.
+
+        Two modes: pass ``query`` for hybrid semantic + keyword search,
+        or ``similar_to`` with a text unit ID for pure vector similarity.
+        Exactly one is required.
+        """
+        return self._search.query(query, similar_to=similar_to, **kwargs)
+
+    def close(self):
+        """Close the underlying HTTP connection."""
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()

gildea-0.1.0/src/gildea_sdk/exceptions.py

@@ -0,0 +1,34 @@
+"""Exception classes for the Gildea SDK."""
+
+
+class GildeaError(Exception):
+    """Base exception for all Gildea SDK errors."""
+
+    def __init__(self, message, *, code=None, status=None):
+        super().__init__(message)
+        self.code = code
+        self.status = status
+
+
+class AuthenticationError(GildeaError):
+    """Raised on 401/403 responses or missing API key."""
+
+
+class NotFoundError(GildeaError):
+    """Raised on 404 responses."""
+
+
+class RateLimitError(GildeaError):
+    """Raised on 429 responses."""
+
+    def __init__(self, message, *, code=None, status=None, retry_after=None):
+        super().__init__(message, code=code, status=status)
+        self.retry_after = retry_after
+
+
+class BadRequestError(GildeaError):
+    """Raised on 400 responses."""
+
+
+class APIError(GildeaError):
+    """Raised on 5xx or other unexpected responses."""

gildea-0.1.0/src/gildea_sdk/mcp/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running MCP server as: python -m gildea_sdk.mcp"""
+
+from gildea_sdk.mcp.server import main
+
+main()