socaity-cli 0.1.7__tar.gz → 0.1.8__tar.gz

{socaity_cli-0.1.7 → socaity_cli-0.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: socaity-cli
-Version: 0.1.7
+Version: 0.1.8
 Summary: Socaity platform CLI: login, catalog browsing, SDK installs and APIPod deployment commands.
 Author: SocAIty
 License: MIT
@@ -9,7 +9,7 @@ Project-URL: Homepage, https://www.socaity.ai
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 Requires-Dist: httpx
-Requires-Dist: socaity-schemas>=0.1.4
+Requires-Dist: socaity-schemas>=0.1.6
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: ruff; extra == "dev"
@@ -49,15 +49,15 @@ You get `socaity-cli` as part of `pip install socaity` or `pip install apipod` a
 | `socaity start [entrypoint]` | `apipod` | Run an APIPod service locally |
 | `socaity deploy [target]` | `apipod` | Deploy to Socaity (wraps `apipod deploy`) |
 
-Use `-C DIR` with scan/build/start/deploy to point at a service project directory
-(e.g. `socaity -C simple_test_service deploy serverless-runpod --yes`).
+Use `--project-dir DIR` with scan/build/start/deploy to point at a service project directory
+(e.g. `socaity --project-dir simple_test_service deploy serverless-runpod --yes`).
 
 ## Configuration
 
 | Env var | Default | Purpose |
 |---------|---------|---------|
 | `SOCAITY_API_KEY` | from login | API key (wins over stored credentials) |
-| `SOCAITY_BACKEND_URL` | `https://webapi.socaity.ai` | Platform API |
+| `SOCAITY_BACKEND_URL` | `https://webapi.socaity.ai` | Platform API (env wins; login file is fallback only, never written into the process) |
 | `SOCAITY_FRONTEND_URL` | `https://socaity.ai` | Web UI for browser login |
 
 ## Using it as a library

{socaity_cli-0.1.7 → socaity_cli-0.1.8}/README.md

@@ -32,15 +32,15 @@ You get `socaity-cli` as part of `pip install socaity` or `pip install apipod` a
 | `socaity start [entrypoint]` | `apipod` | Run an APIPod service locally |
 | `socaity deploy [target]` | `apipod` | Deploy to Socaity (wraps `apipod deploy`) |
 
-Use `-C DIR` with scan/build/start/deploy to point at a service project directory
-(e.g. `socaity -C simple_test_service deploy serverless-runpod --yes`).
+Use `--project-dir DIR` with scan/build/start/deploy to point at a service project directory
+(e.g. `socaity --project-dir simple_test_service deploy serverless-runpod --yes`).
 
 ## Configuration
 
 | Env var | Default | Purpose |
 |---------|---------|---------|
 | `SOCAITY_API_KEY` | from login | API key (wins over stored credentials) |
-| `SOCAITY_BACKEND_URL` | `https://webapi.socaity.ai` | Platform API |
+| `SOCAITY_BACKEND_URL` | `https://webapi.socaity.ai` | Platform API (env wins; login file is fallback only, never written into the process) |
 | `SOCAITY_FRONTEND_URL` | `https://socaity.ai` | Web UI for browser login |
 
 ## Using it as a library

{socaity_cli-0.1.7 → socaity_cli-0.1.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "socaity-cli"
-version = "0.1.7"
+version = "0.1.8"
 description = "Socaity platform CLI: login, catalog browsing, SDK installs and APIPod deployment commands."
 requires-python = ">=3.8"
 authors = [
@@ -14,7 +14,7 @@ license = { text = "MIT" }
 readme = "README.md"
 dependencies = [
     "httpx",
-    "socaity-schemas>=0.1.4",
+    "socaity-schemas>=0.1.6",
 ]
 
 [project.scripts]

{socaity_cli-0.1.7 → socaity_cli-0.1.8}/socaity_cli/backend_client.py

@@ -1,11 +1,14 @@
-"""Composed platform backend client (catalog, jobs, projects, analytics, files, sdk, deployment)."""
+"""Composed platform backend client (catalog, jobs, projects, analytics, files, sdk, deployment, workflows)."""
 from socaity_cli.clients.analytics import AnalyticsClient
 from socaity_cli.clients.catalog import CatalogClient
+from socaity_cli.clients.conversations import ConversationsClient
 from socaity_cli.clients.deployment import DeploymentClient
 from socaity_cli.clients.files import FilesClient
+from socaity_cli.clients.interrupts import InterruptsClient
 from socaity_cli.clients.jobs import JobsClient
 from socaity_cli.clients.projects import ProjectsClient
 from socaity_cli.clients.sdk_install import SdkInstallClient
+from socaity_cli.clients.workflows import WorkflowsClient
 from socaity_cli.http import BackendHttp
 
 
@@ -18,6 +21,9 @@ class SocaityBackendClient(
     FilesClient,
     SdkInstallClient,
     DeploymentClient,
+    ConversationsClient,
+    InterruptsClient,
+    WorkflowsClient,
 ):
     """Facade over domain mixins. Prefer importing a domain client when you only need one surface."""
     pass

{socaity_cli-0.1.7 → socaity_cli-0.1.8}/socaity_cli/cli.py

@@ -3,12 +3,14 @@
 from __future__ import annotations
 
 import argparse
+import json
+from pathlib import Path
 
 from socaity_cli.apipod_commands import run_build, run_deploy, run_scan, run_start
 from socaity_cli.auth import run_login, run_whoami
 from socaity_cli.backend_client import SocaityBackendClient
 from socaity_cli.credentials import clear_credentials, require_credentials
-from socaity_cli.sdk_commands import run_install, run_update
+from socaity_cli.sdk_commands import run_install, run_update, run_workflow_command
 
 
 def _run_list(entity: str, category: str | None, family: str | None, limit: int) -> None:
@@ -75,6 +77,127 @@ def _run_jobs(
         _print_job(job)
 
 
+def _run_interrupts(
+    interrupt_id: str | None,
+    resolve: str | None,
+    message: str | None,
+    expand: str | None,
+    status: str | None,
+    limit: int,
+    no_continue: bool = False,
+) -> None:
+    client = SocaityBackendClient()
+    expand_list = _split_csv(expand)
+
+    if interrupt_id and resolve:
+        result = client.resolve_interrupt(
+            interrupt_id, decision=resolve, message=message, continue_run=not no_continue,
+        )
+        if not result:
+            print(f"Interrupt '{interrupt_id}' not found.")
+            return
+        print(result.model_dump_json(indent=2, exclude_none=True))
+        return
+
+    if interrupt_id:
+        interrupt = client.get_interrupt(interrupt_id, expand=expand_list)
+        if not interrupt:
+            print(f"Interrupt '{interrupt_id}' not found.")
+            return
+        print(interrupt.model_dump_json(indent=2, exclude_none=True))
+        return
+
+    filters = [f"status:eq:{status}"] if status else None
+    interrupts = client.query_interrupts(filters=filters, expand=expand_list, limit=limit)
+    if not interrupts:
+        print("No pending interrupts. Your agents are not waiting on you.")
+        return
+    for row in interrupts:
+        decisions = "|".join(row.allowed_decisions or [])
+        print(f"{row.id}  {row.action_name}  [{row.status}]  ({decisions})  {row.description or ''}".rstrip())
+
+
+def _parse_inputs(pairs: list[str] | None) -> dict:
+    """Parse repeatable ``--input key=value`` flags. Values parse as JSON when possible."""
+    inputs: dict = {}
+    for pair in pairs or []:
+        key, separator, value = pair.partition("=")
+        if not separator or not key.strip():
+            print(f"Ignoring malformed --input '{pair}' (expected key=value).")
+            continue
+        try:
+            inputs[key.strip()] = json.loads(value)
+        except json.JSONDecodeError:
+            inputs[key.strip()] = value
+    return inputs
+
+
+def _run_workflows(args) -> None:
+    client = SocaityBackendClient()
+    command = args.workflows_command
+
+    if command == "list":
+        workflows = client.search_workflows(query=args.q, limit=args.limit)
+        if not workflows:
+            print("No workflows found.")
+            return
+        for workflow in workflows:
+            visibility = "public" if workflow.is_public else "private"
+            print(f"{workflow.id}  {workflow.slug or '-'}  [{visibility}]  {workflow.title or ''}".rstrip())
+        return
+
+    if command == "get":
+        workflow = client.get_workflow(args.workflow_id)
+        if not workflow:
+            print(f"Workflow '{args.workflow_id}' not found.")
+            return
+        print(workflow.model_dump_json(indent=2, exclude_none=True))
+        return
+
+    if command == "push":
+        path = Path(args.file)
+        if not path.is_file():
+            print(f"File '{args.file}' not found.")
+            return
+        document = json.loads(path.read_text(encoding="utf-8"))
+        result = client.upsert_workflow(document, slug=args.slug, message=args.message)
+        if not result:
+            print("Workflow upsert failed.")
+            return
+        state = "unchanged" if result.unchanged else ("forked" if result.forked else "saved")
+        print(f"{result.workflow.id}  revision {result.revision.id}  [{state}]")
+        return
+
+    if command == "publish":
+        workflow = client.publish_workflow(args.workflow_id, revision_id=args.revision_id)
+        if not workflow:
+            print(f"Workflow '{args.workflow_id}' not found or not publishable.")
+            return
+        print(f"{workflow.id}  published revision {workflow.published_revision_id}")
+        return
+
+    if command == "runs":
+        if args.workflow_id and args.workflow_id.startswith("wr_"):
+            run = client.get_workflow_run(args.workflow_id, expand=["traces"])
+            if not run:
+                print(f"Workflow run '{args.workflow_id}' not found.")
+                return
+            print(run.model_dump_json(indent=2, exclude_none=True))
+            return
+        runs = client.query_workflow_runs(workflow_id=args.workflow_id, limit=args.limit)
+        if not runs:
+            print("No workflow runs found.")
+            return
+        for run in runs:
+            cost = f"  {run.total_cost_eur:.4f} EUR" if run.total_cost_eur is not None else ""
+            print(f"{run.id}  [{run.status}]  {run.workflow_id or '?'}  {run.created_at or ''}{cost}")
+        return
+
+    if command == "run":
+        run_workflow_command(args.workflow_id, _parse_inputs(args.input), timeout_s=args.timeout)
+        return
+
+
 def _run_projects(project_id: str | None, expand: str | None, limit: int) -> None:
     client = SocaityBackendClient()
     expand_list = _split_csv(expand)
@@ -137,7 +260,7 @@ Examples:
   socaity build main.py
   socaity start --port 8123
   socaity deploy serverless-runpod
-  socaity -C simple_test_service deploy serverless-runpod --yes
+  socaity --project-dir simple_test_service deploy serverless-runpod --yes
         """,
     )
     parser.add_argument(
@@ -146,12 +269,19 @@ Examples:
         help="Install an AI service (requires login)",
     )
     parser.add_argument(
-        "-C",
         "--project-dir",
+        dest="project_dir",
         default=None,
         metavar="DIR",
         help="Service project directory for apipod commands (scan/build/start/deploy).",
     )
+    parser.add_argument(
+        "-C",
+        "--cwd",
+        dest="project_dir",
+        metavar="DIR",
+        help=argparse.SUPPRESS,
+    )
 
     subparsers = parser.add_subparsers(dest="command")
 
@@ -201,6 +331,59 @@ Examples:
     )
     jobs_parser.add_argument("--limit", type=int, default=25)
 
+    interrupts_parser = subparsers.add_parser(
+        "interrupts", help="Your HIT approval inbox: list, inspect, or answer agent action requests (requires login)"
+    )
+    interrupts_parser.add_argument("interrupt_id", nargs="?", default=None, help="Interrupt id for detail or resolve")
+    interrupts_parser.add_argument(
+        "--resolve", default=None, choices=("approve", "edit", "reject", "respond"),
+        help="Answer the given interrupt with this decision",
+    )
+    interrupts_parser.add_argument("--message", default=None, help="Reject feedback or respond answer text")
+    interrupts_parser.add_argument("--expand", default=None, help="Comma-separated: chat,chat_item,job")
+    interrupts_parser.add_argument("--status", default=None, help="Filter by status (default: pending)")
+    interrupts_parser.add_argument(
+        "--no-continue", action="store_true",
+        help="Record the decision without enqueuing the agent continue job",
+    )
+    interrupts_parser.add_argument("--limit", type=int, default=25)
+
+    workflows_parser = subparsers.add_parser(
+        "workflows", help="Manage and run your workflows (requires login)"
+    )
+    workflows_sub = workflows_parser.add_subparsers(dest="workflows_command")
+
+    wf_list = workflows_sub.add_parser("list", help="List your workflows plus public ones")
+    wf_list.add_argument("--q", default=None, help="Fuzzy search over title, goal, slug, and node text")
+    wf_list.add_argument("--limit", type=int, default=25)
+
+    wf_get = workflows_sub.add_parser("get", help="Show one workflow including its document")
+    wf_get.add_argument("workflow_id", help="Workflow id (wf_...) or slug")
+
+    wf_push = workflows_sub.add_parser("push", help="Upsert a workflow from a JSON document file")
+    wf_push.add_argument("file", help="Path to the workflow document JSON")
+    wf_push.add_argument("--slug", default=None, help="Stable per-owner handle")
+    wf_push.add_argument("--message", default=None, help="Revision message (changelog)")
+
+    wf_publish = workflows_sub.add_parser("publish", help="Publish a workflow (pins a revision)")
+    wf_publish.add_argument("workflow_id", help="Workflow id (wf_...) or slug")
+    wf_publish.add_argument("--revision-id", default=None, help="rv_ id to pin; default latest valid")
+
+    wf_runs = workflows_sub.add_parser("runs", help="List workflow runs, or inspect one (wr_ id)")
+    wf_runs.add_argument(
+        "workflow_id", nargs="?", default=None,
+        help="Workflow id to filter by, or a run id (wr_...) for a detailed view",
+    )
+    wf_runs.add_argument("--limit", type=int, default=25)
+
+    wf_run = workflows_sub.add_parser("run", help="Run a workflow via the inference gateway (requires socaity)")
+    wf_run.add_argument("workflow_id", help="Workflow id (wf_...) or slug")
+    wf_run.add_argument(
+        "--input", action="append", default=None, metavar="KEY=VALUE",
+        help="Workflow input (repeatable). Values parse as JSON when possible.",
+    )
+    wf_run.add_argument("--timeout", type=float, default=None, help="Give up waiting after this many seconds")
+
     projects_parser = subparsers.add_parser("projects", help="List your projects or inspect one (requires login)")
     projects_parser.add_argument("project_id", nargs="?", default=None, help="Project id for a detailed view")
     projects_parser.add_argument("--expand", default=None, help="Comma-separated: jobs (nested: jobs.data, ...)")
@@ -224,7 +407,7 @@ Examples:
             "Examples:\n"
             "  socaity deploy\n"
             "  socaity deploy serverless-runpod\n"
-            "  socaity -C simple_test_service deploy serverless-runpod --yes\n"
+            "  socaity --project-dir simple_test_service deploy serverless-runpod --yes\n"
             "  socaity deploy --skip-build\n"
             "  socaity deploy --resume DEPLOYMENT_ID"
         ),
@@ -318,6 +501,22 @@ Examples:
         _run_jobs(args.job_id, args.expand, args.status, args.visibility, args.limit, q=args.q)
         return
 
+    if args.command == "interrupts":
+        require_credentials()
+        _run_interrupts(
+            args.interrupt_id, args.resolve, args.message,
+            args.expand, args.status, args.limit, no_continue=args.no_continue,
+        )
+        return
+
+    if args.command == "workflows":
+        if not args.workflows_command:
+            workflows_parser.print_help()
+            return
+        require_credentials()
+        _run_workflows(args)
+        return
+
     if args.command == "projects":
         require_credentials()
         _run_projects(args.project_id, args.expand, args.limit)

{socaity_cli-0.1.7 → socaity_cli-0.1.8}/socaity_cli/clients/catalog.py

@@ -1,15 +1,84 @@
 """AI catalog reads (`/v1/catalog`)."""
+import re
 from typing import Dict, List, Optional, Union
 
 from socaity_schemas.platform import AIModel, AIService, Job, ServiceCategory
 
 SERVICE_LIST_FIELDS = ["id", "name", "display_name", "short_desc", "categories", "is_official", "n_usages"]
+SERVICE_DETAIL_EXPAND = ["deployments.contract", "endpoints", "models"]
 MODEL_LIST_FIELDS = ["id", "name", "display_name", "family", "release_date", "hugging_face_url"]
 
 
 class CatalogClient:
     """Mixin: catalog list/get/search. Requires ``BackendHttp`` methods on ``self``."""
 
+    SERVICE_DETAIL_EXPAND = SERVICE_DETAIL_EXPAND
+
+    def search_services(
+        self,
+        query: Optional[str] = None,
+        category: Optional[str] = None,
+        filters: Optional[List[str]] = None,
+        expand: Optional[List[str]] = None,
+        fields: Optional[List[str]] = None,
+        sort: Optional[str] = None,
+        limit: int = 20,
+        offset: int = 0,
+        mine: bool = False,
+    ) -> List[AIService]:
+        """Find AI services in the socaity catalog.
+
+        Start here for any generation task. Search by capability ("text to image",
+        "voice cloning"). Results are slim catalog rows; call ``get_service`` with
+        a hit ``id`` for endpoints and the call signature under
+        ``deployments.contract``.
+
+        Args:
+            query: Free-text search. Omit to browse.
+            category: Category id (not display name).
+            filters: Repeatable ``field:operator:value`` strings.
+            expand: Relations to embed (``deployments``, ``models``, ``pricing``).
+            fields: Sparse fieldset, e.g. ``["id", "name"]``.
+            sort: ``field:asc`` or ``field:desc``.
+            limit: Page size, 1 to 100.
+            offset: Skip this many rows; increase by ``limit`` for the next page.
+            mine: Only services owned by the caller.
+
+        Returns:
+            Service rows, or an empty list when nothing matches.
+        """
+        service_filters = list(filters or [])
+        if category:
+            service_filters.append(f"categories:contains:{category}")
+        rows = self.query_services(
+            q=query,
+            filters=service_filters or None,
+            expand=expand,
+            fields=fields,
+            sort=sort,
+            limit=limit,
+            offset=offset,
+            mine=mine,
+        )
+        # Stale Typesense (watermark after empty first sync, or a later
+        # write-through of one service) can return [] or the wrong hit while
+        # GET /services still lists the row. Browse + local token match fills
+        # the gap without waiting for an index rebuild.
+        if query and not mine:
+            matched = [row for row in rows if _service_matches_query(row, query)]
+            if matched:
+                return matched[:limit]
+            browsed = self.query_services(
+                filters=service_filters or None,
+                expand=expand,
+                fields=fields,
+                sort=sort,
+                limit=max(limit, 100),
+                offset=0,
+            )
+            return [row for row in browsed if _service_matches_query(row, query)][:limit]
+        return rows
+
     def query_services(
         self,
         q: Optional[str] = None,
@@ -21,6 +90,7 @@ class CatalogClient:
         offset: int = 0,
         known_ids: Optional[List[str]] = None,
         known_fieldset: Optional[str] = None,
+        mine: bool = False,
     ) -> List[AIService]:
         rows = self._unwrap_list(self._get("v1/catalog/services", params={
             "q": q,
@@ -32,6 +102,7 @@ class CatalogClient:
             "offset": offset,
             "known_ids": known_ids or [],
             "known_fieldset": known_fieldset,
+            "mine": mine,
         }))
         return [AIService(**row) for row in rows]
 
@@ -54,14 +125,29 @@ class CatalogClient:
 
     def get_service(
         self,
-        id_or_name: str,
+        identifier: str,
         expand: Optional[List[str]] = None,
         fields: Optional[List[str]] = None,
         filters: Optional[List[str]] = None,
     ) -> Optional[AIService]:
-        row = self._get(f"v1/catalog/services/{id_or_name}", params={
+        """Fetch one catalog service by id, name, or ``owner/service``.
+
+        Default expand embeds ``deployments.contract``, platform ``endpoints`` and
+        ``models``. The call signature for ``run_service`` lives under
+        ``deployments[].contract.endpoints[].parameters``.
+
+        Args:
+            identifier: Service id or slug from ``search_services``.
+            expand: Override the default expand list.
+            fields: Sparse fieldset.
+            filters: Post-fetch filters.
+
+        Returns:
+            The service record, or ``None`` when not found or not visible.
+        """
+        row = self._get(f"v1/catalog/services/{identifier}", params={
             "filter": filters or [],
-            "expand": expand if expand is not None else ["deployments", "endpoints", "models"],
+            "expand": expand if expand is not None else SERVICE_DETAIL_EXPAND,
             "fields": fields or [],
         })
         return AIService(**row) if row else None
@@ -144,4 +230,35 @@ class CatalogClient:
             return self.query_models(q=query, filters=filters, limit=limit)
         if collection == "jobs":
             return self.query_jobs(q=query, filters=filters, visibility=visibility, limit=limit)
-        return self.query_services(q=query, filters=filters, limit=limit)
+        return self.search_services(query=query, filters=filters, limit=limit)
+
+
+def _service_matches_query(service: AIService, text: str) -> bool:
+    tokens = _query_tokens(text)
+    if not tokens:
+        return True
+    hay = _fold(" ".join(filter(None, (
+        getattr(service, "name", None),
+        getattr(service, "display_name", None),
+        getattr(service, "short_desc", None),
+        getattr(service, "description", None),
+    ))))
+    return all(token in hay for token in tokens)
+
+
+_QUERY_STOP = frozenset({
+    "a", "an", "the", "by", "for", "of", "and", "or", "to", "in", "on",
+    "image", "images", "video", "audio", "text", "generation", "generate",
+    "model", "models", "service", "services", "ai", "good", "best",
+})
+
+
+def _query_tokens(text: str) -> list[str]:
+    """Distinctive tokens. Drop filler so 'Labs image generation' still hits flux."""
+    raw = _fold(text).split()
+    kept = [token for token in raw if token not in _QUERY_STOP and len(token) > 2]
+    return kept or raw
+
+
+def _fold(value: str) -> str:
+    return re.sub(r"[^a-z0-9]+", " ", (value or "").lower()).strip()

socaity_cli-0.1.8/socaity_cli/clients/conversations.py

@@ -0,0 +1,81 @@
+"""Conversations facade (`/v1/conversations`)."""
+
+from typing import List, Optional
+
+from socaity_schemas.platform import Chat, ChatItem
+
+
+class ConversationsClient:
+    """Mixin: conversation metadata and items. Requires ``BackendHttp`` methods on ``self``."""
+
+    def list_conversations(
+        self,
+        q: Optional[str] = None,
+        filters: Optional[List[str]] = None,
+        expand: Optional[List[str]] = None,
+        fields: Optional[List[str]] = None,
+        sort: Optional[str] = None,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> List[Chat]:
+        """Conversations owned by the caller, newest activity first (fuzzy ``q`` via Typesense)."""
+        rows = self._unwrap_list(self._get("v1/conversations", params={
+            "q": q,
+            "filter": filters or [],
+            "expand": expand or [],
+            "fields": fields or [],
+            "sort": sort,
+            "limit": limit,
+            "offset": offset,
+        }))
+        return [Chat(**row) for row in rows]
+
+    def get_conversation(
+        self,
+        conversation_id: str,
+        expand: Optional[List[str]] = None,
+        fields: Optional[List[str]] = None,
+    ) -> Optional[Chat]:
+        """Fetch one conversation by id; relations omitted unless expanded."""
+        row = self._get(f"v1/conversations/{conversation_id}", params={
+            "expand": expand or [],
+            "fields": fields or [],
+        })
+        return Chat(**row) if row else None
+
+    def list_conversation_items(
+        self,
+        conversation_id: str,
+        branch: str = "active",
+        after: Optional[str] = None,
+        order: str = "asc",
+        filters: Optional[List[str]] = None,
+        limit: int = 100,
+    ) -> List[ChatItem]:
+        """Typed items of one conversation. ``branch=active`` walks the active chain; ``all`` is the full tree."""
+        rows = self._get(f"v1/conversations/{conversation_id}/items", params={
+            "branch": branch,
+            "after": after,
+            "order": order,
+            "filter": filters or [],
+            "limit": limit,
+        }) or []
+        return [ChatItem(**row) for row in rows]
+
+    def update_conversation(
+        self,
+        conversation_id: str,
+        title: Optional[str] = None,
+        status: Optional[str] = None,
+    ) -> Optional[Chat]:
+        """Patch title and/or status on a conversation the caller owns."""
+        row = self._request(
+            "PATCH",
+            f"v1/conversations/{conversation_id}",
+            params={"title": title, "status": status},
+        )
+        return Chat(**row) if row else None
+
+    def delete_conversation(self, conversation_id: str) -> bool:
+        """Soft-delete a conversation and clear its linked job data."""
+        return bool(self._request("DELETE", f"v1/conversations/{conversation_id}"))