citadel-predict 0.1.0__py3-none-any.whl

citadel_predict/__init__.py

@@ -0,0 +1,30 @@
+"""
+citadel-predict: Developer client for AI agent pre-execution cost prediction.
+"""
+
+from .client import CitadelClient, predict_cost
+from .config import resolve_api_key, resolve_api_url
+from .errors import (
+    CitadelAuthError,
+    CitadelBadRequestError,
+    CitadelError,
+    CitadelNetworkError,
+    CitadelRateLimitError,
+    CitadelServerError,
+    CitadelValidationError,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "predict_cost",
+    "CitadelClient",
+    "resolve_api_key",
+    "resolve_api_url",
+    "CitadelError",
+    "CitadelAuthError",
+    "CitadelRateLimitError",
+    "CitadelValidationError",
+    "CitadelBadRequestError",
+    "CitadelServerError",
+    "CitadelNetworkError",
+]

citadel_predict/cli.py

@@ -0,0 +1,179 @@
+"""
+Command-line interface for Citadel Predict.
+
+Usage:
+    citadel-predict --task "Research 3 competitors" --tools web_search,draft_document
+"""
+
+import argparse
+import json
+import sys
+from typing import Optional, Sequence
+
+from .client import CitadelClient
+from .errors import (
+    CitadelAuthError,
+    CitadelBadRequestError,
+    CitadelError,
+    CitadelNetworkError,
+    CitadelRateLimitError,
+    CitadelServerError,
+    CitadelValidationError,
+)
+
+EXIT_SUCCESS = 0
+EXIT_GENERAL_ERROR = 1
+EXIT_VALIDATION_ERROR = 2
+EXIT_AUTH_ERROR = 3
+EXIT_RATE_LIMIT_ERROR = 4
+EXIT_SERVER_ERROR = 5
+EXIT_NETWORK_ERROR = 6
+
+
+def parse_args(args: Optional[Sequence[str]] = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="citadel-predict",
+        description="Predict AI agent token budgets and costs before execution.",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    parser.add_argument(
+        "--task",
+        "-t",
+        type=str,
+        help="Task description string for the agent run.",
+    )
+    parser.add_argument(
+        "positional_task",
+        nargs="?",
+        type=str,
+        help="Task description (if --task is not passed).",
+    )
+    parser.add_argument(
+        "--tools",
+        type=str,
+        default="",
+        help="Comma-separated list of tool names (e.g. 'web_search,fetch_url,draft_document').",
+    )
+    parser.add_argument(
+        "--model-id",
+        "-m",
+        type=str,
+        default="claude-sonnet",
+        help="Model calibration identifier.",
+    )
+    parser.add_argument(
+        "--api-key",
+        "-k",
+        type=str,
+        default=None,
+        help="Citadel API key (overrides CITADEL_API_KEY env var and config file).",
+    )
+    parser.add_argument(
+        "--api-url",
+        "-u",
+        type=str,
+        default=None,
+        help="Citadel API base URL (default: http://localhost:8000 or CITADEL_API_URL).",
+    )
+    parser.add_argument(
+        "--timeout",
+        type=float,
+        default=10.0,
+        help="Request timeout in seconds.",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output raw JSON instead of formatted text.",
+    )
+    return parser.parse_args(args)
+
+
+def format_pretty_output(result: dict) -> str:
+    lines = [
+        "=" * 50,
+        "  CITADEL PREDICT — TOKEN BUDGET ESTIMATE",
+        "=" * 50,
+        f"Model:           {result.get('model_id')}",
+        f"Expected Tokens: {result.get('expected_tokens', 0):,} tokens",
+        f"Predicted Range: {result.get('low_tokens', 0):,} – {result.get('high_tokens', 0):,} tokens",
+        f"Confidence:      {result.get('confidence', 'unknown').upper()}",
+    ]
+
+    if result.get("out_of_distribution"):
+        lines.append(f"OOD Warning:     YES ({', '.join(result.get('ood_reasons', []))})")
+    else:
+        lines.append("OOD Warning:     No (In-Distribution)")
+
+    factors = result.get("driving_factors", [])
+    if factors:
+        lines.append("Driving Factors:")
+        for factor in factors:
+            lines.append(f"  • {factor}")
+
+    lines.append("=" * 50)
+    return "\n".join(lines)
+
+
+def main(args: Optional[Sequence[str]] = None) -> int:
+    parsed = parse_args(args)
+
+    task = parsed.task or parsed.positional_task
+    if not task:
+        sys.stderr.write("Error: Task description is required. Use --task '...' or pass as argument.\n")
+        return EXIT_VALIDATION_ERROR
+
+    tools = [t.strip() for t in parsed.tools.split(",") if t.strip()] if parsed.tools else []
+
+    try:
+        with CitadelClient(
+            api_key=parsed.api_key,
+            base_url=parsed.api_url,
+            timeout=parsed.timeout,
+        ) as client:
+            result = client.predict(
+                task_text=task,
+                tools=tools,
+                model_id=parsed.model_id,
+            )
+
+        if parsed.json:
+            print(json.dumps(result, indent=2))
+        else:
+            print(format_pretty_output(result))
+        return EXIT_SUCCESS
+
+    except CitadelAuthError as exc:
+        sys.stderr.write(f"Authentication Error: {exc.message}\n")
+        return EXIT_AUTH_ERROR
+
+    except CitadelRateLimitError as exc:
+        msg = f"Rate Limit Error: {exc.message}"
+        if exc.retry_after is not None:
+            msg += f" (Retry after {exc.retry_after}s)"
+        sys.stderr.write(f"{msg}\n")
+        return EXIT_RATE_LIMIT_ERROR
+
+    except (CitadelValidationError, CitadelBadRequestError) as exc:
+        sys.stderr.write(f"Validation Error: {exc.message}\n")
+        return EXIT_VALIDATION_ERROR
+
+    except CitadelServerError as exc:
+        sys.stderr.write(f"Server Error: {exc.message}\n")
+        return EXIT_SERVER_ERROR
+
+    except CitadelNetworkError as exc:
+        sys.stderr.write(f"Network Error: {exc.message}\n")
+        return EXIT_NETWORK_ERROR
+
+    except CitadelError as exc:
+        sys.stderr.write(f"Citadel Error: {exc.message}\n")
+        return EXIT_GENERAL_ERROR
+
+    except Exception as exc:
+        sys.stderr.write(f"Unexpected Error: {exc}\n")
+        return EXIT_GENERAL_ERROR
+
+
+if __name__ == "__main__":
+    sys.exit(main())

citadel_predict/client.py

@@ -0,0 +1,243 @@
+"""
+HTTP client for the Citadel Predict API.
+"""
+
+from pathlib import Path
+from typing import Any, Optional
+
+import httpx
+
+from .config import resolve_api_key, resolve_api_url
+from .errors import (
+    CitadelAuthError,
+    CitadelBadRequestError,
+    CitadelError,
+    CitadelNetworkError,
+    CitadelRateLimitError,
+    CitadelServerError,
+    CitadelValidationError,
+)
+
+
+class CitadelClient:
+    """
+    Client for interacting with the Citadel Predict API.
+
+    Handles authentication, error mapping, timeouts, and request dispatch.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 10.0,
+        config_path: Optional[Path] = None,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        self.api_key = resolve_api_key(api_key, config_path=config_path)
+        self.base_url = resolve_api_url(base_url, config_path=config_path)
+        self.timeout = timeout
+        self._custom_client = http_client is not None
+        self._client = http_client or httpx.Client(timeout=self.timeout)
+
+    def _get_headers(self) -> dict[str, str]:
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": "citadel-predict-python/0.1.0",
+        }
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        return headers
+
+    def _handle_error_response(self, response: httpx.Response) -> None:
+        status_code = response.status_code
+        try:
+            data = response.json()
+            detail = data.get("detail")
+            if isinstance(detail, list):
+                # Pydantic validation error list format
+                msg = "; ".join(
+                    f"{err.get('loc', [])}: {err.get('msg', '')}" if isinstance(err, dict) else str(err)
+                    for err in detail
+                )
+            elif detail:
+                msg = str(detail)
+            else:
+                msg = response.text or f"HTTP error {status_code}"
+        except Exception:
+            data = None
+            msg = response.text or f"HTTP error {status_code}"
+
+        if status_code == 401:
+            raise CitadelAuthError(
+                message=(
+                    f"Authentication failed ({msg}). "
+                    "Ensure your Citadel API key is set via api_key argument, "
+                    "CITADEL_API_KEY environment variable, or ~/.citadel/config.toml"
+                ),
+                status_code=401,
+                response_data=data,
+            )
+
+        if status_code == 429:
+            retry_after: Optional[int] = None
+            raw_retry = response.headers.get("Retry-After")
+            if raw_retry and raw_retry.isdigit():
+                retry_after = int(raw_retry)
+            raise CitadelRateLimitError(
+                message=f"Rate limit exceeded: {msg}",
+                status_code=429,
+                response_data=data,
+                retry_after=retry_after,
+            )
+
+        if status_code == 422:
+            raise CitadelValidationError(
+                message=f"Validation error: {msg}",
+                status_code=422,
+                response_data=data,
+            )
+
+        if status_code == 400:
+            raise CitadelBadRequestError(
+                message=f"Bad request: {msg}",
+                status_code=400,
+                response_data=data,
+            )
+
+        if 500 <= status_code < 600:
+            raise CitadelServerError(
+                message=f"Server error ({status_code}): {msg}",
+                status_code=status_code,
+                response_data=data,
+            )
+
+        raise CitadelError(
+            message=f"API request failed with status {status_code}: {msg}",
+            status_code=status_code,
+            response_data=data,
+        )
+
+    def predict(
+        self,
+        task_text: str,
+        tools: Optional[list[str]] = None,
+        num_tools: Optional[int] = None,
+        model_id: str = "claude-sonnet",
+    ) -> dict[str, Any]:
+        """
+        Predict token budget and cost ranges for a given agent task description and tools.
+
+        Parameters:
+            task_text: Natural language task description (1-4000 chars).
+            tools: List of tool names available to the agent.
+            num_tools: Optional integer count (tools list takes precedence if provided).
+            model_id: Model calibration identifier (default: 'claude-sonnet').
+
+        Returns:
+            Dictionary matching the API response schema exactly:
+            {
+                "model_id": "claude-sonnet",
+                "low_tokens": int,
+                "expected_tokens": int,
+                "high_tokens": int,
+                "driving_factors": list[str],
+                "features": dict,
+                "confidence": str,
+                "out_of_distribution": bool,
+                "ood_reasons": list[str]
+            }
+        """
+        tool_list = list(tools) if tools is not None else []
+        url = f"{self.base_url}/api/predict"
+        payload = {
+            "task_text": task_text,
+            "tools": tool_list,
+            "model_id": model_id,
+        }
+
+        try:
+            response = self._client.post(
+                url,
+                json=payload,
+                headers=self._get_headers(),
+            )
+        except (httpx.TimeoutException, httpx.NetworkError, httpx.RequestError) as exc:
+            raise CitadelNetworkError(
+                message=f"Network error communicating with Citadel API at {url}: {exc}",
+                cause=exc,
+            ) from exc
+
+        if response.status_code != 200:
+            self._handle_error_response(response)
+
+        try:
+            return response.json()
+        except Exception as exc:
+            raise CitadelServerError(
+                message="Failed to parse JSON response from Citadel Predict API",
+                status_code=response.status_code,
+            ) from exc
+
+    def health(self) -> dict[str, Any]:
+        """Check health status and supported models on the Citadel Predict API."""
+        url = f"{self.base_url}/api/health"
+        try:
+            response = self._client.get(url, headers=self._get_headers())
+        except (httpx.TimeoutException, httpx.NetworkError, httpx.RequestError) as exc:
+            raise CitadelNetworkError(
+                message=f"Network error communicating with Citadel API at {url}: {exc}",
+                cause=exc,
+            ) from exc
+
+        if response.status_code != 200:
+            self._handle_error_response(response)
+
+        return response.json()
+
+    def close(self) -> None:
+        """Close the underlying HTTP client session."""
+        if not self._custom_client:
+            self._client.close()
+
+    def __enter__(self) -> "CitadelClient":
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        self.close()
+
+
+def predict_cost(
+    task_text: str,
+    tools: Optional[list[str]] = None,
+    num_tools: Optional[int] = None,
+    model_id: str = "claude-sonnet",
+    api_key: Optional[str] = None,
+    api_url: Optional[str] = None,
+    timeout: Optional[float] = None,
+    **kwargs: Any,
+) -> dict[str, Any]:
+    """
+    Convenience function to predict token budget and cost ranges for an agent run.
+
+    Example:
+        >>> from citadel_predict import predict_cost
+        >>> result = predict_cost(
+        ...     task_text="Research competitor pricing and draft report",
+        ...     tools=["web_search", "draft_document"]
+        ... )
+        >>> print(result["expected_tokens"])
+    """
+    client_timeout = timeout if timeout is not None else 10.0
+    with CitadelClient(
+        api_key=api_key,
+        base_url=api_url,
+        timeout=client_timeout,
+    ) as client:
+        return client.predict(
+            task_text=task_text,
+            tools=tools,
+            num_tools=num_tools,
+            model_id=model_id,
+        )

citadel_predict/config.py

@@ -0,0 +1,115 @@
+"""
+Configuration resolver for Citadel Predict.
+
+Resolution priority:
+1. Explicit function / CLI parameter
+2. Environment variables (`CITADEL_API_KEY`, `CITADEL_API_URL`)
+3. Config file (`~/.citadel/config.toml`)
+"""
+
+import os
+from pathlib import Path
+from typing import Any, Optional
+
+try:
+    import tomllib
+except ImportError:  # pragma: no cover
+    try:
+        import tomli as tomllib  # type: ignore[no-redef]
+    except ImportError:
+        tomllib = None  # type: ignore[assignment]
+
+
+DEFAULT_API_URL = "http://localhost:8000"
+DEFAULT_CONFIG_PATH = Path.home() / ".citadel" / "config.toml"
+
+
+def load_config_file(config_path: Optional[Path] = None) -> dict[str, Any]:
+    """
+    Load configuration from ~/.citadel/config.toml if present.
+    Supports top-level keys or keys under a [default] section.
+    """
+    path = config_path or DEFAULT_CONFIG_PATH
+    if not path.exists() or not path.is_file():
+        return {}
+
+    try:
+        if tomllib is not None:
+            with open(path, "rb") as f:
+                data = tomllib.load(f)
+        else:
+            # Fallback simple line-by-line parser for key = "value" pairs
+            data = {}
+            with open(path, "r", encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    if not line or line.startswith("#") or line.startswith("["):
+                        continue
+                    if "=" in line:
+                        k, v = line.split("=", 1)
+                        k = k.strip()
+                        v = v.strip().strip("\"'")
+                        data[k] = v
+
+        # If data has a [default] table, merge it
+        if "default" in data and isinstance(data["default"], dict):
+            merged = dict(data["default"])
+            for k, v in data.items():
+                if k != "default":
+                    merged[k] = v
+            return merged
+        return data
+    except Exception:
+        # If config file is corrupted or unreadable, ignore silently and return empty dict
+        return {}
+
+
+def resolve_api_key(
+    explicit_key: Optional[str] = None,
+    config_path: Optional[Path] = None,
+) -> Optional[str]:
+    """
+    Resolve API key according to priority:
+    1. Explicit argument
+    2. CITADEL_API_KEY environment variable (or legacy API_KEY)
+    3. api_key in ~/.citadel/config.toml
+    """
+    if explicit_key:
+        return explicit_key.strip()
+
+    env_key = os.environ.get("CITADEL_API_KEY") or os.environ.get("API_KEY")
+    if env_key:
+        return env_key.strip()
+
+    file_config = load_config_file(config_path)
+    file_key = file_config.get("api_key")
+    if file_key and isinstance(file_key, str):
+        return file_key.strip()
+
+    return None
+
+
+def resolve_api_url(
+    explicit_url: Optional[str] = None,
+    config_path: Optional[Path] = None,
+) -> str:
+    """
+    Resolve base API URL according to priority:
+    1. Explicit argument
+    2. CITADEL_API_URL environment variable
+    3. api_url in ~/.citadel/config.toml
+    4. Default: http://localhost:8000
+    """
+    if explicit_url:
+        return explicit_url.rstrip("/")
+
+    env_url = os.environ.get("CITADEL_API_URL")
+    if env_url:
+        return env_url.rstrip("/")
+
+    file_config = load_config_file(config_path)
+    file_url = file_config.get("api_url")
+    if file_url and isinstance(file_url, str):
+        return file_url.rstrip("/")
+
+    return DEFAULT_API_URL

citadel_predict/errors.py

@@ -0,0 +1,109 @@
+"""
+Exception hierarchy for citadel-predict.
+"""
+
+from typing import Any, Optional
+
+
+class CitadelError(Exception):
+    """Base exception for all Citadel Predict client errors."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        response_data: Optional[Any] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.response_data = response_data
+
+    def __str__(self) -> str:
+        if self.status_code:
+            return f"[{self.status_code}] {self.message}"
+        return self.message
+
+
+class CitadelAuthError(CitadelError):
+    """Raised when authentication fails (HTTP 401) or API key is missing/invalid."""
+
+    def __init__(
+        self,
+        message: str = (
+            "Authentication failed: Missing or invalid Citadel API key. "
+            "Set CITADEL_API_KEY environment variable, pass api_key='...', "
+            "or configure api_key in ~/.citadel/config.toml"
+        ),
+        status_code: int = 401,
+        response_data: Optional[Any] = None,
+    ) -> None:
+        super().__init__(message, status_code=status_code, response_data=response_data)
+
+
+class CitadelRateLimitError(CitadelError):
+    """Raised when API rate limits are exceeded (HTTP 429)."""
+
+    def __init__(
+        self,
+        message: str = "Rate limit exceeded. Please back off and retry later.",
+        status_code: int = 429,
+        response_data: Optional[Any] = None,
+        retry_after: Optional[int] = None,
+    ) -> None:
+        super().__init__(message, status_code=status_code, response_data=response_data)
+        self.retry_after = retry_after
+
+    def __str__(self) -> str:
+        base = f"[{self.status_code}] {self.message}"
+        if self.retry_after is not None:
+            base += f" (Retry-After: {self.retry_after}s)"
+        return base
+
+
+class CitadelValidationError(CitadelError):
+    """Raised when the server rejects invalid request data (HTTP 422)."""
+
+    def __init__(
+        self,
+        message: str = "Request validation failed. Check task_text and tools formatting.",
+        status_code: int = 422,
+        response_data: Optional[Any] = None,
+    ) -> None:
+        super().__init__(message, status_code=status_code, response_data=response_data)
+
+
+class CitadelBadRequestError(CitadelError):
+    """Raised when the request is bad or model_id is unsupported (HTTP 400)."""
+
+    def __init__(
+        self,
+        message: str = "Bad request. Unsupported model or invalid payload.",
+        status_code: int = 400,
+        response_data: Optional[Any] = None,
+    ) -> None:
+        super().__init__(message, status_code=status_code, response_data=response_data)
+
+
+class CitadelServerError(CitadelError):
+    """Raised when the Citadel API server returns a 5xx error."""
+
+    def __init__(
+        self,
+        message: str = "Citadel Predict server error. Please try again later.",
+        status_code: int = 500,
+        response_data: Optional[Any] = None,
+    ) -> None:
+        super().__init__(message, status_code=status_code, response_data=response_data)
+
+
+class CitadelNetworkError(CitadelError):
+    """Raised when a network connection fails or requests time out."""
+
+    def __init__(
+        self,
+        message: str = "Network error: Failed to connect to Citadel Predict API.",
+        cause: Optional[Exception] = None,
+    ) -> None:
+        super().__init__(message)
+        self.cause = cause

citadel_predict/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561.

citadel_predict-0.1.0.dist-info/METADATA

@@ -0,0 +1,215 @@
+Metadata-Version: 2.5
+Name: citadel-predict
+Version: 0.1.0
+Summary: Pre-execution LLM token budget and cost prediction client for AI agents
+Author: Citadel Predict Team
+License: MIT
+Keywords: agent,ai,budget,cost-estimation,governance,guardrails,llm,tokens
+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 :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# citadel-predict
+
+[![PyPI Version](https://img.shields.io/pypi/v/citadel-predict.svg)](https://pypi.org/project/citadel-predict/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/citadel-predict.svg)](https://pypi.org/project/citadel-predict/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+**Pre-execution token budget and cost predictor client for AI agents.**
+
+`citadel-predict` is a lightweight, pure HTTP Python client and CLI for the Citadel Predict API. It allows developers, CI pipelines, and autonomous agent loops to estimate LLM token consumption and cost ranges *before* initiating expensive agent runs.
+
+---
+
+## Installation
+
+```bash
+pip install citadel-predict
+```
+
+---
+
+## Quickstart (3 Lines of Code)
+
+```python
+from citadel_predict import predict_cost
+
+result = predict_cost(
+    task_text="Research competitor pricing across 3 sources and draft report",
+    tools=["web_search", "draft_document"]
+)
+
+print(f"Expected: {result['expected_tokens']:,} tokens (Range: {result['low_tokens']:,} – {result['high_tokens']:,})")
+```
+
+Output:
+```text
+Expected: 3,200 tokens (Range: 1,500 – 5,800)
+```
+
+---
+
+## CLI Usage
+
+`citadel-predict` includes a full-featured CLI for terminal workflows and CI/CD cost checks:
+
+```bash
+# Pretty terminal card output
+citadel-predict --task "Audit repository and write migration guide" --tools list_files,read_document,draft_document
+
+# Scripting / CI mode (JSON output)
+citadel-predict --task "Calculate statistical metrics" --tools calculator --json
+
+# Override API key or URL
+citadel-predict --task "..." --api-key "cp_live_12345" --api-url "https://api.citadel.dev"
+```
+
+### CLI Exit Codes
+- `0`: Success
+- `2`: Validation Error / Bad Request (HTTP 400 / 422 or missing task)
+- `3`: Authentication Failure (HTTP 401)
+- `4`: Rate Limit Exceeded (HTTP 429)
+- `5`: Server Error (HTTP 5xx)
+- `6`: Network / Timeout Error
+
+---
+
+## Real Agent Integration: Pre-Execution Guardrails
+
+Existing agent governance tools (e.g., Portkey, Langfuse, LiteLLM) are **reactive**—they record costs during or after an execution. `citadel-predict` is **predictive**—enabling pre-flight budget checks and dynamic routing before running reasoning loops.
+
+### LangGraph / CrewAI Pre-Flight Cost Guardrail Example
+
+```python
+from typing import TypedDict, List
+from citadel_predict import predict_cost, CitadelError
+
+class AgentState(TypedDict):
+    task: str
+    tools: List[str]
+    budget_tokens: int
+    approved: bool
+
+def pre_flight_budget_guardrail(state: AgentState) -> AgentState:
+    """
+    Evaluates token budget before dispatching tools or multi-agent loops.
+    """
+    try:
+        prediction = predict_cost(
+            task_text=state["task"],
+            tools=state["tools"],
+            model_id="claude-sonnet"
+        )
+    except CitadelError as e:
+        print(f"Cost prediction unavailable: {e}. Falling back to default budget.")
+        return state
+
+    expected = prediction["expected_tokens"]
+    high = prediction["high_tokens"]
+    is_ood = prediction["out_of_distribution"]
+
+    print(f"Pre-flight estimate: ~{expected:,} tokens (Upper bound: {high:,})")
+    if is_ood:
+        print(f"Warning: Out-of-Distribution task ({prediction['ood_reasons']})")
+
+    # Guardrail Policy: Escalate if upper bound exceeds budget
+    if high > state["budget_tokens"]:
+        print(f"[BLOCKED] High-estimate ({high:,}) exceeds budget ({state['budget_tokens']:,})")
+        # In a real agent: switch to smaller model, ask human for approval, or prune tool access
+        state["approved"] = False
+    else:
+        state["approved"] = True
+
+    return state
+
+# Example usage in workflow
+initial_state: AgentState = {
+    "task": "Perform exhaustive market research across 20 industry filings",
+    "tools": ["web_search", "fetch_url", "draft_document"],
+    "budget_tokens": 10000,
+    "approved": False
+}
+
+state = pre_flight_budget_guardrail(initial_state)
+if not state["approved"]:
+    print("Action required: Human-in-the-loop approval or task reformulation needed.")
+```
+
+---
+
+## Authentication & Configuration
+
+The client resolves your API key and base URL according to the following priority:
+
+1. **Explicit argument**: `predict_cost(..., api_key="...", api_url="...")` or CLI `--api-key` / `--api-url`
+2. **Environment variables**: `CITADEL_API_KEY` and `CITADEL_API_URL`
+3. **Configuration file**: `~/.citadel/config.toml`
+
+### Example `~/.citadel/config.toml`
+```toml
+api_key = "cp_live_your_api_key_here"
+api_url = "https://api.citadel.dev"
+```
+
+---
+
+## Error Handling
+
+`citadel-predict` surfaces typed, catchable exceptions:
+
+```python
+from citadel_predict import (
+    predict_cost,
+    CitadelAuthError,
+    CitadelRateLimitError,
+    CitadelValidationError,
+    CitadelServerError,
+    CitadelNetworkError,
+)
+
+try:
+    result = predict_cost("Analyze dataset", tools=["calculator"])
+except CitadelAuthError:
+    # 401: Missing or invalid API key
+    ...
+except CitadelRateLimitError as e:
+    # 429: Rate limited; check e.retry_after
+    print(f"Retry after {e.retry_after} seconds")
+except CitadelValidationError as e:
+    # 422: Input validation bounds exceeded (e.g. task > 4000 chars)
+    ...
+except CitadelNetworkError as e:
+    # Timeout or connection failure
+    ...
+```
+
+---
+
+## Honest Limitations
+
+`citadel-predict` is a thin client wrapping the hosted calibration model. It directly inherits the current system characteristics:
+
+1. **Single-Model Calibration**: Calibration is currently tuned specifically for **Claude Sonnet** (`claude-sonnet`). Future releases will introduce multi-model support via `model_id`.
+2. **Calibration Dataset Scale**: Calibrated on $N=20$ diverse task archetypes across 80 benchmarked runs.
+3. **Synthetic Tool Sizing**: Ground-truth data was collected using deterministic mock tool outputs with representative context expansion. Real-world tools with unbounded payload returns (e.g., massive scraped DOMs) may exhibit higher variance.
+4. **Pre-execution Estimation**: Token predictions represent calibrated statistical ranges $[low, expected, high]$, not runtime guarantees against infinite loops or divergent agent reasoning.
+
+---
+
+## License
+
+MIT

citadel_predict-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+citadel_predict/__init__.py,sha256=wWIouGF5_qoLlC1abmINIPMPs8CfxqXlUwLw2yf_OUM,694
+citadel_predict/cli.py,sha256=axeoyd-G_i4COPVPce7f6z8Utx-kUzapNJPmZSabZlA,5166
+citadel_predict/client.py,sha256=JprRpeRpJI6gjqA3sk18F_CxP8tFc4nX7RKyn6eXM9U,8038
+citadel_predict/config.py,sha256=P7eWXpJpjwhMSdmOlFThEtj3q7bxeE5NZ4jebgUpzt8,3431
+citadel_predict/errors.py,sha256=0k7sY5doKBw99_BB8sYgMGM6x_7I3Zr4aXHPfT4zxfU,3495
+citadel_predict/py.typed,sha256=bWew9mHgMy8LqMu7RuqQXFXLBxh2CRx0dUbSx-3wE48,27
+citadel_predict-0.1.0.dist-info/METADATA,sha256=yvoo-xlKDTBRnlynovI3kWxg12-hwrrjgadHzvDX5VY,7232
+citadel_predict-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+citadel_predict-0.1.0.dist-info/entry_points.txt,sha256=wpobzRsGxw0Tv6f0mWFlpH7OEXpOM7D2zyed6L60GXI,61
+citadel_predict-0.1.0.dist-info/RECORD,,

citadel_predict-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

citadel_predict-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+citadel-predict = citadel_predict.cli:main