ellf-cli 4.0.96__tar.gz → 4.0.100__tar.gz

{ellf_cli-4.0.96/ellf_cli.egg-info → ellf_cli-4.0.100}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ellf-cli
-Version: 4.0.96
+Version: 4.0.100
 Summary: Ellf Command Line Interface
 Home-page: https://prodi.gy
 Author: ExplosionAI GmbH

{ellf_cli-4.0.96 → ellf_cli-4.0.100}/README.md

@@ -795,7 +795,7 @@ List all projects
 
 | Argument | Type | Description | Default |
 | --- | --- | --- | --- |
-| `--select` | `list[str]` | Comma-separated fields to select and show in output. Available: ['id', 'created', 'updated', 'org_id', 'name', 'description', 'default_job_name_template'] | `['id', 'name']` |
+| `--select` | `list[str]` | Comma-separated fields to select and show in output. Available: ['id', 'created', 'updated', 'org_id', 'name', 'slug', 'description', 'default_job_name_template'] | `['slug', 'name']` |
 | `--name` | `str` | Filter by name | `None` |
 | `--json` | `bool` | Output the result as JSON | `False` |
 
@@ -806,7 +806,7 @@ Get detailed info for a project
 | Argument | Type | Description | Default |
 | --- | --- | --- | --- |
 | `name_or_id` | `Union[str, UUID]` | Name or ID of the project |  |
-| `--select` | `list[str]` | Comma-separated fields to select and show in output. Available: ['id', 'created', 'updated', 'org_id', 'name', 'description', 'default_job_name_template'] | `None` |
+| `--select` | `list[str]` | Comma-separated fields to select and show in output. Available: ['id', 'created', 'updated', 'org_id', 'name', 'slug', 'description', 'default_job_name_template'] | `None` |
 | `--json` | `bool` | Output the result as JSON | `False` |
 
 #### `ellf projects create`

{ellf_cli-4.0.96 → ellf_cli-4.0.100}/ellf_cli/about.json

@@ -1,7 +1,7 @@
 {
   "title": "Ellf CLI",
   "name": "ellf-cli",
-  "version": "4.0.96",
+  "version": "4.0.100",
   "summary": "Ellf Command Line Interface",
   "uri": "https://prodi.gy",
   "prog": "ellf",

{ellf_cli-4.0.96 → ellf_cli-4.0.100}/ellf_cli/commands/projects.py

@@ -39,7 +39,7 @@ logger = logging.getLogger(__name__)
     # fmt: on
 )
 def list(
-    select: builtins.list[str] = ["id", "name"],
+    select: builtins.list[str] = ["slug", "name"],
     name: Optional[str] = None,
     as_json: bool = False,
 ) -> Sequence[ProjectSummary]:
@@ -108,7 +108,7 @@ def create(
     except EllfErrors.ProjectInvalid:
         raise CLIError(Messages.E004.format(noun="project", name=name))
     print_mutation_result(
-        {"id": str(res.id), "name": res.name},
+        {"slug": res.slug, "id": str(res.id), "name": res.name},
         Messages.T002.format(noun="project", name=res.name),
         as_json=as_json,
     )
@@ -147,7 +147,7 @@ def update(
     )
     res = auth.client.project.update(body)
     print_mutation_result(
-        {"id": str(res.id), "name": res.name},
+        {"slug": res.slug, "id": str(res.id), "name": res.name},
         Messages.T051.format(noun="project", name=res.name),
         as_json=as_json,
     )

{ellf_cli-4.0.96 → ellf_cli-4.0.100}/ellf_cli/ellf.json

@@ -1,7 +1,7 @@
 {
   "prog": "ellf",
   "help": "Ellf Command Line Interface.",
-  "version": "4.0.95",
+  "version": "4.0.99",
   "extra_key": "_extra",
   "commands": {
     "actions": {
@@ -204,7 +204,7 @@
           "orig_type": "bool"
         }
       ],
-      "description": "\n    Log in to your Ellf account. You normally don't need to call this\n    manually. It will automatically authenticate when needed.\n    ",
+      "description": "\nLog in to your Ellf account. You normally don't need to call this\nmanually. It will automatically authenticate when needed.\n",
       "allow_extra": false,
       "parent": null,
       "is_placeholder": false
@@ -257,7 +257,7 @@
           "orig_type": "Literal[api, cluster, id, ci]"
         }
       ],
-      "description": "\n    Return an auth token for the current user\n    ",
+      "description": "\nReturn an auth token for the current user\n",
       "allow_extra": false,
       "parent": null,
       "is_placeholder": false
@@ -333,7 +333,7 @@
           "orig_type": "list[Literal[tasks, actions, assets, datasets, paths]]"
         }
       ],
-      "description": "\n    Save the state of the current app JSON file. If an assets directory is\n    provided, assets will be downloaded and referenced in the JSON accordingly.\n    ",
+      "description": "\nSave the state of the current app JSON file. If an assets directory is\nprovided, assets will be downloaded and referenced in the JSON accordingly.\n",
       "allow_extra": false,
       "parent": null,
       "is_placeholder": false
@@ -368,7 +368,7 @@
           "orig_type": "bool"
         }
       ],
-      "description": "\n    Populate Ellf with data for projects, tasks, actions, assets and paths.\n    ",
+      "description": "\nPopulate Ellf with data for projects, tasks, actions, assets and paths.\n",
       "allow_extra": false,
       "parent": null,
       "is_placeholder": false
@@ -445,7 +445,7 @@
             "orig_type": "List[str]"
           }
         ],
-        "description": "\n    Create a new action. The available action recipes are fetched from your\n    cluster and are added as dynamic subcommands. You can see more details\n    and available arguments by calling the subcommand with --help, e.g. create\n    [name] --help\n    ",
+        "description": "\nCreate a new action. The available action recipes are fetched from your\ncluster and are added as dynamic subcommands. You can see more details\nand available arguments by calling the subcommand with --help, e.g. create\n[name] --help\n",
         "allow_extra": true,
         "parent": "actions",
         "is_placeholder": false
@@ -480,7 +480,7 @@
             "orig_type": "bool"
           }
         ],
-        "description": "\n    List the actions on the cluster. By default, this includes their ID, name\n    and current state, e.g. created or completed\n    ",
+        "description": "\nList the actions on the cluster. By default, this includes their ID, name\nand current state, e.g. created or completed\n",
         "allow_extra": false,
         "parent": "actions",
         "is_placeholder": false
@@ -926,7 +926,7 @@
             "orig_type": "List[str]"
           }
         ],
-        "description": "\n    Create a new agent. The available agent recipes are fetched from your\n    cluster and are added as dynamic subcommands. You can see more details\n    and available arguments by calling the subcommand with --help, e.g. create\n    [name] --help\n    ",
+        "description": "\nCreate a new agent. The available agent recipes are fetched from your\ncluster and are added as dynamic subcommands. You can see more details\nand available arguments by calling the subcommand with --help, e.g. create\n[name] --help\n",
         "allow_extra": true,
         "parent": "agents",
         "is_placeholder": false
@@ -1035,7 +1035,7 @@
             "orig_type": "bool"
           }
         ],
-        "description": "\n    List the agents on the cluster. By default, this includes their ID, name\n    and current state, e.g. created or completed\n    ",
+        "description": "\nList the agents on the cluster. By default, this includes their ID, name\nand current state, e.g. created or completed\n",
         "allow_extra": false,
         "parent": "agents",
         "is_placeholder": false
@@ -1529,7 +1529,7 @@
             "orig_type": "bool"
           }
         ],
-        "description": "\n    Get detailed info for an asset uploaded to the cluster and registered\n    with Ellf\n    ",
+        "description": "\nGet detailed info for an asset uploaded to the cluster and registered\nwith Ellf\n",
         "allow_extra": false,
         "parent": "assets",
         "is_placeholder": false
@@ -1629,7 +1629,7 @@
             "orig_type": "bool"
           }
         ],
-        "description": "\n    Create an asset on the cluster and register it with Ellf. Assets\n    point to files or directories you control. The Ellf server only has\n    a reference to them. This command doesn't transfer any data. See `ellf files`\n    for utilities to transfer files to and from your cluster\n    ",
+        "description": "\nCreate an asset on the cluster and register it with Ellf. Assets\npoint to files or directories you control. The Ellf server only has\na reference to them. This command doesn't transfer any data. See `ellf files`\nfor utilities to transfer files to and from your cluster\n",
         "allow_extra": false,
         "parent": "assets",
         "is_placeholder": false
@@ -1858,7 +1858,7 @@
             "orig_type": "Union[str, UUID]"
           }
         ],
-        "description": "\n    Delete a cluster from PAM. This only removes PAM's record\n    of it. The cluster itself will continue to exist - you need\n    to shut it down separately.\n    ",
+        "description": "\nDelete a cluster from PAM. This only removes PAM's record\nof it. The cluster itself will continue to exist - you need\nto shut it down separately.\n",
         "allow_extra": false,
         "parent": "clusters",
         "is_placeholder": false
@@ -1945,7 +1945,7 @@
             "orig_type": "bool"
           }
         ],
-        "description": "Check the health of a cluster deployment.\n\n    Runs CLI-side connectivity checks against the cluster and PAM.\n    Use --deep to also trigger cluster-side deployment checks (K8s API,\n    NFS, database, etc.).\n    ",
+        "description": "Check the health of a cluster deployment.\n\nRuns CLI-side connectivity checks against the cluster and PAM.\nUse --deep to also trigger cluster-side deployment checks (K8s API,\nNFS, database, etc.).\n",
         "allow_extra": false,
         "parent": "clusters",
         "is_placeholder": false
@@ -2028,7 +2028,7 @@
             "orig_type": "str"
           }
         ],
-        "description": "Rotate the cluster RSA keypair.\n\n    Generates a new keypair, updates the cluster record in PAM with the\n    new public key, patches the K8s secret with the new private key,\n    and restarts the cluster deployment.\n    ",
+        "description": "Rotate the cluster RSA keypair.\n\nGenerates a new keypair, updates the cluster record in PAM with the\nnew public key, patches the K8s secret with the new private key,\nand restarts the cluster deployment.\n",
         "allow_extra": false,
         "parent": "clusters",
         "is_placeholder": false
@@ -2813,7 +2813,7 @@
             "orig_type": "str"
           }
         ],
-        "description": "Export all the examples from a dataset and save it in the designated file as\n    JSONL (newline-delimited JSON).\n    ",
+        "description": "Export all the examples from a dataset and save it in the designated file as\nJSONL (newline-delimited JSON).\n",
         "allow_extra": false,
         "parent": "datasets",
         "is_placeholder": false
@@ -3248,7 +3248,7 @@
             "orig_type": "bool"
           }
         ],
-        "description": "Deploy or upgrade the Ellf Helm chart.\n\n    Creates the namespace, image pull secret, cluster keypair secret,\n    then runs helm upgrade --install with the provided values.\n    ",
+        "description": "Deploy or upgrade the Ellf Helm chart.\n\nCreates the namespace, image pull secret, cluster keypair secret,\nthen runs helm upgrade --install with the provided values.\n",
         "allow_extra": false,
         "parent": "infra",
         "is_placeholder": false
@@ -3492,7 +3492,7 @@
             "orig_type": "str"
           }
         ],
-        "description": "Install cluster infrastructure prerequisites (Traefik, cert-manager).\n\n    These operations are idempotent and safe to re-run.\n    ",
+        "description": "Install cluster infrastructure prerequisites (Traefik, cert-manager).\n\nThese operations are idempotent and safe to re-run.\n",
         "allow_extra": false,
         "parent": "infra",
         "is_placeholder": false
@@ -3775,7 +3775,7 @@
             "orig_type": "str"
           }
         ],
-        "description": "Manage TLS certificates for local cluster access.\n\n    Use --self-signed when you have direct kubectl access to the cluster.\n    Use --setup HOST to do everything from your laptop over SSH.\n    Use --trust HOST to fetch and install an existing CA from a remote cluster.\n    ",
+        "description": "Manage TLS certificates for local cluster access.\n\nUse --self-signed when you have direct kubectl access to the cluster.\nUse --setup HOST to do everything from your laptop over SSH.\nUse --trust HOST to fetch and install an existing CA from a remote cluster.\n",
         "allow_extra": false,
         "parent": "infra",
         "is_placeholder": false
@@ -3799,7 +3799,7 @@
             "orig_type": "str"
           }
         ],
-        "description": "\n    Run a job directly on the cluster from a YAML spec file, bypassing PAM.\n    ",
+        "description": "\nRun a job directly on the cluster from a YAML spec file, bypassing PAM.\n",
         "allow_extra": false,
         "parent": "jobs",
         "is_placeholder": false
@@ -4547,9 +4547,9 @@
             "id": "select",
             "option": "--select",
             "short": null,
-            "orig_help": "Comma-separated fields to select and show in output. Available: ['id', 'created', 'updated', 'org_id', 'name', 'description', 'default_job_name_template']",
-            "default": "['id', 'name']",
-            "help": "Comma-separated fields to select and show in output. Available: ['id', 'created', 'updated', 'org_id', 'name', 'description', 'default_job_name_template'] (list[str])",
+            "orig_help": "Comma-separated fields to select and show in output. Available: ['id', 'created', 'updated', 'org_id', 'name', 'slug', 'description', 'default_job_name_template']",
+            "default": "['slug', 'name']",
+            "help": "Comma-separated fields to select and show in output. Available: ['id', 'created', 'updated', 'org_id', 'name', 'slug', 'description', 'default_job_name_template'] (list[str])",
             "action": null,
             "choices": null,
             "has_converter": true,
@@ -4608,9 +4608,9 @@
             "id": "select",
             "option": "--select",
             "short": null,
-            "orig_help": "Comma-separated fields to select and show in output. Available: ['id', 'created', 'updated', 'org_id', 'name', 'description', 'default_job_name_template']",
+            "orig_help": "Comma-separated fields to select and show in output. Available: ['id', 'created', 'updated', 'org_id', 'name', 'slug', 'description', 'default_job_name_template']",
             "default": null,
-            "help": "Comma-separated fields to select and show in output. Available: ['id', 'created', 'updated', 'org_id', 'name', 'description', 'default_job_name_template'] (list[str])",
+            "help": "Comma-separated fields to select and show in output. Available: ['id', 'created', 'updated', 'org_id', 'name', 'slug', 'description', 'default_job_name_template'] (list[str])",
             "action": null,
             "choices": null,
             "has_converter": true,
@@ -4877,7 +4877,7 @@
             "orig_type": "str"
           }
         ],
-        "description": "\n    Upload and advertise a recipes package from your Python environment.\n    ",
+        "description": "\nUpload and advertise a recipes package from your Python environment.\n",
         "allow_extra": false,
         "parent": "publish",
         "is_placeholder": false
@@ -4990,7 +4990,7 @@
             "orig_type": "bool"
           }
         ],
-        "description": "\n    Transfer data to the cluster, and advertise it to Ellf.\n\n    These steps can also be done separately. See `ellf files` to transfer\n    data to the cluster without creating an Asset record for it, and\n    `ellf assets create` to create an Asset without transfer.\n    ",
+        "description": "\nTransfer data to the cluster, and advertise it to Ellf.\n\nThese steps can also be done separately. See `ellf files` to transfer\ndata to the cluster without creating an Asset record for it, and\n`ellf assets create` to create an Asset without transfer.\n",
         "allow_extra": false,
         "parent": "publish",
         "is_placeholder": false
@@ -5663,7 +5663,7 @@
             "orig_type": "List[str]"
           }
         ],
-        "description": "\n    Create a new task. The available task recipes are fetched from your\n    cluster and are added as dynamic subcommands. You can see more details\n    and available arguments by calling the subcommand with --help, e.g. create\n    [name] --help\n    ",
+        "description": "\nCreate a new task. The available task recipes are fetched from your\ncluster and are added as dynamic subcommands. You can see more details\nand available arguments by calling the subcommand with --help, e.g. create\n[name] --help\n",
         "allow_extra": true,
         "parent": "tasks",
         "is_placeholder": false
@@ -5698,7 +5698,7 @@
             "orig_type": "bool"
           }
         ],
-        "description": "\n    List the tasks on the cluster. By default, this includes their ID, name\n    and current state, e.g. created or completed\n    ",
+        "description": "\nList the tasks on the cluster. By default, this includes their ID, name\nand current state, e.g. created or completed\n",
         "allow_extra": false,
         "parent": "tasks",
         "is_placeholder": false
@@ -6129,7 +6129,7 @@
             "orig_type": "bool"
           }
         ],
-        "description": "Fetch a batch of questions from a running annotation task.\n\n    Mirrors the web app: asks the broker for a Prodigy login token, then talks\n    to the task pod directly via its public task_url. Note that requesting a\n    batch reserves those questions for this CLI's session \u2014 they will not be\n    handed to other annotators until they are answered or another session\n    runs out of work and steals them.\n    ",
+        "description": "Fetch a batch of questions from a running annotation task.\n\nMirrors the web app: asks the broker for a Prodigy login token, then talks\nto the task pod directly via its public task_url. Note that requesting a\nbatch reserves those questions for this CLI's session \u2014 they will not be\nhanded to other annotators until they are answered or another session\nruns out of work and steals them.\n",
         "allow_extra": false,
         "parent": "tasks",
         "is_placeholder": false

{ellf_cli-4.0.96 → ellf_cli-4.0.100}/ellf_cli/ellf_skills/skills/ellf-monitor.assistant/SKILL.md

@@ -75,19 +75,29 @@ If follow-up action is needed, route to `/ellf-ops` or `/ellf-handoff`.
 
 ### Annotation tasks
 
-Use cluster calls such as:
+Use cluster calls for job status and per-dataset counts; use PAM for dataset
+discovery:
 ```text
 mcp__cluster__cluster_request(method="GET", path="/api/v1/jobs/{id}/status")
-mcp__cluster__cluster_request(method="GET", path="/api/v1/datasets/example-count", query={"dataset": "<name>"})
+mcp__pam__dataset_list(cluster_id="<id>")               # discover datasets (org-wide, registered with PAM)
+mcp__cluster__dataset_example_count(name="<name>")      # total examples in the dataset (per-cluster, via broker)
+mcp__cluster__dataset_session_counts(name="<name>")     # per-annotator breakdown (keys are session_ids; null = bulk import)
 ```
 
+`dataset_list` is a PAM read (org-wide registry), while the count tools talk to
+the broker because example counts live in the per-cluster Prodigy database.
+All three are read-only and do not require user confirmation. They do not
+read annotation contents — only counts and metadata.
+
 Read when needed:
 - `${CLAUDE_SKILL_DIR}/references/annotation_metrics.md`
 
 Report:
 - task state
 - whether the task appears reachable and healthy
-- annotation count
+- annotation count (from `dataset_example_count`)
+- per-annotator activity (from `dataset_session_counts`) when the user asks
+  who annotated what or about active annotators
 - dataset growth
 - whether agent assignment appears to be producing data if applicable
 

{ellf_cli-4.0.96/ellf_cli/ellf_skills/skills/ellf-monitor.coding → ellf_cli-4.0.100/ellf_cli/ellf_skills/skills/ellf-monitor.assistant}/references/annotation_metrics.md

@@ -4,10 +4,13 @@ Use this reference to interpret annotation activity and quality signals.
 
 ## What to watch
 
-- Total annotation count
-- Dataset growth over time
-- Number of active annotators or agents
-- Whether a running task is producing new examples
+- Total annotation count — from `mcp__cluster__dataset_example_count`
+- Dataset growth over time — compare counts across checks
+- Number of active annotators or agents — from `mcp__cluster__dataset_session_counts`
+  (each non-null key is a session_id; `null` means examples written directly via
+  `db-in` rather than through an annotation session)
+- Whether a running task is producing new examples — combine job status with
+  example count over time
 
 ## Warning signals
 

{ellf_cli-4.0.96 → ellf_cli-4.0.100}/ellf_cli/query.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import time
 from collections.abc import Callable, Iterable
-from typing import Literal, TypeVar, Union
+from typing import Any, Literal, TypeVar, Union, cast
 from uuid import UUID
 
 import httpx
@@ -384,9 +384,8 @@ def _resolve_id(
     name_or_id: str | UUID,
     params: dict[str, str | UUID | None],
 ) -> UUID:
-    """Resolve reference to a Ellf Entity by name or ID.
-    If an ID is given, return it. If it's a name,
-    look up the ID.
+    """Resolve reference to a Ellf Entity by UUID, slug, or name.
+    If an ID is given, return it. Otherwise try slug then name.
     """
     if isinstance(name_or_id, UUID):
         return name_or_id
@@ -397,12 +396,11 @@ def _resolve_id(
     auth = get_auth_state()
     model_client = getattr(auth.client, model_name)
     NotFound = get_not_found_error(model_name)
-    try:
-        res = model_client.read(name=name_or_id, **params)
-        return res.id
-    except NotFound:
+    res = _read_by_slug_or_name(model_client, str(name_or_id), params, NotFound)
+    if res is None:
         err = Messages.E038.format(noun=model_name, name_or_id=name_or_id)
         raise CLIError(err, params)
+    return cast(UUID, res.id)  # type: ignore[attr-defined]
 
 
 def _resolve_object(
@@ -410,9 +408,13 @@ def _resolve_object(
     name_or_id: str | UUID,
     params: dict[str, str | UUID | None],
 ) -> BaseModel:
-    """Resolve reference to a Ellf Entity by name or ID.
-    If an ID is given, use it for an id query, otherwise, query by
-    the entity name
+    """Resolve reference to a Ellf Entity by UUID, slug, or name.
+
+    UUIDs are detected by parsing. Otherwise we try the input as a slug
+    first (globally unique), then fall back to name (scoped). The slug
+    branch is silently skipped for SDK clients that don't yet expose
+    a slug field on their Reading model — older deployments stay
+    name-resolvable.
     """
     auth = get_auth_state()
     model_client = getattr(auth.client, model_name)
@@ -432,14 +434,37 @@ def _resolve_object(
             err = Messages.E038.format(noun=model_name, name_or_id=name_or_id)
             raise CLIError(err, params)
     else:
-        try:
-            res = model_client.read(name=name_or_id, **params)
-        except NotFound:
+        res = _read_by_slug_or_name(model_client, str(name_or_id), params, NotFound)
+        if res is None:
             err = Messages.E038.format(noun=model_name, name_or_id=name_or_id)
             raise CLIError(err, params)
     return res
 
 
+def _read_by_slug_or_name(
+    model_client: Any,
+    value: str,
+    params: dict[str, str | UUID | None],
+    not_found_exc: type[BaseException],
+) -> BaseModel | None:
+    """Try slug lookup first, then name. Return None if neither matches.
+
+    Slug lookup is only attempted when the SDK's Reading schema for this
+    resource declares a ``slug`` field; without it the request would fail
+    schema validation client-side before ever leaving the process.
+    """
+    reading_cls = getattr(model_client, "Reading", None)
+    if reading_cls is not None and "slug" in getattr(reading_cls, "model_fields", {}):
+        try:
+            return model_client.read(slug=value, **params)
+        except not_found_exc:
+            pass
+    try:
+        return model_client.read(name=value, **params)
+    except not_found_exc:
+        return None
+
+
 def _resolve_latest_object(
     model_name: str,
     name_or_id: str | UUID,

{ellf_cli-4.0.96 → ellf_cli-4.0.100/ellf_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ellf-cli
-Version: 4.0.96
+Version: 4.0.100
 Summary: Ellf Command Line Interface
 Home-page: https://prodi.gy
 Author: ExplosionAI GmbH