tetra-cli 0.2.0__py3-none-any.whl

tetra_cli/api_client/operations/ai.py

@@ -0,0 +1,278 @@
+"""Pure async operations for the AI chat API.
+
+Covers natural-language querying (RAG + analytics tool calling), embedding
+synchronization, chat history, model discovery, and per-account AI config.
+Each op mirrors the FastAPI contract in ``tetra/api/routes/ai.py`` exactly;
+optional body/query fields that are ``None`` are omitted so server defaults
+apply.
+"""
+from typing import Any
+
+from tetra_cli.api_client import TetraClient
+from tetra_cli.registry import arg, operation, opt
+
+
+@operation(
+    cli="ai status",
+    summary="Check AI feature availability and configured LLM provider.",
+    covers=[("GET", "/api/v1/ai/status")],
+)
+async def ai_status(client: TetraClient) -> dict[str, Any]:
+    """Check AI feature availability.
+
+    Returns whether AI is enabled, which LLM provider/embedding model are
+    configured, and (when enabled) whether the LLM is reachable.
+
+    Args:
+        client: Authenticated TetraClient
+
+    Returns:
+        Dict with ai_enabled, llm_provider, embedding_model, and (if enabled)
+        llm_available.
+    """
+    return await client.get("/api/v1/ai/status")
+
+
+@operation(
+    cli="ai models",
+    summary="List available LLM models for the configured provider.",
+    covers=[("GET", "/api/v1/ai/models")],
+)
+async def list_models(client: TetraClient) -> dict[str, Any]:
+    """List available LLM models.
+
+    For Ollama, this queries the local Ollama API for installed models.
+
+    Args:
+        client: Authenticated TetraClient
+
+    Returns:
+        Dict with 'models' list and the 'provider' name.
+    """
+    return await client.get("/api/v1/ai/models")
+
+
+@operation(
+    cli="ai config",
+    summary="Get the current account's AI configuration.",
+    covers=[("GET", "/api/v1/ai/config")],
+)
+async def get_ai_config(client: TetraClient) -> dict[str, Any]:
+    """Get the current account's AI configuration.
+
+    Args:
+        client: Authenticated TetraClient
+
+    Returns:
+        Dict with 'llm_model' (null when using the server default).
+    """
+    return await client.get("/api/v1/ai/config")
+
+
+@operation(
+    cli="ai set-config",
+    summary="Set or reset the current account's preferred LLM model.",
+    covers=[("PUT", "/api/v1/ai/config")],
+    params={
+        "llm_model": opt(
+            "--llm-model",
+            help="Preferred model name. Omit/clear to reset to server default.",
+            clears=True,
+        ),
+    },
+)
+async def update_ai_config(
+    client: TetraClient,
+    *,
+    llm_model: str | None = None,
+) -> dict[str, Any]:
+    """Update the current account's AI configuration.
+
+    The PUT route always reads the ``llm_model`` field: a non-null value sets
+    the preferred model, ``null`` resets to the server default. The body is
+    therefore always sent with an explicit ``llm_model`` key (defaulting to
+    ``None`` = reset) rather than being omitted.
+
+    Args:
+        client: Authenticated TetraClient
+        llm_model: Preferred model name, or None to reset to the server
+            default.
+
+    Returns:
+        Updated config dict with the effective 'llm_model'.
+    """
+    body: dict[str, Any] = {"llm_model": llm_model}
+    return await client.put("/api/v1/ai/config", json=body)
+
+
+@operation(
+    cli="ai query",
+    summary="Ask a natural-language question about your data (RAG + tools).",
+    covers=[("POST", "/api/v1/ai/query")],
+    params={
+        "query": arg(help="Natural-language question (1-2000 chars)."),
+        "entity_types": opt(
+            "--entity-type", repeatable=True,
+            help="Restrict search to entity types (value | goal | event).",
+        ),
+        "date_start": opt("--date-start", help="Filter start date (YYYY-MM-DD)."),
+        "date_end": opt("--date-end", help="Filter end date (YYYY-MM-DD)."),
+    },
+)
+async def ai_query(
+    client: TetraClient,
+    *,
+    query: str,
+    entity_types: list[str] | None = None,
+    date_start: str | None = None,
+    date_end: str | None = None,
+) -> dict[str, Any]:
+    """Execute a natural-language query against the account's data.
+
+    Mirrors ``AIQueryRequest``: ``query`` is required, the rest are optional
+    filters omitted when not provided. The exchange is persisted to chat
+    history server-side.
+
+    Args:
+        client: Authenticated TetraClient
+        query: Natural-language question (1-2000 characters).
+        entity_types: Optional entity-type filter ('value', 'goal', 'event').
+        date_start: Optional ISO start date (YYYY-MM-DD) for filtering.
+        date_end: Optional ISO end date (YYYY-MM-DD) for filtering.
+
+    Returns:
+        Dict with 'answer', 'sources', 'tools_used', and 'query_id'.
+    """
+    body: dict[str, Any] = {"query": query}
+    if entity_types:
+        body["entity_types"] = entity_types
+    if date_start is not None:
+        body["date_start"] = date_start
+    if date_end is not None:
+        body["date_end"] = date_end
+    return await client.post("/api/v1/ai/query", json=body)
+
+
+@operation(
+    cli="ai query-stream",
+    summary="Ask a question and stream progress via Server-Sent Events.",
+    covers=[("POST", "/api/v1/ai/query/stream")],
+    params={
+        "query": arg(help="Natural-language question (1-2000 chars)."),
+        "entity_types": opt(
+            "--entity-type", repeatable=True,
+            help="Restrict search to entity types (value | goal | event).",
+        ),
+        "date_start": opt("--date-start", help="Filter start date (YYYY-MM-DD)."),
+        "date_end": opt("--date-end", help="Filter end date (YYYY-MM-DD)."),
+    },
+    output="stream",
+)
+async def ai_query_stream(
+    client: TetraClient,
+    *,
+    query: str,
+    entity_types: list[str] | None = None,
+    date_start: str | None = None,
+    date_end: str | None = None,
+) -> dict[str, Any]:
+    """Stream AI query progress via Server-Sent Events.
+
+    Same request shape as :func:`ai_query` (the ``AIQueryRequest`` body); the
+    route returns an SSE stream (status events, then a done/error event)
+    instead of a single JSON response.
+
+    Args:
+        client: Authenticated TetraClient
+        query: Natural-language question (1-2000 characters).
+        entity_types: Optional entity-type filter ('value', 'goal', 'event').
+        date_start: Optional ISO start date (YYYY-MM-DD) for filtering.
+        date_end: Optional ISO end date (YYYY-MM-DD) for filtering.
+
+    Returns:
+        The raw stream payload as returned by the client transport.
+    """
+    body: dict[str, Any] = {"query": query}
+    if entity_types:
+        body["entity_types"] = entity_types
+    if date_start is not None:
+        body["date_start"] = date_start
+    if date_end is not None:
+        body["date_end"] = date_end
+    return await client.post("/api/v1/ai/query/stream", json=body)
+
+
+@operation(
+    cli="ai sync",
+    summary="Re-index values, goals, and events for semantic search.",
+    covers=[("POST", "/api/v1/ai/embeddings/sync")],
+)
+async def sync_embeddings(client: TetraClient) -> dict[str, Any]:
+    """Trigger embedding generation/refresh for the current account.
+
+    Re-indexes all values, goals, and events for semantic search. This is an
+    expensive operation and should be called sparingly. Takes no body.
+
+    Args:
+        client: Authenticated TetraClient
+
+    Returns:
+        Dict with 'entities_indexed' and 'status'.
+    """
+    return await client.post("/api/v1/ai/embeddings/sync")
+
+
+@operation(
+    cli="ai history",
+    summary="Get the current account's AI chat history (chronological).",
+    covers=[("GET", "/api/v1/ai/chat/history")],
+    params={
+        "limit": opt("--limit", min=1, max=200,
+                     help="Max messages to return (1-200, default 50)."),
+        "offset": opt("--offset", min=0,
+                      help="Number of messages to skip (default 0)."),
+    },
+)
+async def get_chat_history(
+    client: TetraClient,
+    *,
+    limit: int | None = None,
+    offset: int | None = None,
+) -> dict[str, Any]:
+    """Get chat history for the current account.
+
+    Returns the most recent messages ordered chronologically (ascending).
+    Query params are omitted when not provided so the server defaults
+    (limit=50, offset=0) apply.
+
+    Args:
+        client: Authenticated TetraClient
+        limit: Max number of messages to return (1-200).
+        offset: Number of messages to skip for pagination.
+
+    Returns:
+        Dict with 'messages' list and 'total' count.
+    """
+    params: dict[str, Any] = {}
+    if limit is not None:
+        params["limit"] = limit
+    if offset is not None:
+        params["offset"] = offset
+    return await client.get("/api/v1/ai/chat/history", params=params or None)
+
+
+@operation(
+    cli="ai clear-history",
+    summary="Delete all AI chat history for the current account.",
+    covers=[("DELETE", "/api/v1/ai/chat/history")],
+)
+async def clear_chat_history(client: TetraClient) -> dict[str, Any]:
+    """Clear all chat history for the current account.
+
+    Args:
+        client: Authenticated TetraClient
+
+    Returns:
+        Dict with 'deleted' count and 'status'.
+    """
+    return await client.delete("/api/v1/ai/chat/history")

tetra_cli/api_client/operations/analysis.py

@@ -0,0 +1,190 @@
+"""Pure async operations for the analysis/export APIs."""
+from typing import Any
+
+from tetra_cli.api_client import TetraClient
+from tetra_cli.registry import operation, opt
+
+
+@operation(
+    cli="analysis time-allocation",
+    summary="Show how time is allocated across values for a date range.",
+    covers=[("GET", "/api/v1/analysis/time-allocation")],
+    params={
+        "start_date": opt("--start-date", help="Start date filter (YYYY-MM-DD)"),
+        "end_date": opt("--end-date", help="End date filter (YYYY-MM-DD)"),
+    },
+)
+async def get_time_allocation(
+    client: TetraClient,
+    *,
+    start_date: str | None = None,
+    end_date: str | None = None,
+) -> dict[str, Any]:
+    """Show how time is allocated across values for a date range.
+
+    Args:
+        client: Authenticated TetraClient
+        start_date: Optional start-date filter (YYYY-MM-DD)
+        end_date: Optional end-date filter (YYYY-MM-DD)
+
+    Returns:
+        Dict with total_hours and a per-value allocation list.
+    """
+    params: dict[str, Any] = {}
+    if start_date:
+        params["start_date"] = start_date
+    if end_date:
+        params["end_date"] = end_date
+    return await client.get("/api/v1/analysis/time-allocation", params=params)
+
+
+@operation(
+    cli="analysis spending-by-goal",
+    summary="Show spending (outcomes) distributed across goals for a date range.",
+    covers=[("GET", "/api/v1/analysis/spending-by-goal")],
+    params={
+        "start_date": opt("--start-date", help="Start date filter (YYYY-MM-DD)"),
+        "end_date": opt("--end-date", help="End date filter (YYYY-MM-DD)"),
+    },
+)
+async def get_spending_by_goal(
+    client: TetraClient,
+    *,
+    start_date: str | None = None,
+    end_date: str | None = None,
+) -> dict[str, Any]:
+    """Show spending (outcomes) distributed across goals for a date range.
+
+    Args:
+        client: Authenticated TetraClient
+        start_date: Optional start-date filter (YYYY-MM-DD)
+        end_date: Optional end-date filter (YYYY-MM-DD)
+
+    Returns:
+        Dict with total_spending and a per-goal spending list.
+    """
+    params: dict[str, Any] = {}
+    if start_date:
+        params["start_date"] = start_date
+    if end_date:
+        params["end_date"] = end_date
+    return await client.get("/api/v1/analysis/spending-by-goal", params=params)
+
+
+@operation(
+    cli="analysis effective-hourly",
+    summary="Calculate effective hourly rate from an income goal and a work value.",
+    covers=[("GET", "/api/v1/analysis/effective-hourly")],
+    params={
+        "income_goal": opt("--income-goal", help="Goal name that tracks income"),
+        "work_value": opt("--work-value", help="Value name that tracks work time"),
+        "start": opt("--start", help="Start date filter (YYYY-MM-DD)"),
+        "end": opt("--end", help="End date filter (YYYY-MM-DD)"),
+    },
+)
+async def get_effective_hourly(
+    client: TetraClient,
+    *,
+    income_goal: str,
+    work_value: str,
+    start: str | None = None,
+    end: str | None = None,
+) -> dict[str, Any]:
+    """Calculate effective hourly rate ($/hour).
+
+    Compares total income (events on ``income_goal``) to total hours
+    (events on ``work_value``) to derive an effective rate. The backend
+    requires both ``income_goal`` and ``work_value`` query params; ``start``
+    and ``end`` are optional date filters.
+
+    Args:
+        client: Authenticated TetraClient
+        income_goal: Goal name that tracks income (required)
+        work_value: Value name that tracks work time (required)
+        start: Optional start-date filter (YYYY-MM-DD)
+        end: Optional end-date filter (YYYY-MM-DD)
+
+    Returns:
+        Dict with total_income, total_hours, and effective_rate.
+    """
+    params: dict[str, Any] = {
+        "income_goal": income_goal,
+        "work_value": work_value,
+    }
+    if start:
+        params["start"] = start
+    if end:
+        params["end"] = end
+    return await client.get("/api/v1/analysis/effective-hourly", params=params)
+
+
+@operation(
+    cli="analysis double-draw-detection",
+    summary="Detect likely double-counted financial draws within a value hierarchy.",
+    covers=[("GET", "/api/v1/analysis/double-draw-detection")],
+    params={
+        "value_uid": opt("--value-uid", help="Parent value UID to scan"),
+        "start": opt("--start", help="Start date (default: 90 days ago)"),
+        "end": opt("--end", help="End date (default: today)"),
+        "min_confidence": opt("--min-confidence", min=0, max=1,
+                              help="Minimum confidence threshold (0-1)"),
+    },
+)
+async def get_double_draw_detection(
+    client: TetraClient,
+    *,
+    value_uid: str,
+    start: str | None = None,
+    end: str | None = None,
+    min_confidence: float | None = None,
+) -> dict[str, Any]:
+    """Detect likely double-counted financial draws within a value hierarchy.
+
+    Scans the parent value (``value_uid``) and its children for lump events
+    on one child that match the sum of itemized events on a sibling child.
+    The backend requires ``value_uid``; ``start``/``end`` default to a
+    90-day window and ``min_confidence`` defaults to 0.5 server-side.
+
+    Args:
+        client: Authenticated TetraClient
+        value_uid: Parent value UID to scan (required)
+        start: Optional start date (YYYY-MM-DD; default 90 days ago)
+        end: Optional end date (YYYY-MM-DD; default today)
+        min_confidence: Optional minimum confidence threshold (0-1)
+
+    Returns:
+        Dict with a ``matches`` list of detected double-draw matches.
+    """
+    params: dict[str, Any] = {"value_uid": value_uid}
+    if start:
+        params["start"] = start
+    if end:
+        params["end"] = end
+    if min_confidence is not None:
+        params["min_confidence"] = min_confidence
+    return await client.get(
+        "/api/v1/analysis/double-draw-detection", params=params,
+    )
+
+
+@operation(
+    cli="data export",
+    summary="Export all account data as a .zip of CSVs (values, goals, events).",
+    covers=[("GET", "/api/v1/data/export")],
+    output="file",
+)
+async def export_data(client: TetraClient) -> tuple[bytes, str]:
+    """Export all account data as a downloadable zip archive.
+
+    The export endpoint returns a ``.zip`` containing ``values.csv``,
+    ``goals.csv``, and ``events.csv`` (the same archive ``data import``
+    accepts), so the op downloads the raw bytes rather than JSON-decoding
+    them. Over MCP the bytes are returned base64-encoded.
+
+    Args:
+        client: Authenticated TetraClient.
+
+    Returns:
+        A ``(content_bytes, filename)`` tuple for the file generator to write.
+    """
+    return await client.download("/api/v1/data/export")

tetra_cli/api_client/operations/api_keys.py

@@ -0,0 +1,145 @@
+"""Pure async operations for the API-key management API.
+
+These ops mirror ``backend/tetra/api/routes/api_keys.py``. API keys are the
+agent's own credentials: an account creates a key (the raw token is shown
+ONCE), lists its keys, updates scopes/avatar, and revokes keys. Webhook
+registration on a key lives in ``webhooks.py`` (it shares the PATCH route but
+is exposed as its own dedicated ops); the ``update`` op here handles the
+scopes/avatar path of that same PATCH.
+"""
+from typing import Any
+
+from tetra_cli.api_client import TetraClient
+from tetra_cli.registry import arg, operation, opt
+
+
+@operation(
+    cli="api-keys list",
+    summary="List all API keys for the current account.",
+    covers=[("GET", "/api/v1/api-keys/")],
+)
+async def list_api_keys(client: TetraClient) -> list[dict[str, Any]]:
+    """List all API keys for the current account.
+
+    The raw token is never returned here — it is only shown once at
+    creation time. Each entry exposes the prefix, scopes, avatar, activity
+    timestamps, and whether a webhook is configured.
+
+    Args:
+        client: Authenticated TetraClient
+
+    Returns:
+        List of API-key dicts (without raw tokens).
+    """
+    return await client.get("/api/v1/api-keys/")
+
+
+@operation(
+    cli="api-keys create",
+    summary="Create a new API key (raw token is shown only once).",
+    covers=[("POST", "/api/v1/api-keys/")],
+    params={
+        "name": arg(help="Human-readable key name (max 100 chars)."),
+        "scopes": opt("--scope", repeatable=True,
+                      help="Permission scope (repeatable; at least one required)."),
+        "expires_at": opt("--expires-at",
+                          help="ISO-8601 expiry timestamp (UTC). Omit for no expiry."),
+        "avatar": opt("--avatar", json=True,
+                      help="Avatar configuration as a JSON dict."),
+    },
+)
+async def create_api_key(
+    client: TetraClient,
+    *,
+    name: str,
+    scopes: list[str],
+    expires_at: str | None = None,
+    avatar: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Create a new API key.
+
+    The response includes ``raw_token`` exactly once — it cannot be
+    retrieved again, so the caller must capture it immediately. Only fields
+    that are provided are sent; ``expires_at`` and ``avatar`` are omitted
+    when None so the API applies its defaults (no expiry / no avatar).
+
+    Args:
+        client: Authenticated TetraClient
+        name: Human-readable key name (required, max 100 chars)
+        scopes: Permission scopes (at least one required)
+        expires_at: Optional ISO-8601 UTC expiry timestamp
+        avatar: Optional avatar configuration dict
+
+    Returns:
+        Dict with ``key`` (the API-key metadata) and ``raw_token``.
+    """
+    body: dict[str, Any] = {"name": name, "scopes": scopes}
+    if expires_at is not None:
+        body["expires_at"] = expires_at
+    if avatar is not None:
+        body["avatar"] = avatar
+    return await client.post("/api/v1/api-keys/", json=body)
+
+
+@operation(
+    cli="api-keys update",
+    summary="Update an API key's scopes and/or avatar.",
+    covers=[("PATCH", "/api/v1/api-keys/{uid}")],
+    params={
+        "uid": arg(help="API key UID."),
+        "scopes": opt("--scope", repeatable=True,
+                      help="Permission scope (repeatable; replaces all scopes)."),
+        "avatar": opt("--avatar", json=True,
+                      help="Avatar configuration as a JSON dict (pass to clear handled separately)."),
+    },
+)
+async def update_api_key(
+    client: TetraClient,
+    *,
+    uid: str,
+    scopes: list[str] | None = None,
+    avatar: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Update an API key's scopes and/or avatar.
+
+    The backend keys off ``model_fields_set``: only fields present in the
+    request body are applied, and a missing field is left untouched. This op
+    therefore only includes ``scopes`` / ``avatar`` when the caller actually
+    passed them — a scopes-only update never disturbs the avatar (or a
+    configured webhook), and vice-versa. Webhook registration is handled by
+    the dedicated ops in ``webhooks.py``.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: API key UID
+        scopes: New scope list (replaces all scopes; cannot be null)
+        avatar: New avatar configuration dict
+
+    Returns:
+        Dict ``{"updated": True}`` on success.
+    """
+    body: dict[str, Any] = {}
+    if scopes is not None:
+        body["scopes"] = scopes
+    if avatar is not None:
+        body["avatar"] = avatar
+    return await client.patch(f"/api/v1/api-keys/{uid}", json=body)
+
+
+@operation(
+    cli="api-keys revoke",
+    summary="Revoke (deactivate) an API key.",
+    covers=[("DELETE", "/api/v1/api-keys/{uid}")],
+    params={"uid": arg(help="API key UID to revoke.")},
+)
+async def revoke_api_key(client: TetraClient, uid: str) -> dict[str, Any]:
+    """Revoke an API key, immediately deactivating it.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: API key UID to revoke
+
+    Returns:
+        Dict ``{"revoked": True}`` on success.
+    """
+    return await client.delete(f"/api/v1/api-keys/{uid}")