tetra-cli 0.2.0__tar.gz → 0.5.0__tar.gz

{tetra_cli-0.2.0 → tetra_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tetra-cli
-Version: 0.2.0
+Version: 0.5.0
 Summary: Standalone CLI/agent client for the Tetra API (no backend).
 Project-URL: Homepage, https://tetraoptum.com
 Requires-Python: >=3.11

{tetra_cli-0.2.0 → tetra_cli-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tetra-cli"
-version = "0.2.0"
+version = "0.5.0"
 description = "Standalone CLI/agent client for the Tetra API (no backend)."
 readme = "README.md"
 requires-python = ">=3.11"

{tetra_cli-0.2.0 → tetra_cli-0.5.0}/tests/test_smoke.py

@@ -3,4 +3,4 @@ import tetra_cli
 
 
 def test_version():
-    assert tetra_cli.__version__ == "0.1.0"
+    assert tetra_cli.__version__ == "0.5.0"

{tetra_cli-0.2.0 → tetra_cli-0.5.0}/tetra_cli/__init__.py

@@ -3,4 +3,4 @@
 Speaks only HTTP to a remote Tetra API with a bearer token. Contains NO
 backend server code (no models, routes, services, ORM). Safe to distribute.
 """
-__version__ = "0.1.0"
+__version__ = "0.5.0"

{tetra_cli-0.2.0 → tetra_cli-0.5.0}/tetra_cli/api_client/operations/capacity.py

@@ -61,24 +61,31 @@ async def get_group_capacity(
 
 @operation(
     cli="capacity purchase-slot",
-    summary="Buy the next credit-purchased active capacity slot.",
+    summary="Buy the next credit-purchased active capacity slots.",
     covers=[("POST", "/api/v1/capacity/purchase-slot")],
+    params={"quantity": arg(help="How many slots to buy (default 1)")},
 )
-async def purchase_capacity_slot(client: TetraClient) -> dict[str, Any]:
-    """Buy the next credit-purchased active slot (escalating credit cost).
+async def purchase_capacity_slot(
+    client: TetraClient, quantity: int = 1,
+) -> dict[str, Any]:
+    """Buy the next ``quantity`` credit-purchased active slots.
 
-    The endpoint takes no body — the next slot's cost and the caller's
-    eligibility are derived server-side from the account state.
+    Per-slot cost escalates and the purchase is all-or-nothing: the summed
+    cost is debited in one transaction or the call fails without buying any.
 
     Args:
         client: Authenticated TetraClient
+        quantity: How many slots to buy (default 1)
 
     Returns:
-        Updated capacity dict reflecting the new ``purchased_slots`` and
-        ``next_slot_cost``.
+        Updated capacity dict reflecting the new ``purchased_slots``,
+        ``next_slot_cost``, and ``slot_cost_paid`` (total credits debited).
 
     Raises:
-        TetraClientError: 400 ``insufficient_credits`` if the balance is too
-            low; 400 ``unlimited_capacity`` for Pro/comped accounts.
+        TetraClientError: 400 ``insufficient_credits`` if the balance can't
+            cover the summed cost; 400 ``free_cap_reached`` when a free
+            account would end past the slot hard cap.
     """
-    return await client.post("/api/v1/capacity/purchase-slot")
+    return await client.post(
+        "/api/v1/capacity/purchase-slot", json={"quantity": quantity}
+    )

tetra_cli-0.5.0/tetra_cli/api_client/operations/event_sessions.py

@@ -0,0 +1,228 @@
+"""Pure async operations for the event-sessions API.
+
+Event Sessions group two or more existing events on the same subject timeline
+into a named "occurrence" (e.g. three lifts logged in one gym visit). Grouping
+is a first-class capability, so it must be drivable from the CLI and the
+generated MCP tools — not just the web app. Each op here is a thin wrapper over
+one ``/api/v1/event-sessions`` endpoint; the backend owns quorum, shared-scope,
+and authorization rules.
+"""
+from typing import Any
+
+from tetra_cli.api_client import TetraClient
+from tetra_cli.registry import arg, operation, opt
+
+
+@operation(
+    cli="events session group",
+    summary="Group >= 2 existing events into a new session.",
+    covers=[("POST", "/api/v1/event-sessions")],
+    params={
+        "event_uids": opt("--uid", repeatable=True,
+                          help="Event UID to group (repeatable, >= 2 required)"),
+        "name": opt("--name", help="Optional session label"),
+    },
+)
+async def group_events(
+    client: TetraClient,
+    *,
+    event_uids: list[str],
+    name: str | None = None,
+) -> dict[str, Any]:
+    """Group existing events into a new session.
+
+    All events must resolve and share one ``group_uid`` (the same subject
+    timeline); the backend rejects cross-group grouping with HTTP 400.
+
+    Args:
+        client: Authenticated TetraClient
+        event_uids: Event UIDs to group (at least two, same subject timeline)
+        name: Optional display label for the session
+
+    Returns:
+        The created session detail (uid, members, summary fields).
+    """
+    body: dict[str, Any] = {"event_uids": event_uids}
+    if name is not None:
+        body["name"] = name
+    return await client.post("/api/v1/event-sessions", json=body)
+
+
+@operation(
+    cli="events session show",
+    summary="Get a session with its member events.",
+    covers=[("GET", "/api/v1/event-sessions/{uid}")],
+    params={
+        "uid": arg(help="Session UID"),
+    },
+)
+async def show_event_session(client: TetraClient, uid: str) -> dict[str, Any]:
+    """Get one session and its member events.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: Session UID
+
+    Returns:
+        The session detail dict (summary fields plus member events).
+    """
+    return await client.get(f"/api/v1/event-sessions/{uid}")
+
+
+@operation(
+    cli="events session list",
+    summary="List sessions on the caller's own timeline.",
+    covers=[("GET", "/api/v1/event-sessions")],
+)
+async def list_event_sessions(client: TetraClient) -> list[dict[str, Any]]:
+    """List the caller's own personal-timeline sessions.
+
+    Intentionally self-scoped to the caller's ``personal_group_uid`` — group
+    sessions are reached via their events, not this listing.
+
+    Args:
+        client: Authenticated TetraClient
+
+    Returns:
+        A list of session summary dicts.
+    """
+    return await client.get("/api/v1/event-sessions")
+
+
+@operation(
+    cli="events session rename",
+    summary="Set a session's display label.",
+    covers=[("PATCH", "/api/v1/event-sessions/{uid}")],
+    params={
+        "uid": arg(help="Session UID"),
+        "name": arg(help="New display label"),
+    },
+)
+async def rename_event_session(
+    client: TetraClient, uid: str, name: str,
+) -> dict[str, Any]:
+    """Relabel a session.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: Session UID
+        name: New display label
+
+    Returns:
+        The updated session summary dict.
+    """
+    return await client.patch(
+        f"/api/v1/event-sessions/{uid}", json={"name": name}
+    )
+
+
+@operation(
+    cli="events session add-member",
+    summary="Attach one more event to an existing session.",
+    covers=[("POST", "/api/v1/event-sessions/{uid}/members")],
+    params={
+        "uid": arg(help="Session UID"),
+        "event_uid": arg(help="Event UID to attach"),
+    },
+)
+async def add_event_session_member(
+    client: TetraClient, uid: str, event_uid: str,
+) -> dict[str, Any]:
+    """Attach one more event to a session.
+
+    The event must share the session's ``group_uid``; if it already belongs to
+    another session it is re-homed here.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: Session UID to grow
+        event_uid: Event UID to attach
+
+    Returns:
+        The updated session summary dict.
+    """
+    return await client.post(
+        f"/api/v1/event-sessions/{uid}/members", json={"event_uid": event_uid}
+    )
+
+
+@operation(
+    cli="events session remove-member",
+    summary="Detach one event; the session dissolves below quorum.",
+    covers=[("DELETE", "/api/v1/event-sessions/{uid}/members/{event_uid}")],
+    params={
+        "uid": arg(help="Session UID"),
+        "event_uid": arg(help="Event UID to detach"),
+    },
+)
+async def remove_event_session_member(
+    client: TetraClient, uid: str, event_uid: str,
+) -> dict[str, Any] | None:
+    """Detach one event from a session.
+
+    If removing the event drops the session below quorum, the session is
+    dissolved entirely and the response is ``null``.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: Session UID
+        event_uid: Event UID to detach
+
+    Returns:
+        The resulting session summary, or ``None`` if the session dissolved.
+    """
+    return await client.delete(
+        f"/api/v1/event-sessions/{uid}/members/{event_uid}"
+    )
+
+
+@operation(
+    cli="events session ungroup",
+    summary="Dissolve a session entirely, unlinking all its members.",
+    covers=[("DELETE", "/api/v1/event-sessions/{uid}")],
+    params={
+        "uid": arg(help="Session UID"),
+    },
+)
+async def ungroup_event_session(
+    client: TetraClient, uid: str,
+) -> dict[str, Any] | None:
+    """Dissolve a session, unlinking every member event.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: Session UID
+
+    Returns:
+        Empty/``None`` — the backend responds 204 No Content.
+    """
+    return await client.delete(f"/api/v1/event-sessions/{uid}")
+
+
+@operation(
+    cli="events session suggest",
+    summary="Advisory: which session/event should an event join? (never stamps)",
+    covers=[("POST", "/api/v1/event-sessions/suggest")],
+    params={
+        "event_uid": arg(help="Candidate event UID"),
+    },
+)
+async def suggest_event_session(
+    client: TetraClient, event_uid: str,
+) -> dict[str, Any] | None:
+    """Ask which session/event the given event should join.
+
+    Purely advisory — it never mutates. Returns ``null`` when nothing on the
+    same subject timeline matches within the session window.
+
+    Args:
+        client: Authenticated TetraClient
+        event_uid: Candidate event UID
+
+    Returns:
+        A suggestion dict (join_session_uid / join_event_uid / derived_label),
+        or ``None`` when nothing matches.
+    """
+    return await client.post(
+        "/api/v1/event-sessions/suggest", json={"event_uid": event_uid}
+    )

tetra_cli-0.5.0/tetra_cli/api_client/operations/foods.py

@@ -0,0 +1,31 @@
+"""Pure async operations for the foods API."""
+from typing import Any
+
+from tetra_cli.api_client import TetraClient
+from tetra_cli.registry import arg, operation
+
+
+@operation(
+    cli="foods search",
+    summary="Search foods by free-text description (USDA-backed, cached).",
+    covers=[("GET", "/api/v1/foods/search")],
+    params={
+        "q": arg(help="Free-text food search term (e.g. \"egg\")"),
+    },
+)
+async def food_search(client: TetraClient, q: str) -> Any:
+    """Search cached/USDA foods by free-text description.
+
+    Delegates to the server's ``FoodLookupService``: a local-cache hit
+    answers immediately, a miss fills in from USDA FoodData Central. Returns
+    whatever shape the endpoint returns, unmodified.
+
+    Args:
+        client: Authenticated TetraClient
+        q: Non-empty free-text search term (e.g. "egg")
+
+    Returns:
+        List of food dicts (fdc_food_id, description, brand, kcal_per_100g,
+        protein_per_100g, carb_per_100g, fat_per_100g, serving_size_g)
+    """
+    return await client.get("/api/v1/foods/search", params={"q": q})

{tetra_cli-0.2.0 → tetra_cli-0.5.0}/tetra_cli/api_client/operations/goals.py

@@ -188,6 +188,10 @@ async def create_goal(
             help=("Goal status as a label (created | in_progress | archived | "
                   "abandoned | completed) or its numeric form (1-5)."),
         ),
+        "group_uid": opt(
+            "--group-uid",
+            help="Group UID for a group-scoped update (e.g. editing a goal you "
+                 "created on a mentee's behalf). Omit for your personal scope."),
     },
 )
 async def update_goal(
@@ -206,6 +210,7 @@ async def update_goal(
     outcome_shape: str | None = None,
     outcome_names: list[str] | None = None,
     status: str | None = None,
+    group_uid: str | None = None,
 ) -> dict[str, Any]:
     """Update an existing goal. Only provided (non-None) fields are changed.
 
@@ -227,6 +232,9 @@ async def update_goal(
             2=IN_PROGRESS, 3=ARCHIVED, 4=ABANDONED, 5=COMPLETED) or a label
             string ("created" … "completed", case-insensitive). The op
             normalizes labels→int so the CLI/MCP surfaces share the behavior.
+        group_uid: Group UID for a group-scoped update. Required to edit a goal
+            that lives in a group (e.g. one created on a mentee's behalf);
+            omit for personal-scope goals.
 
     Returns:
         Updated goal dict
@@ -260,26 +268,43 @@ async def update_goal(
         body["outcome_names"] = outcome_names
     if status is not None:
         body["status"] = _normalize_status(status)
-    return await client.put(f"/api/v1/goals/{uid}", json=body)
+    path = f"/api/v1/goals/{uid}"
+    if group_uid is not None:
+        path += f"?group_uid={group_uid}"
+    return await client.put(path, json=body)
 
 
 @operation(
     cli="goals delete",
     summary="Delete a goal permanently.",
     covers=[("DELETE", "/api/v1/goals/{uid}")],
-    params={"uid": arg(help="Goal UID to delete")},
+    params={
+        "uid": arg(help="Goal UID to delete"),
+        "group_uid": opt(
+            "--group-uid",
+            help="Group UID for a group-scoped delete (e.g. a goal you created "
+                 "on a mentee's behalf). Omit for your personal scope."),
+    },
 )
-async def delete_goal(client: TetraClient, uid: str) -> dict[str, Any]:
+async def delete_goal(
+    client: TetraClient, uid: str, *, group_uid: str | None = None,
+) -> dict[str, Any]:
     """Delete a goal permanently.
 
     Args:
         client: Authenticated TetraClient
         uid: Goal UID to delete
+        group_uid: Group UID for a group-scoped delete. Required to delete a
+            goal that lives in a group (e.g. one created on a mentee's behalf);
+            omit for personal-scope goals.
 
     Returns:
         Deletion confirmation dict
     """
-    return await client.delete(f"/api/v1/goals/{uid}")
+    path = f"/api/v1/goals/{uid}"
+    if group_uid is not None:
+        path += f"?group_uid={group_uid}"
+    return await client.delete(path)
 
 
 @operation(
@@ -476,6 +501,10 @@ async def delete_goal_metric(
                           help="New parent goal name (omit to keep current)."),
         "new_priority": opt("--priority", min=1,
                             help="New priority among siblings (1 = top)."),
+        "group_uid": opt(
+            "--group-uid",
+            help="Group UID for a group-scoped move (e.g. a mentee's goal). "
+                 "Omit for your personal scope."),
     },
 )
 async def move_goal(
@@ -484,6 +513,7 @@ async def move_goal(
     uid: str,
     new_parent: str | None = None,
     new_priority: int | None = None,
+    group_uid: str | None = None,
 ) -> dict[str, Any]:
     """Move a goal to a new parent and/or position in the sibling order.
 
@@ -508,8 +538,12 @@ async def move_goal(
     body: dict[str, Any] = {"uid": uid}
     if new_parent is None:
         # Caller didn't specify — pre-fetch and use current parent so the
-        # API doesn't interpret missing as "move to root."
-        current = await client.get(f"/api/v1/goals/{uid}")
+        # API doesn't interpret missing as "move to root." Scope the read to
+        # the same group so a mentee's goal resolves.
+        read_path = f"/api/v1/goals/{uid}"
+        if group_uid is not None:
+            read_path += f"?group_uid={group_uid}"
+        current = await client.get(read_path)
         if current.get("parent"):
             body["new_parent"] = current["parent"]
         # else: goal is already a root, omit new_parent (API treats omitted
@@ -521,6 +555,8 @@ async def move_goal(
         body["new_parent"] = new_parent
     if new_priority is not None:
         body["new_priority"] = new_priority
+    if group_uid is not None:
+        body["group_uid"] = group_uid
     return await client.post("/api/v1/goals/move", json=body)
 
 
@@ -574,6 +610,10 @@ async def batch_delete_goals(
         "updates": opt("--updates", json=True,
                        help="JSON map of {goal_uid: new_priority} (1-based, sequential)."),
         "parent": opt("--parent", help="Parent goal name (omit for root siblings)."),
+        "group_uid": opt(
+            "--group-uid",
+            help="Group UID for a group-scoped reorder (e.g. a mentee's goals). "
+                 "Omit for your personal scope."),
     },
 )
 async def batch_update_goal_priorities(
@@ -581,6 +621,7 @@ async def batch_update_goal_priorities(
     *,
     updates: dict[str, int],
     parent: str | None = None,
+    group_uid: str | None = None,
 ) -> dict[str, Any]:
     """Batch-update priorities for goals within one sibling group.
 
@@ -591,6 +632,8 @@ async def batch_update_goal_priorities(
         client: Authenticated TetraClient
         updates: Map of ``{goal_uid: new_priority}`` (1 = top).
         parent: Parent goal name (null/omit for root-level siblings).
+        group_uid: Group UID for a group-scoped reorder (e.g. a mentee's
+            goals); omit for personal scope.
 
     Returns:
         Dict with ``updated`` count and the affected ``uids``.
@@ -598,7 +641,10 @@ async def batch_update_goal_priorities(
     body: dict[str, Any] = {"updates": updates}
     if parent is not None:
         body["parent"] = parent
-    return await client.post("/api/v1/goals/batch-update-priorities", json=body)
+    path = "/api/v1/goals/batch-update-priorities"
+    if group_uid is not None:
+        path += f"?group_uid={group_uid}"
+    return await client.post(path, json=body)
 
 
 @operation(
@@ -610,6 +656,14 @@ async def batch_update_goal_priorities(
                            help="Source goal UID to merge (repeatable; 2+ required)."),
         "new_goal": opt("--new-goal", json=True,
                         help="New goal data as a JSON dict (at least {\"name\": ...})."),
+        "group_uid": opt(
+            "--group-uid",
+            help="Group UID for a group-scoped merge (e.g. a mentee's goals). "
+                 "Omit for your personal scope."),
+        "for_account_uid": opt(
+            "--for-account-uid",
+            help="Merge on this member's behalf — the merged goal belongs to "
+                 "them (mentee account UID); requires --group-uid."),
     },
 )
 async def merge_goals(
@@ -617,6 +671,8 @@ async def merge_goals(
     *,
     source_uids: list[str],
     new_goal: dict[str, Any],
+    group_uid: str | None = None,
+    for_account_uid: str | None = None,
 ) -> dict[str, Any]:
     """Merge two or more goals into a new goal.
 
@@ -628,11 +684,19 @@ async def merge_goals(
         source_uids: UIDs of the goals to merge (at least 2).
         new_goal: New goal payload (must include ``name``; may include
             ``parent``, ``values``, etc.).
+        group_uid: Group UID for a group-scoped merge (e.g. a mentee's
+            goals); omit for personal scope.
+        for_account_uid: Merge on this member's behalf so the merged goal
+            belongs to them (mentee account UID); requires ``group_uid``.
 
     Returns:
         The created goal dict.
     """
     body: dict[str, Any] = {"source_uids": source_uids, "new_goal": new_goal}
+    if group_uid is not None:
+        body["group_uid"] = group_uid
+    if for_account_uid is not None:
+        body["for_account_uid"] = for_account_uid
     return await client.post("/api/v1/goals/merge", json=body)
 
 
@@ -1085,6 +1149,10 @@ async def get_goal_status_stages(
         "uid": arg(help="Goal UID"),
         "old_name": opt("--old-name", help="Current field name to rename."),
         "new_name": opt("--new-name", help="New field name."),
+        "group_uid": opt(
+            "--group-uid",
+            help="Group UID for a group-scoped rename (e.g. a mentee's goal). "
+                 "Omit for your personal scope."),
     },
 )
 async def rename_goal_field(
@@ -1093,6 +1161,7 @@ async def rename_goal_field(
     *,
     old_name: str,
     new_name: str,
+    group_uid: str | None = None,
 ) -> dict[str, Any]:
     """Rename a tuple/record field on a goal and across all its events.
 
@@ -1104,13 +1173,18 @@ async def rename_goal_field(
         uid: Goal UID.
         old_name: Existing field name.
         new_name: Replacement field name.
+        group_uid: Group UID for a group-scoped rename (e.g. a mentee's
+            goal); omit for personal scope.
 
     Returns:
         Dict with ``success``, ``events_updated``, and the new
         ``outcome_names``.
     """
     body: dict[str, Any] = {"old_name": old_name, "new_name": new_name}
-    return await client.post(f"/api/v1/goals/{uid}/rename-field", json=body)
+    path = f"/api/v1/goals/{uid}/rename-field"
+    if group_uid is not None:
+        path += f"?group_uid={group_uid}"
+    return await client.post(path, json=body)
 
 
 @operation(
@@ -1142,3 +1216,97 @@ async def reorder_all_goals(
     return await client.post(
         "/api/v1/goals/reorder-all", json={"order": order}
     )
+
+
+@operation(
+    cli="goals link-value",
+    summary="Mirror-link a goal to a value: renaming one renames the other.",
+    covers=[("POST", "/api/v1/goals/{uid}/link-value")],
+    params={
+        "uid": arg(help="Goal UID to link"),
+        "value_uid": arg(help="Value UID to link it to (same scope)"),
+        "name_source": opt(
+            "--name-source",
+            choices=["goal", "value"],
+            help="When the leaf names differ, which name wins — the loser "
+                 "is renamed to match (with descendant cascade). "
+                 "Default: goal.",
+        ),
+        "group_uid": opt(
+            "--group-uid",
+            help="Group UID for a group-scoped link (goal + value both in "
+                 "that group, e.g. a mentee's). Omit for your personal scope."),
+    },
+)
+async def link_goal_value(
+    client: TetraClient,
+    *,
+    uid: str,
+    value_uid: str,
+    name_source: str | None = None,
+    group_uid: str | None = None,
+) -> dict[str, Any]:
+    """Create the explicit 1:1 mirror link between a goal and a value.
+
+    Same scope required; a value can be the mirror of at most one goal
+    (409 when it is already linked elsewhere). While linked, leaf renames
+    propagate across the link in both directions. Independent of the
+    draws-from/adds-to assignment in the goal's ``values``.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: Goal UID.
+        value_uid: Value UID in the same scope.
+        name_source: 'goal' or 'value' — which name wins when the leaves
+            differ (the loser is renamed with cascade). Defaults to 'goal'.
+        group_uid: Group UID for a group-scoped link (both goal and value
+            live in that group, e.g. a mentee's); omit for personal scope.
+
+    Returns:
+        The updated goal dict, including ``linked_value`` {uid, name}.
+    """
+    body: dict[str, Any] = {"value_uid": value_uid}
+    if name_source is not None:
+        body["name_source"] = name_source
+    path = f"/api/v1/goals/{uid}/link-value"
+    if group_uid is not None:
+        path += f"?group_uid={group_uid}"
+    return await client.post(path, json=body)
+
+
+@operation(
+    cli="goals unlink-value",
+    summary="Remove a goal's mirror link; both sides rename independently.",
+    covers=[("DELETE", "/api/v1/goals/{uid}/link-value")],
+    params={
+        "uid": arg(help="Goal UID to unlink"),
+        "group_uid": opt(
+            "--group-uid",
+            help="Group UID for a group-scoped unlink (e.g. a mentee's goal). "
+                 "Omit for your personal scope."),
+    },
+)
+async def unlink_goal_value(
+    client: TetraClient,
+    *,
+    uid: str,
+    group_uid: str | None = None,
+) -> dict[str, Any]:
+    """Remove the goal's explicit value link.
+
+    The draws-from/adds-to assignment in ``values`` is kept — unlinking
+    only stops rename mirroring.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: Goal UID.
+        group_uid: Group UID for a group-scoped unlink (e.g. a mentee's
+            goal); omit for personal scope.
+
+    Returns:
+        The updated goal dict with ``linked_value: null``.
+    """
+    path = f"/api/v1/goals/{uid}/link-value"
+    if group_uid is not None:
+        path += f"?group_uid={group_uid}"
+    return await client.delete(path)