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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: socaity-cli
-Version: 0.1.7
+Version: 0.1.9
 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.9}/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.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "socaity-cli"
-version = "0.1.7"
+version = "0.1.9"
 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.9}/socaity_cli/backend_client.py

@@ -1,11 +1,15 @@
-"""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.profile import ProfileClient
 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 +22,10 @@ class SocaityBackendClient(
     FilesClient,
     SdkInstallClient,
     DeploymentClient,
+    ConversationsClient,
+    InterruptsClient,
+    WorkflowsClient,
+    ProfileClient,
 ):
     """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.9}/socaity_cli/cli.py

@@ -3,18 +3,20 @@
 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:
     client = SocaityBackendClient()
     if entity == "services":
-        services = client.list_services(category=category, limit=limit)
+        services = client.query_services(category=category, limit=limit)
         if not services:
             print("No services found.")
             return
@@ -24,7 +26,7 @@ def _run_list(entity: str, category: str | None, family: str | None, limit: int)
             desc = f" - {service.short_desc}" if service.short_desc else ""
             print(f"{name}{official}{desc}")
     else:
-        models = client.list_models(family=family, limit=limit)
+        models = client.query_models(family=family, limit=limit)
         if not models:
             print("No models found.")
             return
@@ -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.query_workflows(q=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)
@@ -101,7 +224,12 @@ def _run_search(query: str, collections: str | None, limit: int) -> None:
     targets = [part.strip() for part in (collections or "services,models").split(",") if part.strip()]
     found = False
     for collection in targets:
-        hits = client.search(query, collection=collection, limit=limit)
+        if collection == "models":
+            hits = client.query_models(q=query, limit=limit)
+        elif collection == "jobs":
+            hits = client.query_jobs(q=query, limit=limit)
+        else:
+            hits = client.query_services(q=query, limit=limit)
         if not hits:
             continue
         found = True
@@ -137,7 +265,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 +274,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 +336,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 +412,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 +506,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.9}/socaity_cli/clients/__init__.py

@@ -3,16 +3,24 @@ from socaity_cli.clients.analytics import AnalyticsClient
 from socaity_cli.clients.catalog import CatalogClient
 from socaity_cli.clients.deployment import DeploymentClient
 from socaity_cli.clients.files import FilesClient
+from socaity_cli.clients.conversations import ConversationsClient
+from socaity_cli.clients.interrupts import InterruptsClient
 from socaity_cli.clients.jobs import JobsClient
+from socaity_cli.clients.profile import ProfileClient
 from socaity_cli.clients.projects import ProjectsClient
 from socaity_cli.clients.sdk_install import SdkInstallClient
+from socaity_cli.clients.workflows import WorkflowsClient
 
 __all__ = [
     "AnalyticsClient",
     "CatalogClient",
+    "ConversationsClient",
     "DeploymentClient",
     "FilesClient",
+    "InterruptsClient",
     "JobsClient",
+    "ProfileClient",
     "ProjectsClient",
     "SdkInstallClient",
+    "WorkflowsClient",
 ]

socaity_cli-0.1.9/socaity_cli/clients/catalog.py

@@ -0,0 +1,224 @@
+"""AI catalog reads (`/v1/catalog`)."""
+import re
+from typing import List, Optional
+
+from socaity_schemas.platform import AIModel, AIService, 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 query/get. Requires ``BackendHttp`` methods on ``self``."""
+
+    SERVICE_DETAIL_EXPAND = SERVICE_DETAIL_EXPAND
+
+    def query_services(
+        self,
+        q: 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 = 100,
+        offset: int = 0,
+        known_ids: Optional[List[str]] = None,
+        known_fieldset: Optional[str] = None,
+        mine: bool = False,
+    ) -> List[AIService]:
+        """Query AI services in the socaity catalog.
+
+        Start here for any generation task. Query by capability ("text to image",
+        "voice cloning") or browse with filters. Results are slim catalog rows;
+        call ``get_service`` with a hit ``id`` for endpoints and the call
+        signature under ``deployments.contract``.
+
+        Args:
+            q: Free-text query. Omit to browse.
+            category: Category id (not display name). Appended as a filter.
+            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.
+            known_ids: Client cache ids for delta fetch.
+            known_fieldset: Client cache fieldset for delta fetch.
+            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._unwrap_list(self._get("v1/catalog/services", params={
+            "q": q,
+            "filter": service_filters,
+            "expand": expand or [],
+            "fields": fields if fields is not None else SERVICE_LIST_FIELDS,
+            "sort": sort,
+            "limit": limit,
+            "offset": offset,
+            "known_ids": known_ids or [],
+            "known_fieldset": known_fieldset,
+            "mine": mine,
+        }))
+        services = [AIService(**row) for row in rows]
+        # 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 q and not mine:
+            matched = [row for row in services if _service_matches_query(row, q)]
+            if matched:
+                return matched[:limit]
+            browsed = self._unwrap_list(self._get("v1/catalog/services", params={
+                "filter": service_filters,
+                "expand": expand or [],
+                "fields": fields if fields is not None else SERVICE_LIST_FIELDS,
+                "sort": sort,
+                "limit": max(limit, 100),
+                "offset": 0,
+                "mine": mine,
+            }))
+            browsed_services = [AIService(**row) for row in browsed]
+            return [row for row in browsed_services if _service_matches_query(row, q)][:limit]
+        return services
+
+    def get_service(
+        self,
+        identifier: str,
+        expand: Optional[List[str]] = None,
+        fields: Optional[List[str]] = None,
+        filters: Optional[List[str]] = None,
+    ) -> Optional[AIService]:
+        """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 ``query_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 SERVICE_DETAIL_EXPAND,
+            "fields": fields or [],
+        })
+        return AIService(**row) if row else None
+
+    def query_models(
+        self,
+        q: Optional[str] = None,
+        family: Optional[str] = None,
+        task: 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,
+        known_ids: Optional[List[str]] = None,
+        known_fieldset: Optional[str] = None,
+    ) -> List[AIModel]:
+        """Query AI models in the catalog.
+
+        Args:
+            q: Free-text query. Omit to browse.
+            family: Model family, e.g. ``flux``. Appended as a filter.
+            task: Task slug, e.g. ``text2image``. Appended as a filter.
+            filters: Repeatable ``field:operator:value`` strings.
+            expand: Relations to embed (``scores``, ``capabilities``).
+            fields: Sparse fieldset.
+            sort: ``field:asc`` or ``field:desc``.
+            limit: Page size.
+            offset: Skip this many rows.
+            known_ids: Client cache ids for delta fetch.
+            known_fieldset: Client cache fieldset for delta fetch.
+
+        Returns:
+            Model rows, or an empty list when nothing matches.
+        """
+        model_filters = list(filters or [])
+        if family:
+            model_filters.append(f"family:eq:{family}")
+        if task:
+            model_filters.append(f"tasks:contains:{task}")
+        rows = self._unwrap_list(self._get("v1/catalog/models", params={
+            "q": q,
+            "filter": model_filters,
+            "expand": expand or [],
+            "fields": fields if fields is not None else MODEL_LIST_FIELDS,
+            "sort": sort,
+            "limit": limit,
+            "offset": offset,
+            "known_ids": known_ids or [],
+            "known_fieldset": known_fieldset,
+        }))
+        return [AIModel(**row) for row in rows]
+
+    def get_model(
+        self,
+        id_or_name: str,
+        expand: Optional[List[str]] = None,
+        fields: Optional[List[str]] = None,
+    ) -> Optional[AIModel]:
+        row = self._get(f"v1/catalog/models/{id_or_name}", params={
+            "expand": expand if expand is not None else ["scores"],
+            "fields": fields or [],
+        })
+        return AIModel(**row) if row else None
+
+    def query_categories(self) -> List[ServiceCategory]:
+        """Query catalog task categories."""
+        rows = self._get("v1/catalog/categories") or []
+        if isinstance(rows, dict):
+            rows = rows.get("entities") or rows.get("data") or []
+        return [ServiceCategory(**row) for row in rows]
+
+    def list_pricing_rules(self, active_only: bool = True) -> List[dict]:
+        rows = self._get("v1/catalog/pricing-rules", params={"active_only": active_only}) or []
+        if isinstance(rows, dict):
+            rows = rows.get("entities") or rows.get("data") or []
+        return rows if isinstance(rows, list) else []
+
+
+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()