phase 0+1: project scaffold, k8s manifests, CI pipeline, steering, hooks, tests

- Repository structure for all services, infra, lakehouse, dashboards
- K8s manifests targeting stonks-oracle namespace with GHCR images
- Ingress via Traefik with ca-issuer TLS for internal services
- ConfigMap wired to existing cluster services (pg, redis, minio, ollama)
- GitHub Actions workflow for lint, test, multi-service container builds
- Dockerfile with build-arg CMD per service
- Makefile for local build/push/deploy
- Steering rules for TDD workflow, K8s conventions, project context
- Agent hooks for lint-on-save, test-on-save, k8s-validate, phase-commit
- Ruff linter config, all lint issues fixed
- 14 passing tests for schemas, config, redis keys
- PostgreSQL migrations, Trino catalogs, Superset config, MinIO lifecycle

services/adapters/__init__.py

@@ -0,0 +1 @@
+# Ingestion Adapters

services/adapters/base.py

@@ -0,0 +1,29 @@
+"""Base adapter interface for all external API integrations."""
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class AdapterResult:
+    source_type: str
+    ticker: str
+    items: List[Dict[str, Any]]
+    raw_payload: bytes
+    content_hash: str
+    fetched_at: datetime
+    error: Optional[str] = None
+
+
+class BaseAdapter(ABC):
+    """Interface for all ingestion adapters."""
+
+    @abstractmethod
+    async def fetch(self, ticker: str, config: Dict[str, Any]) -> AdapterResult:
+        """Fetch data for a given ticker using source config."""
+        ...
+
+    @abstractmethod
+    def source_type(self) -> str:
+        ...

services/adapters/broker_adapter.py

@@ -0,0 +1,108 @@
+"""Broker API adapter - paper/live trading, orders, positions, balances."""
+import hashlib
+import logging
+import uuid
+from datetime import datetime
+from typing import Any, Dict, Optional
+
+import httpx
+
+from .base import AdapterResult, BaseAdapter
+
+logger = logging.getLogger("broker_adapter")
+
+
+class BrokerAdapter(BaseAdapter):
+    """Broker API adapter supporting paper and live modes."""
+
+    def __init__(self, api_key: str = "", api_secret: str = "", base_url: str = "", mode: str = "paper"):
+        self.api_key = api_key
+        self.api_secret = api_secret
+        self.base_url = base_url
+        self.mode = mode  # paper | live
+
+    def source_type(self) -> str:
+        return "broker"
+
+    def _headers(self) -> Dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+
+    async def fetch(self, ticker: str, config: Dict[str, Any]) -> AdapterResult:
+        """Fetch positions and recent orders for a ticker."""
+        async with httpx.AsyncClient(timeout=30) as client:
+            try:
+                resp = await client.get(
+                    f"{self.base_url}/v2/positions/{ticker}",
+                    headers=self._headers(),
+                )
+                raw = resp.content
+                data = resp.json() if resp.status_code == 200 else {}
+                content_hash = hashlib.sha256(raw).hexdigest()
+
+                return AdapterResult(
+                    source_type="broker",
+                    ticker=ticker,
+                    items=[data] if data else [],
+                    raw_payload=raw,
+                    content_hash=content_hash,
+                    fetched_at=datetime.utcnow(),
+                )
+            except Exception as e:
+                logger.error(f"Broker fetch failed for {ticker}: {e}")
+                return AdapterResult(
+                    source_type="broker",
+                    ticker=ticker,
+                    items=[],
+                    raw_payload=b"",
+                    content_hash="",
+                    fetched_at=datetime.utcnow(),
+                    error=str(e),
+                )
+
+    async def submit_order(
+        self,
+        ticker: str,
+        side: str,
+        qty: float,
+        order_type: str = "market",
+        limit_price: Optional[float] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Submit an order to the broker. Returns broker response."""
+        if self.mode == "live":
+            logger.warning("LIVE order submission")
+
+        idem_key = idempotency_key or str(uuid.uuid4())
+        payload = {
+            "symbol": ticker,
+            "qty": str(qty),
+            "side": side,
+            "type": order_type,
+            "time_in_force": "day",
+        }
+        if limit_price and order_type == "limit":
+            payload["limit_price"] = str(limit_price)
+
+        async with httpx.AsyncClient(timeout=30) as client:
+            try:
+                resp = await client.post(
+                    f"{self.base_url}/v2/orders",
+                    headers={**self._headers(), "Idempotency-Key": idem_key},
+                    json=payload,
+                )
+                resp.raise_for_status()
+                return resp.json()
+            except httpx.HTTPStatusError as e:
+                logger.error(f"Order rejected: {e.response.text}")
+                return {"error": e.response.text, "status": e.response.status_code}
+            except Exception as e:
+                logger.error(f"Order submission failed: {e}")
+                return {"error": str(e)}
+
+    async def get_account(self) -> Dict[str, Any]:
+        async with httpx.AsyncClient(timeout=30) as client:
+            resp = await client.get(f"{self.base_url}/v2/account", headers=self._headers())
+            return resp.json()

services/adapters/filings_adapter.py

@@ -0,0 +1,58 @@
+"""Filings / Regulatory API adapter - fetches SEC-style submissions."""
+import hashlib
+import logging
+from datetime import datetime
+from typing import Any, Dict
+
+import httpx
+
+from .base import AdapterResult, BaseAdapter
+
+logger = logging.getLogger("filings_adapter")
+
+
+class FilingsAdapter(BaseAdapter):
+    """Concrete adapter for SEC EDGAR or similar filings API."""
+
+    def __init__(self, base_url: str = "https://efts.sec.gov", user_agent: str = "StonksOracle/1.0"):
+        self.base_url = base_url
+        self.user_agent = user_agent
+
+    def source_type(self) -> str:
+        return "filings_api"
+
+    async def fetch(self, ticker: str, config: Dict[str, Any]) -> AdapterResult:
+        _cik = config.get("cik", "")
+        endpoint = config.get("endpoint", f"/LATEST/search-index?q=%22{ticker}%22&dateRange=custom&startdt=2026-01-01&forms=8-K,10-Q,10-K")
+        url = f"{self.base_url}{endpoint}"
+
+        headers = {"User-Agent": self.user_agent}
+
+        async with httpx.AsyncClient(timeout=30) as client:
+            try:
+                resp = await client.get(url, headers=headers)
+                resp.raise_for_status()
+                raw = resp.content
+                data = resp.json()
+                content_hash = hashlib.sha256(raw).hexdigest()
+
+                hits = data.get("hits", {}).get("hits", [])
+                return AdapterResult(
+                    source_type="filings_api",
+                    ticker=ticker,
+                    items=hits,
+                    raw_payload=raw,
+                    content_hash=content_hash,
+                    fetched_at=datetime.utcnow(),
+                )
+            except Exception as e:
+                logger.error(f"Filings fetch failed for {ticker}: {e}")
+                return AdapterResult(
+                    source_type="filings_api",
+                    ticker=ticker,
+                    items=[],
+                    raw_payload=b"",
+                    content_hash="",
+                    fetched_at=datetime.utcnow(),
+                    error=str(e),
+                )

services/adapters/market_adapter.py

@@ -0,0 +1,59 @@
+"""Market data API adapter - fetches quotes, bars, and reference data."""
+import hashlib
+import logging
+from datetime import datetime
+from typing import Any, Dict
+
+import httpx
+
+from .base import AdapterResult, BaseAdapter
+
+logger = logging.getLogger("market_adapter")
+
+
+class MarketDataAdapter(BaseAdapter):
+    """Concrete adapter for a market data provider (e.g., Alpha Vantage, Polygon, Yahoo)."""
+
+    def __init__(self, api_key: str = "", base_url: str = ""):
+        self.api_key = api_key
+        self.base_url = base_url
+
+    def source_type(self) -> str:
+        return "market_api"
+
+    async def fetch(self, ticker: str, config: Dict[str, Any]) -> AdapterResult:
+        endpoint = config.get("endpoint", "/v2/aggs/ticker/{ticker}/prev")
+        url = f"{self.base_url}{endpoint.format(ticker=ticker)}"
+        params = config.get("params", {})
+        if self.api_key:
+            params["apiKey"] = self.api_key
+
+        async with httpx.AsyncClient(timeout=30) as client:
+            try:
+                resp = await client.get(url, params=params)
+                resp.raise_for_status()
+                raw = resp.content
+                data = resp.json()
+                content_hash = hashlib.sha256(raw).hexdigest()
+
+                items = data.get("results", [data]) if isinstance(data, dict) else data
+
+                return AdapterResult(
+                    source_type="market_api",
+                    ticker=ticker,
+                    items=items if isinstance(items, list) else [items],
+                    raw_payload=raw,
+                    content_hash=content_hash,
+                    fetched_at=datetime.utcnow(),
+                )
+            except Exception as e:
+                logger.error(f"Market fetch failed for {ticker}: {e}")
+                return AdapterResult(
+                    source_type="market_api",
+                    ticker=ticker,
+                    items=[],
+                    raw_payload=b"",
+                    content_hash="",
+                    fetched_at=datetime.utcnow(),
+                    error=str(e),
+                )

services/adapters/news_adapter.py

@@ -0,0 +1,61 @@
+"""News API adapter - fetches company-linked headlines and article metadata."""
+import hashlib
+import logging
+from datetime import datetime
+from typing import Any, Dict
+
+import httpx
+
+from .base import AdapterResult, BaseAdapter
+
+logger = logging.getLogger("news_adapter")
+
+
+class NewsApiAdapter(BaseAdapter):
+    """Concrete adapter for a news API provider."""
+
+    def __init__(self, api_key: str = "", base_url: str = ""):
+        self.api_key = api_key
+        self.base_url = base_url
+
+    def source_type(self) -> str:
+        return "news_api"
+
+    async def fetch(self, ticker: str, config: Dict[str, Any]) -> AdapterResult:
+        endpoint = config.get("endpoint", "/v2/everything")
+        url = f"{self.base_url}{endpoint}"
+        params = config.get("params", {})
+        params.setdefault("q", ticker)
+        params.setdefault("sortBy", "publishedAt")
+        params.setdefault("pageSize", 20)
+        if self.api_key:
+            params["apiKey"] = self.api_key
+
+        async with httpx.AsyncClient(timeout=30) as client:
+            try:
+                resp = await client.get(url, params=params)
+                resp.raise_for_status()
+                raw = resp.content
+                data = resp.json()
+                content_hash = hashlib.sha256(raw).hexdigest()
+
+                articles = data.get("articles", [])
+                return AdapterResult(
+                    source_type="news_api",
+                    ticker=ticker,
+                    items=articles,
+                    raw_payload=raw,
+                    content_hash=content_hash,
+                    fetched_at=datetime.utcnow(),
+                )
+            except Exception as e:
+                logger.error(f"News fetch failed for {ticker}: {e}")
+                return AdapterResult(
+                    source_type="news_api",
+                    ticker=ticker,
+                    items=[],
+                    raw_payload=b"",
+                    content_hash="",
+                    fetched_at=datetime.utcnow(),
+                    error=str(e),
+                )