feat(fetch): add Composio provider for Twitter/X

src/kurt/tools/fetch/providers/composio/__init__.py

@@ -0,0 +1,4 @@
+"""Composio fetch provider for Twitter/X.
+
+Zero-cost Twitter search via Composio API (20k free calls/month).
+"""

src/kurt/tools/fetch/providers/composio/config.py

@@ -0,0 +1,33 @@
+"""Configuration for Composio fetch provider."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class ComposioProviderConfig(BaseModel):
+    """Configuration for Composio Twitter/X provider.
+
+    Requires:
+    - COMPOSIO_API_KEY environment variable
+    - COMPOSIO_CONNECTION_ID environment variable (from Composio dashboard)
+
+    Free tier: 20,000 API calls/month.
+    """
+
+    timeout: float = Field(
+        default=60.0,
+        gt=0,
+        description="Request timeout in seconds",
+    )
+    max_results: int = Field(
+        default=100,
+        ge=10,
+        le=100,
+        description="Maximum results per search (10-100)",
+    )
+    cache_ttl_hours: int = Field(
+        default=6,
+        ge=0,
+        description="Cache TTL in hours (0 to disable)",
+    )

src/kurt/tools/fetch/providers/composio/fixtures/error.json

@@ -0,0 +1,8 @@
+{
+  "content": "",
+  "metadata": {
+    "engine": "composio"
+  },
+  "success": false,
+  "error": "[Composio] Credentials not configured. Set COMPOSIO_API_KEY and COMPOSIO_CONNECTION_ID."
+}

src/kurt/tools/fetch/providers/composio/fixtures/success.json

@@ -0,0 +1,17 @@
+{
+  "content": "# Tweet by Test User (@testuser)\n\n**Date:** 2026-02-15T10:00:00Z\n**URL:** https://x.com/testuser/status/123456789\n\nThis is a test tweet with some content.\n\n**Engagement:** 100 likes · 50 retweets · 10 replies · 5,000 views\n",
+  "metadata": {
+    "engine": "composio",
+    "url": "https://x.com/testuser/status/123456789",
+    "tweet_id": "123456789",
+    "author": "testuser",
+    "created_at": "2026-02-15T10:00:00Z",
+    "like_count": 100,
+    "retweet_count": 50,
+    "reply_count": 10,
+    "impression_count": 5000,
+    "fetched_at": "2026-02-15T12:00:00Z"
+  },
+  "success": true,
+  "error": null
+}

src/kurt/tools/fetch/providers/composio/mock.py

@@ -0,0 +1,97 @@
+"""Mock Composio fetcher for testing."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Callable
+
+from kurt.tools.fetch.core.base import FetchResult
+
+
+class MockComposioFetcher:
+    """Mock Composio fetcher for testing.
+
+    Provides call tracking, fixture loading, and configurable responses
+    without requiring Composio credentials.
+    """
+
+    name = "composio"
+    version = "mock"
+    url_patterns = ["*twitter.com/*", "*x.com/*"]
+    requires_env: list[str] = []
+
+    def __init__(self) -> None:
+        self._calls: list[dict[str, Any]] = []
+        self._response: FetchResult | None = None
+        self._error: Exception | None = None
+        self._response_fn: Callable[[str], FetchResult] | None = None
+
+    @property
+    def calls(self) -> list[dict[str, Any]]:
+        """Record of all fetch() calls."""
+        return self._calls
+
+    @property
+    def call_count(self) -> int:
+        return len(self._calls)
+
+    def was_called_with(self, url: str) -> bool:
+        """Check if fetch was called with specific URL."""
+        return any(c["url"] == url for c in self._calls)
+
+    def reset(self) -> None:
+        """Clear call history and responses."""
+        self._calls.clear()
+        self._response = None
+        self._error = None
+        self._response_fn = None
+
+    def with_error(self, error: Exception) -> MockComposioFetcher:
+        """Configure mock to raise an error."""
+        self._error = error
+        return self
+
+    def with_response(self, response: FetchResult) -> MockComposioFetcher:
+        """Configure mock to return specific response."""
+        self._response = response
+        return self
+
+    def with_fixture(self, fixture_name: str) -> MockComposioFetcher:
+        """Load response from fixture file."""
+        fixture_path = Path(__file__).parent / "fixtures" / f"{fixture_name}.json"
+        data = json.loads(fixture_path.read_text())
+        self._response = FetchResult(**data)
+        return self
+
+    def with_response_fn(self, fn: Callable[[str], FetchResult]) -> MockComposioFetcher:
+        """Configure mock to use a function for responses."""
+        self._response_fn = fn
+        return self
+
+    def fetch(self, url: str, **kwargs: Any) -> FetchResult:
+        """Mock fetch implementation."""
+        self._calls.append({"url": url, **kwargs})
+
+        if self._error:
+            raise self._error
+
+        if self._response_fn:
+            return self._response_fn(url)
+
+        if self._response:
+            return self._response
+
+        return self.with_fixture("success")._response  # type: ignore[return-value]
+
+
+def create_mock(**kwargs: Any) -> MockComposioFetcher:
+    """Create a configured mock."""
+    mock = MockComposioFetcher()
+    if "response" in kwargs:
+        mock.with_response(kwargs["response"])
+    if "error" in kwargs:
+        mock.with_error(kwargs["error"])
+    if "fixture" in kwargs:
+        mock.with_fixture(kwargs["fixture"])
+    return mock