From 69bbad98d1f4fbcb4438ce8b3ed06789ab39b2bd Mon Sep 17 00:00:00 2001 From: Volv G Date: Sat, 4 Jul 2026 20:36:15 -0700 Subject: [PATCH] docs: prefer published tangle-cli in tangent skills Assisted-By: devx/9c4ad24f-24d3-4eb9-8747-dbf53e3221df --- skills/tangent/OSS-CONVENTIONS.md | 43 ++++--- skills/tangent/PORT-README.md | 4 +- skills/tangent/SKILL.md | 8 +- skills/tangent/agents/auth-wizard.md | 10 +- skills/tangent/agents/builder.md | 66 +++++------ skills/tangent/agents/debugger.md | 53 ++++----- skills/tangent/agents/reporter.md | 10 +- skills/tangent/agents/researcher.md | 26 ++--- skills/tangent/agents/reviewer.md | 27 ++--- skills/tangent/agents/scenario-builder.md | 9 +- skills/tangent/references/data-sources.md | 8 +- .../example-scenarios/01-mslr-ranking.md | 16 +-- .../02-text-classification.md | 12 +- .../references/example-scenarios/INDEX.md | 2 +- .../tangent/references/iterating-on-runs.md | 22 ++-- skills/tangent/references/secrets.md | 32 ++--- skills/tangent/references/setup.md | 42 ++++--- .../tangent/references/step-0-initialize.md | 27 +++-- skills/tangent/references/step-3-submit.md | 18 +-- skills/tangent/references/step-4-monitor.md | 12 +- skills/tangent/references/step-5-evaluate.md | 4 +- skills/tangent/references/tangle-tools.md | 110 +++++++++--------- .../tangent/references/uploading-artifacts.md | 22 ++-- tests/test_packaging.py | 3 + 24 files changed, 292 insertions(+), 294 deletions(-) diff --git a/skills/tangent/OSS-CONVENTIONS.md b/skills/tangent/OSS-CONVENTIONS.md index 617f66c..495add2 100644 --- a/skills/tangent/OSS-CONVENTIONS.md +++ b/skills/tangent/OSS-CONVENTIONS.md @@ -19,34 +19,32 @@ and `api`) and **never** any internal wrapper/hook layer. ## 1. Invocation rule -**Keep checkout/dev invocation separate from installed-tool invocation.** - -From a checkout of the `tangle-cli` repo, run commands through the workspace: - -```bash -uv run tangle quickstart -uv run tangle --help -uv run tangle sdk --help -uv run tangle api --help -``` +**Published-package usage is the default; checkout usage is for local `tangle-cli` development/validation.** For a persistent user-level CLI install, prefer uv tools: ```bash uv tool install tangle-cli tangle quickstart -tangle-cli --help +tangle --help +tangle sdk --help +tangle api --help ``` For one-off execution without a persistent install, use `uvx`: ```bash uvx --from tangle-cli tangle --help +uvx --from tangle-cli tangle quickstart ``` Generic Python environments may also use `pip install tangle-cli`; use `uv pip install tangle-cli` only inside an explicitly managed virtualenv. +When intentionally validating a local checkout of the `tangle-cli` repo, prefix +examples with `uv run` (for example, `uv run tangle quickstart`). Skill examples +otherwise use the installed-tool form (`tangle …` / `tangle-cli …`). + - **Never** prefix a command with an internal env-shim exec wrapper. That internal dev-env tooling must not appear in any ported file. - `tangle-cli` is a public PyPI package. The default install includes the @@ -74,7 +72,7 @@ OSS replacement. **Verbs/flags below were verified against the `tangle-cli` sour | Internal | OSS | |---|---| -| ` -- …` | `uv run tangle …` from a checkout, or installed `tangle …` / `tangle-cli …` | +| ` -- …` | `tangle …` / `tangle-cli …` (or `uv run tangle …` only when validating a local checkout) | | ` quickstart` | `tangle quickstart` (real; static onboarding text) | | `--help-extended` / `--help-full` | `--help` | | `from import TangleApiClient` | `from tangle_cli.client import TangleApiClient` (see §3) | @@ -142,9 +140,9 @@ OSS replacement. **Verbs/flags below were verified against the `tangle-cli` sour | `--run-as IDENTITY` | `--run-as` exists on `submit` but the **OSS default hooks do not support it** (downstream extension seam only). Drop run-as examples (§10, D9). | **Invocation rule for the whole table:** every left-column command, however it was -written internally, becomes the right-column form prefixed with `uv run` (e.g. -`uv run tangle sdk pipeline-runs submit …`). Auth flags from §4 attach to any -API-backed command. +written internally, becomes the bare right-column form (for example, +`tangle sdk pipeline-runs submit …`). Only prefix with `uv run` when intentionally +validating a local checkout. Auth flags from §4 attach to any API-backed command. --- @@ -214,13 +212,14 @@ internal backend's auth verification, and the internal package index **entirely* - **Run links:** replace internal run-URL links (`https:///runs/`) with `/runs/` **or** "inspect via `tangle sdk pipeline-runs details RUN_ID`". - **No internal package index.** Resolve dependencies against public PyPI - (`uv sync` from a checkout, `uv tool install tangle-cli` for a persistent CLI, - or `uvx --from tangle-cli tangle …` for one-off execution). Generic Python - environments may also use `pip install tangle-cli`. + (`uv tool install tangle-cli` for a persistent CLI, or + `uvx --from tangle-cli tangle …` for one-off execution). Generic Python + environments may also use `pip install tangle-cli`; local checkout validation + uses `uv sync` / `uv run` inside the repo. - Example for a protected backend: ```bash - uv run tangle sdk pipeline-runs submit pipeline.yaml \ + tangle sdk pipeline-runs submit pipeline.yaml \ --base-url https://api.example \ --auth-header 'Bearer …' \ -H 'X-Gateway-Auth: …' \ @@ -257,11 +256,11 @@ records of the form `{id, uri, size, hash}` (and a `count`); the `uri` is 1. Get metadata and read the `uri`: ```bash - uv run tangle sdk artifacts get RUN_ID -q '{"artifact_ids":[""]}' + tangle sdk artifacts get RUN_ID -q '{"artifact_ids":[""]}' ``` 2. Ask the backend for a signed URL: ```bash - uv run tangle api artifacts signed-artifact-url --id + tangle api artifacts signed-artifact-url --id ``` 3. Fetch with a generic client — `curl -L "" -o ./out`, or for `hf://` URIs `huggingface_hub` (`hf_hub_download` / `snapshot_download`). @@ -317,7 +316,7 @@ selectors, and auth env vars) entirely. The OSS log surface is split by what sto log surface: ```bash - uv run tangle sdk pipeline-runs logs EXECUTION_ID + tangle sdk pipeline-runs logs EXECUTION_ID ``` (Note: this is keyed by **EXECUTION_ID**, not run id.) diff --git a/skills/tangent/PORT-README.md b/skills/tangent/PORT-README.md index fccf8a5..d9b360a 100644 --- a/skills/tangent/PORT-README.md +++ b/skills/tangent/PORT-README.md @@ -38,7 +38,7 @@ references/ ← the loop steps + topic references ## How to invoke -Commands can run as **`uv run tangle …` from a checkout of the `tangle-cli` repo**, from a persistent uv tool install (`uv tool install tangle-cli`, then `tangle …` / `tangle-cli …`), or as a one-off uvx command (`uvx --from tangle-cli tangle …`). Elsewhere, `tangle` still appears as a bare command noun in prose and in the §2 CLI map (the naming-surface exception). See `OSS-CONVENTIONS.md` §1. +Normal usage runs the **published `tangle-cli` package**: install persistently with `uv tool install tangle-cli`, then run `tangle …` / `tangle-cli …`, or use `uvx --from tangle-cli tangle …` for one-off commands. Local checkout invocation (`uv run tangle …`) is only for validating changes inside the `tangle-cli` repo. Elsewhere, `tangle` still appears as a bare command noun in prose and in the §2 CLI map (the naming-surface exception). See `OSS-CONVENTIONS.md` §1. ## What changed from the internal bundle @@ -47,7 +47,7 @@ replaced with the project's open, backend-agnostic equivalent: | Internal coupling (removed) | Open-source replacement | | ---------------------------------- | -------------------------------------------------------------------- | -| Internal CLI wrapper + env shim | `uv run tangle …` (the public CLI), no environment shim | +| Internal CLI wrapper + env shim | `tangle …` / `tangle-cli …` from the published package, no environment shim | | Cloud-object-storage artifact URIs | Scheme-agnostic artifact `uri` (e.g. `hf://…`); fetch via signed URL | | Hosted log-search backend | `tangle sdk pipeline-runs logs` + launcher-native system events | | Hard-coded internal API endpoint | `--base-url` / `TANGLE_API_URL` | diff --git a/skills/tangent/SKILL.md b/skills/tangent/SKILL.md index 8e8e86f..2ab5c5a 100644 --- a/skills/tangent/SKILL.md +++ b/skills/tangent/SKILL.md @@ -1,6 +1,6 @@ --- name: tangent -description: ML experiment toolkit and autonomous agent. Say "tangent" for help, "tangent " for a specific tool, or "tangent auto" for the full autonomous experiment loop. Requires the Tangle CLI (the `tangle-cli` checkout) and a reachable Tangle backend. +description: ML experiment toolkit and autonomous agent. Say "tangent" for help, "tangent " for a specific tool, or "tangent auto" for the full autonomous experiment loop. Requires the published Tangle CLI (`uv tool install tangle-cli` or `uvx --from tangle-cli tangle ...`) and a reachable Tangle backend. allowed-tools: [Bash, Read, Write, Glob, Grep, Agent, dispatch] --- @@ -22,7 +22,7 @@ bundle-refresh step. Relative cross-references in this skill (`agents/*.md`, `references/*.md`) resolve directly on disk. Read [`references/setup.md`](references/setup.md) to set up the CLI and auth. -Run commands as `uv run tangle …` from a checkout of the `tangle-cli` repo. For an installed CLI, prefer `uv tool install tangle-cli`; for one-off execution, use `uvx --from tangle-cli tangle …`. See [`OSS-CONVENTIONS.md`](OSS-CONVENTIONS.md) §1. +Normal usage runs the published CLI: install persistently with `uv tool install tangle-cli` and use `tangle …`, or run one-off commands with `uvx --from tangle-cli tangle …`. If intentionally validating a local `tangle-cli` checkout, prefix examples with `uv run`. See [`OSS-CONVENTIONS.md`](OSS-CONVENTIONS.md) §1. ## Commands @@ -61,10 +61,10 @@ Automation: ## Tools Always use the `tangle` CLI via Bash. Do **not** use any `tangle` MCP tools. -Run `uv run tangle quickstart` to discover commands. See +Run `tangle quickstart` to discover commands. See [`references/tangle-tools.md`](references/tangle-tools.md). -Cancel a run: `uv run tangle sdk pipeline-runs cancel RUN_ID` +Cancel a run: `tangle sdk pipeline-runs cancel RUN_ID` Background execution: `dispatch`. Subagents: `agents/*.md`. diff --git a/skills/tangent/agents/auth-wizard.md b/skills/tangent/agents/auth-wizard.md index f069310..79a20cb 100644 --- a/skills/tangent/agents/auth-wizard.md +++ b/skills/tangent/agents/auth-wizard.md @@ -14,7 +14,7 @@ environment variables (see [OSS-CONVENTIONS.md §4](../OSS-CONVENTIONS.md)). ## Tools -**From a checkout, run commands as `uv run tangle …`. For an installed CLI, prefer `uv tool install tangle-cli`; for one-off execution, use `uvx --from tangle-cli tangle …`.** +**Use the published `tangle` CLI via Bash.** Install persistently with `uv tool install tangle-cli`, or run one-off commands with `uvx --from tangle-cli tangle …`. Examples below use bare `tangle …`; if intentionally validating a local `tangle-cli` checkout, prefix examples with `uv run`. Help is standard `--help` (there is no `--help-extended` / `--help-full`). Resolution precedence: explicit CLI option > `--config` file value > environment @@ -80,7 +80,7 @@ chosen in Step 2): **a) Inline flag** — explicit, per-command, highest precedence: ```bash -uv run tangle sdk pipeline-runs search --limit 1 \ +tangle sdk pipeline-runs search --limit 1 \ --base-url https://api.example \ --token '' ``` @@ -90,7 +90,7 @@ uv run tangle sdk pipeline-runs search --limit 1 \ ```bash export TANGLE_API_URL='https://api.example' export TANGLE_API_TOKEN='' -uv run tangle sdk pipeline-runs search --limit 1 +tangle sdk pipeline-runs search --limit 1 ``` For `--auth-header` set `TANGLE_API_AUTH_HEADER`; for `-H` set @@ -105,7 +105,7 @@ token: "" ``` ```bash -uv run tangle sdk pipeline-runs search --limit 1 --config tangle.config.yaml +tangle sdk pipeline-runs search --limit 1 --config tangle.config.yaml ``` **Advise against committing secrets.** Prefer the env var, or keep the @@ -116,7 +116,7 @@ uv run tangle sdk pipeline-runs search --limit 1 --config tangle.config.yaml Run a cheap, read-only call to confirm the credential works: ```bash -uv run tangle sdk pipeline-runs search --limit 1 +tangle sdk pipeline-runs search --limit 1 ``` (attach the auth flags from Step 3 if not using env/`--config`). A clean exit — diff --git a/skills/tangent/agents/builder.md b/skills/tangent/agents/builder.md index d3316bc..5bd8b5c 100644 --- a/skills/tangent/agents/builder.md +++ b/skills/tangent/agents/builder.md @@ -11,28 +11,28 @@ components with local code changes for testing. ## Tools -**Run every `tangle` command via Bash as `uv run tangle …` from a checkout of the `tangle-cli` repo**. For an installed CLI, prefer `uv tool install tangle-cli`; for one-off execution, use `uvx --from tangle-cli tangle …` (see [`../OSS-CONVENTIONS.md`](../OSS-CONVENTIONS.md) §1). +**Use the published `tangle` CLI via Bash.** Install persistently with `uv tool install tangle-cli`, or run one-off commands with `uvx --from tangle-cli tangle …`. Examples below use bare `tangle …`; if intentionally validating a local `tangle-cli` checkout, prefix examples with `uv run` (see [`../OSS-CONVENTIONS.md`](../OSS-CONVENTIONS.md) §1). -Run `uv run tangle quickstart` to discover available commands. Use `--help` on any +Run `tangle quickstart` to discover available commands. Use `--help` on any command or group for detailed usage (there is no `--help-extended` / `--help-full`). -For schema and concept docs, use `uv run tangle sdk --help`, -`uv run tangle sdk published-components library`, and the public OSS docs at +For schema and concept docs, use `tangle sdk --help`, +`tangle sdk published-components library`, and the public OSS docs at `github.com/TangleML/website/tree/master/docs`. | What you need | Command | |---|---| -| Export run as YAML | `uv run tangle sdk pipeline-runs export RUN_ID --output output.yaml` | -| Inspect a published component | `uv run tangle sdk published-components inspect --name "Name" --full-spec` | -| Search components (optional; may be empty) | `uv run tangle sdk published-components search "keyword"` | -| Curated standard library | `uv run tangle sdk published-components library` | -| Generate from Python | `uv run tangle sdk components generate from-python source.py [--image REG/IMG:TAG]` | -| Bump version | `uv run tangle sdk components bump-version component.yaml` | -| Hydrate refs | `uv run tangle sdk pipelines hydrate template.yaml -o output.yaml` | -| Validate pipeline | `uv run tangle sdk pipelines validate pipeline.yaml` | -| Auto-layout DAG | `uv run tangle sdk pipelines layout pipeline.yaml` | -| Submit pipeline | `uv run tangle sdk pipeline-runs submit pipeline.yaml [--arg K=V \| --args-json JSON]` | -| Run details | `uv run tangle sdk pipeline-runs details RUN_ID --include-execution-state` | -| Component as used | `uv run tangle sdk pipeline-runs details RUN_ID --execution-id EXEC_ID --include-implementations` | +| Export run as YAML | `tangle sdk pipeline-runs export RUN_ID --output output.yaml` | +| Inspect a published component | `tangle sdk published-components inspect --name "Name" --full-spec` | +| Search components (optional; may be empty) | `tangle sdk published-components search "keyword"` | +| Curated standard library | `tangle sdk published-components library` | +| Generate from Python | `tangle sdk components generate from-python source.py [--image REG/IMG:TAG]` | +| Bump version | `tangle sdk components bump-version component.yaml` | +| Hydrate refs | `tangle sdk pipelines hydrate template.yaml -o output.yaml` | +| Validate pipeline | `tangle sdk pipelines validate pipeline.yaml` | +| Auto-layout DAG | `tangle sdk pipelines layout pipeline.yaml` | +| Submit pipeline | `tangle sdk pipeline-runs submit pipeline.yaml [--arg K=V \| --args-json JSON]` | +| Run details | `tangle sdk pipeline-runs details RUN_ID --include-execution-state` | +| Component as used | `tangle sdk pipeline-runs details RUN_ID --execution-id EXEC_ID --include-implementations` | Component discovery (search/library) is **optional** and **off by default** on a fresh OSS install — treat it as a best-effort lookup and tolerate empty results; @@ -51,8 +51,8 @@ field, a `constantValue:`, a `cli_args:` entry, a run-arg passed via `--arg` / plaintext from your environment or a secret store. Treat raw credential values as poison. -The correct flow is: `uv run tangle sdk secrets list` → if the secret doesn't exist, -ask the human to create it with `uv run tangle sdk secrets create NAME --from-env NAME` +The correct flow is: `tangle sdk secrets list` → if the secret doesn't exist, +ask the human to create it with `tangle sdk secrets create NAME --from-env NAME` (`--from-env`/`-e` reads from an env var so the value never lands in shell history; the agent never touches the value) → reference it via `dynamicData.secret: { name: "NAME" }` on the consuming argument. See @@ -95,7 +95,7 @@ When a pipeline produces an artifact worth keeping past the run's TTL — a curated eval set, a fine-tuned checkpoint, a generated annotation set, a frozen feature snapshot — record its identity so a later pipeline can re-reference it: capture the producing `run_id` and the artifact `uri` -(`uv run tangle sdk artifacts get RUN_ID -q ''` returns `{id, uri, size, hash}` +(`tangle sdk artifacts get RUN_ID -q ''` returns `{id, uri, size, hash}` records; see [`../OSS-CONVENTIONS.md`](../OSS-CONVENTIONS.md) §5) and save them in the scenario's `MEMORY.md` / session log. A downstream pipeline re-references the artifact by feeding that `uri` into the consuming task argument (typically @@ -137,25 +137,25 @@ guarded pattern. Do not assume those components exist. See [`../references/iterating-on-runs.md`](../references/iterating-on-runs.md) for the full workflow. -1. **Export**: `uv run tangle sdk pipeline-runs export RUN_ID --output /tmp/pipeline.yaml` +1. **Export**: `tangle sdk pipeline-runs export RUN_ID --output /tmp/pipeline.yaml` — exports the root spec as-is (there is no `--dehydrate`). Omit `--output` to print to stdout. -2. **Inspect**: `uv run tangle sdk pipeline-runs details RUN_ID --include-execution-state` - — identify task statuses. (`uv run tangle sdk pipeline-runs status RUN_ID` gives a +2. **Inspect**: `tangle sdk pipeline-runs details RUN_ID --include-execution-state` + — identify task statuses. (`tangle sdk pipeline-runs status RUN_ID` gives a lighter run + derived status summary.) 3. **Modify**: Edit the exported YAML. To swap a component, replace its `digest:` or `url: file://` reference with a new `url: file://` pointing to your replacement. -4. **Validate**: `uv run tangle sdk pipelines validate /tmp/pipeline.yaml` +4. **Validate**: `tangle sdk pipelines validate /tmp/pipeline.yaml` 5. **Submit** (see Submission Rules in [`../references/tangle-tools.md`](../references/tangle-tools.md)): ```bash - uv run tangle sdk pipeline-runs submit /tmp/pipeline.yaml \ + tangle sdk pipeline-runs submit /tmp/pipeline.yaml \ --args-json @/tmp/pipeline.args.json ``` `submit` hydrates by default (it resolves component versions), so there is no "dehydrate first" guard and no `--no-wait` — `submit` returns as soon as the - run is created; poll with `uv run tangle sdk pipeline-runs wait RUN_ID`. Pass run + run is created; poll with `tangle sdk pipeline-runs wait RUN_ID`. Pass run arguments with `--arg K=V` / `--args-json ''` (or `--args-json @file.json`); `--config` carries CLI-option defaults (base-url/auth/log-type), not run args. @@ -167,7 +167,7 @@ yourself with your own tooling (docker/podman), then point the component at it. 1. **Find source code**: Inspect the published component to get source annotations: ```bash - uv run tangle sdk published-components inspect --name "Component Name" --full-spec + tangle sdk published-components inspect --name "Component Name" --full-spec ``` Check the annotations the publisher attached (e.g. source path, repo, image, docs references) to locate the source. @@ -179,7 +179,7 @@ yourself with your own tooling (docker/podman), then point the component at it. 3. **Generate the component YAML** from your Python entrypoint, pointing at the image you pushed: ```bash - uv run tangle sdk components generate from-python source.py --image registry.example/img:tag + tangle sdk components generate from-python source.py --image registry.example/img:tag ``` 4. **Insert into pipeline**: In the exported YAML, change the task's `componentRef` @@ -193,16 +193,16 @@ what you need. Component discovery is off by default on a fresh OSS install, so treat this as best-effort and tolerate empty results: ```bash # Optional keyword/name/digest search (may return nothing on a fresh install): -uv run tangle sdk published-components search "" +tangle sdk published-components search "" # Curated standard library: -uv run tangle sdk published-components library +tangle sdk published-components library ``` There are no v2/semantic/fuzzy/regex/schema search variants in OSS. If discovery returns nothing, just generate the component you need. **From Python**: ```bash -uv run tangle sdk components generate from-python my_module.py +tangle sdk components generate from-python my_module.py ``` Generates component YAML from a Python function. Looks for a function matching the filename by default; use `--function ` to pick a different one. Pass @@ -214,10 +214,10 @@ yourself. `generate from-python` is the only generation path — there is no ```bash # Bump version first -uv run tangle sdk components bump-version component.yaml +tangle sdk components bump-version component.yaml # Publish -uv run tangle sdk published-components publish component.yaml +tangle sdk published-components publish component.yaml ``` `bump-version` lives under `components`; `publish` lives under `published-components`. To publish several at once, pass a `--config` YAML/JSON @@ -230,7 +230,7 @@ Always validate before submitting. See Submission Rules in [`../references/tangle-tools.md`](../references/tangle-tools.md) for the full pre-submit checklist. ```bash -uv run tangle sdk pipelines validate pipeline.yaml +tangle sdk pipelines validate pipeline.yaml ``` Use `--verbose` only if validation fails and you need full error details. diff --git a/skills/tangent/agents/debugger.md b/skills/tangent/agents/debugger.md index 5277faa..92776c8 100644 --- a/skills/tangent/agents/debugger.md +++ b/skills/tangent/agents/debugger.md @@ -11,29 +11,30 @@ return a one-line diagnosis. ## Tools -**Always use the `tangle` CLI via Bash.** Run commands as `uv run tangle …` -from a checkout of the `tangle-cli` repo. For an installed CLI, prefer -`uv tool install tangle-cli`; for one-off execution, use -`uvx --from tangle-cli tangle …` (see `OSS-CONVENTIONS.md` §1). - -Run `uv run tangle quickstart` to discover available commands. Use `--help` on any -command (or group, e.g. `uv run tangle sdk pipeline-runs --help`) for detailed usage. +**Always use the published `tangle` CLI via Bash.** Install persistently with +`uv tool install tangle-cli`, or run one-off commands with +`uvx --from tangle-cli tangle …`. Examples below use bare `tangle …`; if +intentionally validating a local `tangle-cli` checkout, prefix examples with +`uv run` (see `OSS-CONVENTIONS.md` §1). + +Run `tangle quickstart` to discover available commands. Use `--help` on any +command (or group, e.g. `tangle sdk pipeline-runs --help`) for detailed usage. There is no `--help-extended` / `--help-full` and no `docs` command — for -debugging guidance, lean on `--help`, `uv run tangle sdk published-components library`, +debugging guidance, lean on `--help`, `tangle sdk published-components library`, and the public OSS docs at [github.com/TangleML/website/tree/master/docs](https://github.com/TangleML/website/tree/master/docs). | What you need | Command | |---|---| -| Run state & derived status summary | `uv run tangle sdk pipeline-runs status RUN_ID` | -| Execution tree & task states | `uv run tangle sdk pipeline-runs details RUN_ID --include-execution-state` | -| Graph execution state (per execution) | `uv run tangle sdk pipeline-runs graph-state EXECUTION_ID` | -| Container logs (application stack traces, code errors) | `uv run tangle sdk pipeline-runs logs EXECUTION_ID` | +| Run state & derived status summary | `tangle sdk pipeline-runs status RUN_ID` | +| Execution tree & task states | `tangle sdk pipeline-runs details RUN_ID --include-execution-state` | +| Graph execution state (per execution) | `tangle sdk pipeline-runs graph-state EXECUTION_ID` | +| Container logs (application stack traces, code errors) | `tangle sdk pipeline-runs logs EXECUTION_ID` | | System events (eviction reasons, OOM kills, scheduling failures) | Launcher-native — NOT a Tangle command (see §7 and "Fetching System Events" below) | -| Search for runs | `uv run tangle sdk pipeline-runs search --name ` | -| Component spec (per-task) | `uv run tangle sdk pipeline-runs details RUN_ID --execution-id EXEC_ID --include-implementations` | -| Artifact metadata (URIs, size, hash) | `uv run tangle sdk artifacts get RUN_ID -q '{"tasks": {...}}'` | -| Export pipeline spec | `uv run tangle sdk pipeline-runs export RUN_ID --output output.yaml` | +| Search for runs | `tangle sdk pipeline-runs search --name ` | +| Component spec (per-task) | `tangle sdk pipeline-runs details RUN_ID --execution-id EXEC_ID --include-implementations` | +| Artifact metadata (URIs, size, hash) | `tangle sdk artifacts get RUN_ID -q '{"tasks": {...}}'` | +| Export pipeline spec | `tangle sdk pipeline-runs export RUN_ID --output output.yaml` | Artifact retrieval is **metadata-only** (`artifacts get` returns `{id, uri, size, hash}`); the `uri` is backend-agnostic — read the scheme, don't assume one. There @@ -42,16 +43,16 @@ in `OSS-CONVENTIONS.md` §5. ## Debugging Workflow -1. **Get failure details**: `uv run tangle sdk pipeline-runs status RUN_ID` for a quick - run + derived status summary, then `uv run tangle sdk pipeline-runs details RUN_ID +1. **Get failure details**: `tangle sdk pipeline-runs status RUN_ID` for a quick + run + derived status summary, then `tangle sdk pipeline-runs details RUN_ID --include-execution-state` — shows the execution tree with per-task status. Get execution IDs for failed tasks. For a single failed execution's graph state, - `uv run tangle sdk pipeline-runs graph-state EXECUTION_ID`. -2. **Inspect the failed task**: `uv run tangle sdk pipeline-runs details RUN_ID + `tangle sdk pipeline-runs graph-state EXECUTION_ID`. +2. **Inspect the failed task**: `tangle sdk pipeline-runs details RUN_ID --execution-id EXEC_ID --include-implementations` — drill into the specific failed execution to see the component spec as actually used. 3. **Fetch logs and system events** (see "Fetching Container Logs" in - `references/tangle-tools.md`): `uv run tangle sdk pipeline-runs logs EXECUTION_ID` + `references/tangle-tools.md`): `tangle sdk pipeline-runs logs EXECUTION_ID` for application logs (stack traces, code errors). Container logs are keyed by **EXECUTION_ID**, not run id. For system events (eviction, OOM, scheduling, `pods "task-…" not found` mysteries), the Tangle backend does **not** store @@ -62,12 +63,12 @@ in `OSS-CONVENTIONS.md` §5. auth wizard (`agents/auth-wizard.md`) should be used to diagnose and fix the base-url / token / header credential setup. 5. **Check upstream artifacts**: If logs mention missing data/inputs, check upstream - task outputs via `uv run tangle sdk artifacts get RUN_ID -q '{"tasks": {...}}'` — an + task outputs via `tangle sdk artifacts get RUN_ID -q '{"tasks": {...}}'` — an upstream task may have produced empty or wrong output. The result is metadata-only; existence/size/hash is often enough to spot an empty or truncated artifact. Only fetch bytes (signed-URL recipe, `OSS-CONVENTIONS.md` §5) when you genuinely need to inspect content. -6. **Export the pipeline**: `uv run tangle sdk pipeline-runs export RUN_ID --output +6. **Export the pipeline**: `tangle sdk pipeline-runs export RUN_ID --output /tmp/pipeline.yaml` to get the exact pipeline spec used. Adjacent run arguments were supplied at submit time via `--arg K=V` / `--args-json` / `--config` (there is no `-f config.yaml`). @@ -75,14 +76,14 @@ in `OSS-CONVENTIONS.md` §5. Modify the exported YAML, then resubmit. Hydration is the default; there is no `--dehydrate` step to run first and no `--no-wait` flag (submit never waits): ```bash - uv run tangle sdk pipeline-runs submit /tmp/pipeline.yaml \ + tangle sdk pipeline-runs submit /tmp/pipeline.yaml \ --arg = ``` Submit returns immediately; to block on the result, use - `uv run tangle sdk pipeline-runs wait RUN_ID --max-wait N`. After submission, you may + `tangle sdk pipeline-runs wait RUN_ID --max-wait N`. After submission, you may annotate the run with generic provenance: ```bash - uv run tangle sdk pipeline-runs annotations set source tangle-cli + tangle sdk pipeline-runs annotations set source tangle-cli ``` ## Fetching System Events diff --git a/skills/tangent/agents/reporter.md b/skills/tangent/agents/reporter.md index 9fa96ac..c8a3f94 100644 --- a/skills/tangent/agents/reporter.md +++ b/skills/tangent/agents/reporter.md @@ -10,17 +10,17 @@ Generate an ML experiment report. Regenerate from scratch each round. ## Tools -**Always use the `tangle` CLI via Bash. Do NOT use any MCP tools.** -Run commands as `uv run tangle …` from a checkout of the `tangle-cli` repo. For an installed CLI, prefer `uv tool install tangle-cli`; for one-off execution, use `uvx --from tangle-cli tangle …` (see [OSS-CONVENTIONS.md §1](../OSS-CONVENTIONS.md)). +**Always use the published `tangle` CLI via Bash. Do NOT use any MCP tools.** +Install persistently with `uv tool install tangle-cli`, or run one-off commands with `uvx --from tangle-cli tangle …`. Examples below use bare `tangle …`; if intentionally validating a local `tangle-cli` checkout, prefix examples with `uv run` (see [OSS-CONVENTIONS.md §1](../OSS-CONVENTIONS.md)). -Run `uv run tangle quickstart` to discover available commands. Use `--help` on any +Run `tangle quickstart` to discover available commands. Use `--help` on any command for detailed usage. | What you need | Command | |---|---| -| Artifact metadata (id, `uri`, size, hash) | `uv run tangle sdk artifacts get RUN_ID -q '{"tasks": {...}}'` | +| Artifact metadata (id, `uri`, size, hash) | `tangle sdk artifacts get RUN_ID -q '{"tasks": {...}}'` | | Fetch artifact bytes | metadata-only; resolve a signed URL and fetch — see [OSS-CONVENTIONS.md §5](../OSS-CONVENTIONS.md) | -| Run details | `uv run tangle sdk pipeline-runs details RUN_ID --include-execution-state` | +| Run details | `tangle sdk pipeline-runs details RUN_ID --include-execution-state` | ## Inputs diff --git a/skills/tangent/agents/researcher.md b/skills/tangent/agents/researcher.md index ef35344..3bb6816 100644 --- a/skills/tangent/agents/researcher.md +++ b/skills/tangent/agents/researcher.md @@ -12,22 +12,22 @@ Think like an MLE who reads papers and asks "what if we tried this?" ## Tools -**Always use the `tangle` CLI via Bash. Do NOT use any MCP tool layer.** -Run commands as `uv run tangle …` from a checkout of the `tangle-cli` repo. For an installed CLI, prefer `uv tool install tangle-cli`; for one-off execution, use `uvx --from tangle-cli tangle …`. See [`../OSS-CONVENTIONS.md`](../OSS-CONVENTIONS.md) §1. +**Always use the published `tangle` CLI via Bash. Do NOT use any MCP tool layer.** +Install persistently with `uv tool install tangle-cli`, or run one-off commands with `uvx --from tangle-cli tangle …`. Examples below use bare `tangle …`; if intentionally validating a local `tangle-cli` checkout, prefix examples with `uv run`. See [`../OSS-CONVENTIONS.md`](../OSS-CONVENTIONS.md) §1. -Run `uv run tangle quickstart` to discover available commands. Use `--help` on any -command for detailed usage. For broader docs, see `uv run tangle sdk +Run `tangle quickstart` to discover available commands. Use `--help` on any +command for detailed usage. For broader docs, see `tangle sdk published-components library` and the public OSS docs at `github.com/TangleML/website/tree/master/docs`. | What you need | Command | |---|---| -| Export run as YAML | `uv run tangle sdk pipeline-runs export RUN_ID --output output.yaml` | -| Inspect component | `uv run tangle sdk published-components inspect --name "Name" --full-spec` | -| Search components (optional, may be empty) | `uv run tangle sdk published-components search "keyword"` | -| Run details | `uv run tangle sdk pipeline-runs details RUN_ID --include-execution-state` | -| Run status | `uv run tangle sdk pipeline-runs status RUN_ID` | -| Artifact metadata (URIs/size/hash) | `uv run tangle sdk artifacts get RUN_ID -q '{"tasks": {...}}'` | +| Export run as YAML | `tangle sdk pipeline-runs export RUN_ID --output output.yaml` | +| Inspect component | `tangle sdk published-components inspect --name "Name" --full-spec` | +| Search components (optional, may be empty) | `tangle sdk published-components search "keyword"` | +| Run details | `tangle sdk pipeline-runs details RUN_ID --include-execution-state` | +| Run status | `tangle sdk pipeline-runs status RUN_ID` | +| Artifact metadata (URIs/size/hash) | `tangle sdk artifacts get RUN_ID -q '{"tasks": {...}}'` | | Fetch artifact bytes | metadata-only `get` → signed-URL recipe ([`../OSS-CONVENTIONS.md`](../OSS-CONVENTIONS.md) §5) | | Recent commits | `git log --oneline --since="Nd" -- ` | | PRs/Issues | `gh pr list`/`gh issue list --repo --search ""` | @@ -111,7 +111,7 @@ Use `image_roots` to resolve modules to local files. To find source code for a published component, inspect it: ```bash -uv run tangle sdk published-components inspect --name "Component Name" --full-spec +tangle sdk published-components inspect --name "Component Name" --full-spec ``` The `annotations` section includes `component_yaml_path`, `git_relative_dir`, and `git_remote_url`. Use these to locate the YAML and source code in the repo. @@ -124,8 +124,8 @@ Use `--follow-deprecated` if the component is deprecated to find its successor. Tangle pipelines are nested subgraphs. Inputs flow through the hierarchy via `graphInput` wiring: top-level task output → subgraph input → nested subgraph input → leaf task argument. Trace the wiring at each level before modifying. -For pipeline and component schema details, use `uv run tangle sdk pipelines --help`, -`uv run tangle sdk published-components --help`, `uv run tangle sdk +For pipeline and component schema details, use `tangle sdk pipelines --help`, +`tangle sdk published-components --help`, `tangle sdk published-components library`, and the public OSS docs at `github.com/TangleML/website/tree/master/docs`. diff --git a/skills/tangent/agents/reviewer.md b/skills/tangent/agents/reviewer.md index 19d5732..4356fee 100644 --- a/skills/tangent/agents/reviewer.md +++ b/skills/tangent/agents/reviewer.md @@ -12,23 +12,24 @@ ML methodology issues. Be skeptical. Check the work. ## Tools -**Always use the `tangle` CLI via Bash.** Run commands as `uv run tangle …` -from a checkout of the `tangle-cli` repo. For an installed CLI, prefer -`uv tool install tangle-cli`; for one-off execution, use -`uvx --from tangle-cli tangle …`. See [OSS-CONVENTIONS.md](../OSS-CONVENTIONS.md) -§1 for the invocation rule and §4 for auth flags. - -Run `uv run tangle quickstart` to discover available commands. Use `--help` on any +**Always use the published `tangle` CLI via Bash.** Install persistently with +`uv tool install tangle-cli`, or run one-off commands with +`uvx --from tangle-cli tangle …`. Examples below use bare `tangle …`; if +intentionally validating a local `tangle-cli` checkout, prefix examples with +`uv run`. See [OSS-CONVENTIONS.md](../OSS-CONVENTIONS.md) §1 for the invocation +rule and §4 for auth flags. + +Run `tangle quickstart` to discover available commands. Use `--help` on any command for detailed usage. | What you need | Command | |---|---| -| Run details | `uv run tangle sdk pipeline-runs details RUN_ID --include-execution-state` | -| Drill into a task | `uv run tangle sdk pipeline-runs details RUN_ID --execution-id EXEC_ID --include-implementations` | -| Container logs | `uv run tangle sdk pipeline-runs logs EXECUTION_ID` | -| Artifact metadata (uri/size/hash) | `uv run tangle sdk artifacts get RUN_ID -q '{"tasks": {...}}'` | -| Export pipeline spec | `uv run tangle sdk pipeline-runs export RUN_ID --output output.yaml` | -| Inspect component | `uv run tangle sdk published-components inspect --name "Name" --full-spec` | +| Run details | `tangle sdk pipeline-runs details RUN_ID --include-execution-state` | +| Drill into a task | `tangle sdk pipeline-runs details RUN_ID --execution-id EXEC_ID --include-implementations` | +| Container logs | `tangle sdk pipeline-runs logs EXECUTION_ID` | +| Artifact metadata (uri/size/hash) | `tangle sdk artifacts get RUN_ID -q '{"tasks": {...}}'` | +| Export pipeline spec | `tangle sdk pipeline-runs export RUN_ID --output output.yaml` | +| Inspect component | `tangle sdk published-components inspect --name "Name" --full-spec` | `artifacts get` is **metadata-only** — it returns `{id, uri, size, hash}` records; there is no `artifacts download`. Metadata is sufficient for review verification. diff --git a/skills/tangent/agents/scenario-builder.md b/skills/tangent/agents/scenario-builder.md index 50ce8e0..a5b8849 100644 --- a/skills/tangent/agents/scenario-builder.md +++ b/skills/tangent/agents/scenario-builder.md @@ -9,8 +9,7 @@ tools: read, write, bash, grep, glob, agent You create Tangent scenarios by interviewing the user. Your job is to ASK QUESTIONS and WAIT FOR ANSWERS — not to generate files immediately. -All commands run as `uv run tangle …` from a checkout of the `tangle-cli` repo (see -[`../OSS-CONVENTIONS.md`](../OSS-CONVENTIONS.md) §1). +Use the published `tangle` CLI via Bash: install persistently with `uv tool install tangle-cli`, or run one-off commands with `uvx --from tangle-cli tangle …`. Examples below use bare `tangle …`; if intentionally validating a local `tangle-cli` checkout, prefix examples with `uv run` (see [`../OSS-CONVENTIONS.md`](../OSS-CONVENTIONS.md) §1). ## CRITICAL RULES @@ -152,8 +151,8 @@ and introspect it to understand the pipeline structure. **If no source path but run ID was provided**, export it: ```bash -uv run tangle sdk pipeline-runs details # extract task names, pipeline structure -uv run tangle sdk pipeline-runs export --output /pipeline.yaml +tangle sdk pipeline-runs details # extract task names, pipeline structure +tangle sdk pipeline-runs export --output /pipeline.yaml ``` `export` writes the root spec as-is (omit `--output` to print to stdout). There is no `--dehydrate` flag — `--hydrate` on submit (the default) resolves the latest @@ -225,7 +224,7 @@ based on what fits — e.g., `metrics-guide.md`, `eval-metrics.md`, etc.). ## Phase 3: Code & Data **Introspect:** Trace pipeline tasks to source code using -`uv run tangle sdk published-components inspect --name --full-spec` +`tangle sdk published-components inspect --name --full-spec` (component discovery is **optional** and off by default in OSS — tolerate empty results and fall back to reading the component refs in `pipeline.yaml` directly). If the pipeline reads from a query-backed data source (a warehouse diff --git a/skills/tangent/references/data-sources.md b/skills/tangent/references/data-sources.md index 89ed00d..3e62aca 100644 --- a/skills/tangent/references/data-sources.md +++ b/skills/tangent/references/data-sources.md @@ -133,7 +133,7 @@ run's TTL or share with other scenarios. - **Read the promote task's logs.** The component prints `PROMOTED. data_source_id = ` near the end of its own task log — fetch - with `uv run tangle sdk pipeline-runs logs `. Simplest + with `tangle sdk pipeline-runs logs `. Simplest and works without modifying the pipeline. - **Wire it into a downstream task.** Connect the promote task's `data_source_id` output (a `String`) into another task that prints @@ -141,7 +141,7 @@ run's TTL or share with other scenarios. pipeline graph (e.g. a follow-up `Load data source` in the same run) rather than be recovered out-of-band. - Don't try to recover the value with `uv run tangle sdk artifacts get` — + Don't try to recover the value with `tangle sdk artifacts get` — that returns artifact *metadata* (`uri`/`size`/`hash`), not the contents of scalar `String` outputs. @@ -304,7 +304,7 @@ tasks: ``` ```bash -uv run tangle sdk pipeline-runs submit pipeline.yaml \ +tangle sdk pipeline-runs submit pipeline.yaml \ --arg eval_set_id="" ``` @@ -313,7 +313,7 @@ uv run tangle sdk pipeline-runs submit pipeline.yaml \ - **No data-source components? Use the lightweight pattern.** If your backend doesn't register these components, you can still reuse a prior run's output: record the producer's `run_id` and the artifact `uri` - (read it scheme-agnostically from `uv run tangle sdk artifacts get RUN_ID`) + (read it scheme-agnostically from `tangle sdk artifacts get RUN_ID`) in `MEMORY.md`, and re-reference that `uri` directly. URIs are backend-agnostic and may look like `hf://datasets//@main/` — read the `uri` field; do not assume a scheme. diff --git a/skills/tangent/references/example-scenarios/01-mslr-ranking.md b/skills/tangent/references/example-scenarios/01-mslr-ranking.md index b7fb264..dc70c4a 100644 --- a/skills/tangent/references/example-scenarios/01-mslr-ranking.md +++ b/skills/tangent/references/example-scenarios/01-mslr-ranking.md @@ -4,7 +4,7 @@ A self-contained, public-data worked example of one autonomous tuning round. It loop in `references/step-0-initialize.md` … `references/step-7-decide.md`: read the situation, form a hypothesis, express it as a small config delta, submit, watch the right signals, and write down the outcome. Nothing here is specific to any one backend — every command is the -generic `uv run tangle …` surface from `references/tangle-tools.md`. +published `tangle …` surface from `references/tangle-tools.md`. ## Dataset (public) @@ -56,7 +56,7 @@ model" as out of scope here and just record the winning `run_id`. ### Situation -A baseline run finished. Reading its metrics (`uv run tangle sdk artifacts get -q +A baseline run finished. Reading its metrics (`tangle sdk artifacts get -q '{"tasks":["eval-ranker"]}'`, then fetching the metrics blob via the signed-URL recipe in `OSS-CONVENTIONS.md` §5): @@ -88,7 +88,7 @@ args under test. Run A — regularize: ```bash -uv run tangle sdk pipeline-runs submit pipeline.yaml \ +tangle sdk pipeline-runs submit pipeline.yaml \ --arg num_leaves=63 \ --arg learning_rate=0.05 \ --arg min_data_in_leaf=200 \ @@ -102,7 +102,7 @@ Run B — align truncation to the metric (and a matching `n_estimators` bump to the lower learning rate): ```bash -uv run tangle sdk pipeline-runs submit pipeline.yaml \ +tangle sdk pipeline-runs submit pipeline.yaml \ --arg lambdarank_truncation_level=10 \ --arg learning_rate=0.05 \ --arg n_estimators=2000 \ @@ -122,13 +122,13 @@ While the runs are in flight, watch status and graph state with the CLI rather t poll loop (`OSS-CONVENTIONS.md` §10, D14): ```bash -uv run tangle sdk pipeline-runs status -uv run tangle sdk pipeline-runs graph-state +tangle sdk pipeline-runs status +tangle sdk pipeline-runs graph-state ``` -To block until done: `uv run tangle sdk pipeline-runs wait --max-wait 600 +To block until done: `tangle sdk pipeline-runs wait --max-wait 600 --poll-interval 10`. Container logs (training progress, early-stopping rounds) come from -`uv run tangle sdk pipeline-runs logs `; scheduling/OOM events come from your +`tangle sdk pipeline-runs logs `; scheduling/OOM events come from your launcher's runtime, not from the Tangle backend (`OSS-CONVENTIONS.md` §7). When `eval-ranker` completes, read its metrics artifact and check, in order: diff --git a/skills/tangent/references/example-scenarios/02-text-classification.md b/skills/tangent/references/example-scenarios/02-text-classification.md index cb19d3d..bfec5a7 100644 --- a/skills/tangent/references/example-scenarios/02-text-classification.md +++ b/skills/tangent/references/example-scenarios/02-text-classification.md @@ -3,7 +3,7 @@ A second self-contained, public-data worked example — same loop, a different model family. It shows the situation → hypothesis → config-delta → signals → outcome rhythm applied to a transformer fine-tuning task instead of a gradient-boosted ranker. Every command is the -generic `uv run tangle …` surface (`references/tangle-tools.md`). +published `tangle …` surface (`references/tangle-tools.md`). ## Dataset (public) @@ -52,7 +52,7 @@ and move on. The baseline fine-tune finished but underwhelms, and the run was expensive: - macro-F1 = **0.918**, accuracy = **0.919**. -- Container logs (`uv run tangle sdk pipeline-runs logs `) show validation loss +- Container logs (`tangle sdk pipeline-runs logs `) show validation loss bottoming out around epoch 2 of 5 and creeping up after — the last 2–3 epochs are wasted compute and mild overfitting. - `max_seq_length=256`, but AG News items are short; most sequences are heavily padded. @@ -77,7 +77,7 @@ Args go inline at submit — no `-f config.yaml` (`OSS-CONVENTIONS.md` §10, D12 Run A — fewer epochs + early stopping: ```bash -uv run tangle sdk pipeline-runs submit pipeline.yaml \ +tangle sdk pipeline-runs submit pipeline.yaml \ --arg num_train_epochs=3 \ --arg early_stopping_patience=1 \ --arg metric_for_best_model=macro_f1 \ @@ -90,7 +90,7 @@ uv run tangle sdk pipeline-runs submit pipeline.yaml \ Run B — right-size sequence length + warmup schedule: ```bash -uv run tangle sdk pipeline-runs submit pipeline.yaml \ +tangle sdk pipeline-runs submit pipeline.yaml \ --arg max_seq_length=128 \ --arg lr_scheduler_type=linear \ --arg warmup_ratio=0.06 \ @@ -109,8 +109,8 @@ record it, then watch the run. Use the CLI for status, not a Python poll loop (`OSS-CONVENTIONS.md` §10, D14): ```bash -uv run tangle sdk pipeline-runs status -uv run tangle sdk pipeline-runs wait --max-wait 600 --poll-interval 10 +tangle sdk pipeline-runs status +tangle sdk pipeline-runs wait --max-wait 600 --poll-interval 10 ``` Application progress (loss curves, early-stop trigger, steps/sec) is in container logs; a diff --git a/skills/tangent/references/example-scenarios/INDEX.md b/skills/tangent/references/example-scenarios/INDEX.md index 21cab7d..8171df1 100644 --- a/skills/tangent/references/example-scenarios/INDEX.md +++ b/skills/tangent/references/example-scenarios/INDEX.md @@ -6,7 +6,7 @@ > a single hypothesis, express it as a small config delta, submit, watch the right signals, > and write down the outcome. -Every command in these scenarios is the generic `uv run tangle …` surface documented in +Every command in these scenarios uses the published `tangle …` surface documented in `references/tangle-tools.md`. They name only public datasets and public models, store artifacts scheme-agnostically (read the `uri`; see `OSS-CONVENTIONS.md` §5), and treat registry / promotion / scheduling / `--run-as` as **extension-only** (`OSS-CONVENTIONS.md` diff --git a/skills/tangent/references/iterating-on-runs.md b/skills/tangent/references/iterating-on-runs.md index 8d56487..269cec0 100644 --- a/skills/tangent/references/iterating-on-runs.md +++ b/skills/tangent/references/iterating-on-runs.md @@ -4,7 +4,7 @@ When modifying and re-running an existing pipeline (e.g. change params for faile 1. **Export the run**: ```bash - uv run tangle sdk pipeline-runs export --output /tmp/pipeline.yaml + tangle sdk pipeline-runs export --output /tmp/pipeline.yaml ``` This writes the run's root pipeline spec to `/tmp/pipeline.yaml` (omit `--output` to print to stdout). The export is the spec **as-is** — there is no `--dehydrate` flag and no @@ -13,17 +13,17 @@ When modifying and re-running an existing pipeline (e.g. change params for faile 2. **Inspect execution statuses**: ```bash - uv run tangle sdk pipeline-runs details --include-execution-state + tangle sdk pipeline-runs details --include-execution-state ``` to identify failed/cancelled/skipped executions. For a quick run + derived status - summary, use `uv run tangle sdk pipeline-runs status `. + summary, use `tangle sdk pipeline-runs status `. 3. **Understand the YAML structure**: Tangle pipelines are nested subgraphs. Inputs flow through the hierarchy via `graphInput` wiring: top-level task output → subgraph input → nested subgraph input → leaf task argument. Trace the wiring at each level before - modifying. For pipeline and component schema details, use `uv run tangle sdk pipelines - --help` / `uv run tangle sdk components --help`, browse the curated standard library - (`uv run tangle sdk published-components library`), and consult the public docs at + modifying. For pipeline and component schema details, use `tangle sdk pipelines + --help` / `tangle sdk components --help`, browse the curated standard library + (`tangle sdk published-components library`), and consult the public docs at `github.com/TangleML/website/tree/master/docs`. 4. **Modify the pipeline**: Edit the exported YAML directly. To replace a component, swap @@ -32,17 +32,17 @@ When modifying and re-running an existing pipeline (e.g. change params for faile 5. **Preview**: render the structure before submitting — ```bash - uv run tangle sdk pipelines diagram /tmp/pipeline.yaml # Mermaid - uv run tangle sdk pipelines layout /tmp/pipeline.yaml # auto-layout + tangle sdk pipelines diagram /tmp/pipeline.yaml # Mermaid + tangle sdk pipelines layout /tmp/pipeline.yaml # auto-layout ``` and validate it parses: ```bash - uv run tangle sdk pipelines validate /tmp/pipeline.yaml + tangle sdk pipelines validate /tmp/pipeline.yaml ``` 6. **Submit** (see Submission Rules in `references/tangle-tools.md`): ```bash - uv run tangle sdk pipeline-runs submit /tmp/pipeline.yaml \ + tangle sdk pipeline-runs submit /tmp/pipeline.yaml \ --arg = \ --annotation session= --annotation round= ``` @@ -52,5 +52,5 @@ When modifying and re-running an existing pipeline (e.g. change params for faile file for CLI-option defaults (base-url/auth/log-type — not run args). `submit` never waits; to block on completion, follow up with: ```bash - uv run tangle sdk pipeline-runs wait --max-wait 600 --poll-interval 10 + tangle sdk pipeline-runs wait --max-wait 600 --poll-interval 10 ``` diff --git a/skills/tangent/references/secrets.md b/skills/tangent/references/secrets.md index 0752e90..d59a329 100644 --- a/skills/tangent/references/secrets.md +++ b/skills/tangent/references/secrets.md @@ -23,7 +23,7 @@ token, etc.): via `dynamicData.secret.name` in the pipeline YAML; Tangle resolves the value at task-launch time, inside the container, with no plaintext on the pipeline spec. -3. **The human creates / rotates the secret value**, via `uv run tangle sdk +3. **The human creates / rotates the secret value**, via `tangle sdk secrets create ... --from-env VAR_NAME` (preferred — agent never touches the value). The agent's job is to identify *that a secret is needed*, *what to name it*, and *how to wire it through the pipeline*. Not to source the @@ -124,7 +124,7 @@ If an input/argument is described as, named like, or behaves like any of: ### 1. Discover what secrets exist ```bash -uv run tangle sdk secrets list +tangle sdk secrets list ``` Output lists `secret_name`, `updated_at`, optional `expires_at`, optional @@ -150,7 +150,7 @@ never stored in history): # enters shell history (only `read -rs MY_API_KEY` is recorded, not the value). read -rs MY_API_KEY # paste the value, press Enter (no echo) export MY_API_KEY -uv run tangle sdk secrets create MY_API_KEY \ +tangle sdk secrets create MY_API_KEY \ --from-env MY_API_KEY \ --description 'Used by for ' unset MY_API_KEY # clear it from the current shell @@ -177,10 +177,10 @@ configs: ``` ```bash -uv run tangle sdk secrets create --config secrets_config.yaml +tangle sdk secrets create --config secrets_config.yaml ``` -**Do NOT** propose `uv run tangle sdk secrets create NAME --value 'sk-…'` with +**Do NOT** propose `tangle sdk secrets create NAME --value 'sk-…'` with a value you pulled from somewhere. The `--value` / `-v` flag exists for humans typing at a prompt, not for agents shuffling credentials between systems. Prefer `--from-env` / `-e` everywhere. @@ -192,7 +192,7 @@ credential — or how it expects to receive it — inspect the component's schem first rather than guessing: ```bash -uv run tangle sdk published-components inspect "" +tangle sdk published-components inspect "" ``` That shows each input and its type, so you can tell which argument is @@ -222,7 +222,7 @@ tasks: Things to verify after wiring: -- `uv run tangle sdk pipelines validate ` passes. +- `tangle sdk pipelines validate ` passes. - Run the **complete 4-stage pre-submit gate** from [`step-3-submit.md`](step-3-submit.md) § "Pre-submit checks". The gate uses `grep -lEi` (filenames only, never echoes matching lines) plus a @@ -307,15 +307,15 @@ A minimal end-to-end demo against a public bearer-token echo endpoint # Use --from-env so the value never lands in shell history. read -rs DEMO_BEARER_TOKEN export DEMO_BEARER_TOKEN -uv run tangle sdk secrets create DEMO_BEARER_TOKEN \ +tangle sdk secrets create DEMO_BEARER_TOKEN \ --from-env DEMO_BEARER_TOKEN --description 'demo' unset DEMO_BEARER_TOKEN # 2. Submit — the pipeline references DEMO_BEARER_TOKEN via dynamicData.secret -uv run tangle sdk pipeline-runs submit secrets_demo_pipeline.yaml --hydrate +tangle sdk pipeline-runs submit secrets_demo_pipeline.yaml --hydrate # 3. Cleanup -uv run tangle sdk secrets delete DEMO_BEARER_TOKEN +tangle sdk secrets delete DEMO_BEARER_TOKEN ``` The pipeline injects the secret as `Authorization: Bearer ` to @@ -326,12 +326,12 @@ shape. ## CLI reference ```bash -uv run tangle sdk secrets list -uv run tangle sdk secrets create NAME --from-env ENV_VAR \ +tangle sdk secrets list +tangle sdk secrets create NAME --from-env ENV_VAR \ [--description '…'] [--expires-at 2026-12-31T00:00:00Z] -uv run tangle sdk secrets update NAME --from-env ENV_VAR -uv run tangle sdk secrets delete NAME [--force] -uv run tangle sdk secrets --help +tangle sdk secrets update NAME --from-env ENV_VAR +tangle sdk secrets delete NAME [--force] +tangle sdk secrets --help ``` `create` / `update` take `--value` / `-v` or (preferred) `--from-env` / `-e`, @@ -342,6 +342,6 @@ files (see the `_defaults` / `configs` block above). ## When in doubt Stop and ask the human. "This pipeline needs an `X_API_KEY` — please create -a Tangle secret named `` (`uv run tangle sdk secrets create +a Tangle secret named `` (`tangle sdk secrets create --from-env `) and confirm before I wire it through" is always the right move. Never the wrong move. diff --git a/skills/tangent/references/setup.md b/skills/tangent/references/setup.md index e6284a0..d414245 100644 --- a/skills/tangent/references/setup.md +++ b/skills/tangent/references/setup.md @@ -10,32 +10,30 @@ cross-references resolve directly on disk. ## 1. Install / run the CLI -From a checkout, run commands through `uv run`: - -```bash -uv run tangle quickstart -uv run tangle --help -uv run tangle sdk --help -uv run tangle api --help -``` - -For a persistent user-level CLI install, prefer uv tools: +For normal Tangent usage, install the published CLI as a persistent uv tool: ```bash uv tool install tangle-cli tangle quickstart -tangle-cli --help +tangle --help +tangle sdk --help +tangle api --help ``` For one-off execution without a persistent install, use `uvx`: ```bash uvx --from tangle-cli tangle --help +uvx --from tangle-cli tangle quickstart ``` Generic Python environments may also use `pip install tangle-cli`; use `uv pip install tangle-cli` only inside an explicitly managed virtualenv. +When intentionally validating a local checkout of the `tangle-cli` repo, prefix +examples with `uv run` (for example, `uv run tangle quickstart`). Skill examples +otherwise use the installed-tool form (`tangle …` / `tangle-cli …`). + `uv` resolves dependencies against public PyPI. In the `tangle-cli` workspace, `uv` installs the workspace `tangle-api` package automatically for dev/tests. The published default `tangle-cli` install includes `tangle-api`, enabling static @@ -44,7 +42,7 @@ API-backed commands and the handwritten `TangleApiClient` wrapper. The old Then discover available commands: ```bash -uv run tangle quickstart +tangle quickstart ``` Help is standard `--help` (there is no `--help-extended` / `--help-full`). @@ -81,7 +79,7 @@ export TANGLE_API_HEADERS='X-Gateway-Auth: …' Or pass them per-command: ```bash -uv run tangle sdk pipeline-runs submit pipeline.yaml \ +tangle sdk pipeline-runs submit pipeline.yaml \ --base-url https://api.example \ --auth-header 'Bearer …' \ -H 'X-Gateway-Auth: …' \ @@ -99,7 +97,7 @@ Run a cheap, read-only call. If it returns (even with zero results), your backen URL and credentials are wired correctly: ```bash -uv run tangle sdk pipeline-runs search --limit 1 +tangle sdk pipeline-runs search --limit 1 ``` Interpreting failures: @@ -117,11 +115,11 @@ The unified CLI is `tangle`, split into `tangle sdk …` (hand-written SDK/local/compound commands) and `tangle api …` (auto-generated API wrappers): ```bash -uv run tangle quickstart -uv run tangle sdk pipeline-runs submit pipeline.yaml --arg key=value -uv run tangle sdk pipeline-runs details RUN_ID --include-execution-state -uv run tangle sdk pipeline-runs logs EXECUTION_ID -uv run tangle sdk artifacts get RUN_ID -q '{"tasks": {"TaskName": ["output"]}}' +tangle quickstart +tangle sdk pipeline-runs submit pipeline.yaml --arg key=value +tangle sdk pipeline-runs details RUN_ID --include-execution-state +tangle sdk pipeline-runs logs EXECUTION_ID +tangle sdk artifacts get RUN_ID -q '{"tasks": {"TaskName": ["output"]}}' ``` For checking run status, see [`tangle-tools.md`](tangle-tools.md) — prefer the @@ -129,8 +127,8 @@ light status summary (`tangle sdk pipeline-runs status RUN_ID`) and graph-state (`tangle sdk pipeline-runs graph-state EXECUTION_ID`) for polling over the heavy `details … --include-execution-state` payload. -**Do not memorize a static command list.** Run `uv run tangle quickstart` to -discover commands, and `uv run tangle sdk --help` for detailed usage. +**Do not memorize a static command list.** Run `tangle quickstart` to +discover commands, and `tangle sdk --help` for detailed usage. ## 5. Artifacts @@ -140,7 +138,7 @@ backend it is a HuggingFace `hf://…` URI), so read the `uri` field rather than assuming a scheme: ```bash -uv run tangle sdk artifacts get RUN_ID -q '{"tasks": {"TaskName": ["output"]}}' +tangle sdk artifacts get RUN_ID -q '{"tasks": {"TaskName": ["output"]}}' ``` `artifacts get` is **metadata-only** — there is no download-to-disk command. To diff --git a/skills/tangent/references/step-0-initialize.md b/skills/tangent/references/step-0-initialize.md index 6bb9f8d..be39920 100644 --- a/skills/tangent/references/step-0-initialize.md +++ b/skills/tangent/references/step-0-initialize.md @@ -4,17 +4,16 @@ Pure setup — load everything before the experiment loop. No analysis, no decis ## Set up the `tangle` CLI -Before anything else, make sure you can invoke the CLI. The skills drive the OSS -core, run from a checkout of the `tangle-cli` repo: +Before anything else, make sure you can invoke the published CLI: ```bash -uv run tangle --help +tangle --help ``` -If that fails, work through `references/setup.md` first (checkout, `uv tool install tangle-cli`, or `uvx --from tangle-cli tangle …`; base-url/auth). Once `uv run tangle --help` or installed `tangle --help` works, discover the available commands: +If that fails, work through `references/setup.md` first (`uv tool install tangle-cli`, `uvx --from tangle-cli tangle …`, or local checkout validation with `uv run`; base-url/auth). Once `tangle --help` works, discover the available commands: ```bash -uv run tangle quickstart +tangle quickstart ``` > For an installed CLI, prefer `uv tool install tangle-cli` and invoke `tangle …` or `tangle-cli …`; for one-off execution, use `uvx --from tangle-cli tangle …`. @@ -27,10 +26,10 @@ All experiment state lives in the scenario directory. Set the absolute path: SCENARIO_DIR= ``` -From a checkout, all `tangle` commands run via `uv run tangle …`. From an -installed CLI, use `tangle …` / `tangle-cli …`; for one-off execution, use -`uvx --from tangle-cli tangle …`. All file reads/writes use absolute -`SCENARIO_DIR` paths. These are different locations — don't confuse them. +All normal commands use the published CLI (`tangle …` / `tangle-cli …`) or +one-off `uvx --from tangle-cli tangle …`. When intentionally validating a local +`tangle-cli` checkout, prefix examples with `uv run`. All file reads/writes use +absolute `SCENARIO_DIR` paths. These are different locations — don't confuse them. ## No Scenario Yet? Build One @@ -58,8 +57,8 @@ below. ### Resume: Check Active Runs If MEMORY.md "Active Runs" lists runs from a prior session, light-poll each with -the CLI: `uv run tangle sdk pipeline-runs status RUN_ID` (run + derived status -summary), and `uv run tangle sdk pipeline-runs graph-state EXECUTION_ID` for the +the CLI: `tangle sdk pipeline-runs status RUN_ID` (run + derived status +summary), and `tangle sdk pipeline-runs graph-state EXECUTION_ID` for the per-task graph state. Classify: all tasks terminal → Step 5, any RUNNING → Step 4, any FAILED → Step 4 (debugger). This replaces Step 1-3 when resuming. @@ -79,7 +78,7 @@ the latest published component versions when the refs are `name:`/`digest:` only **Option B: Export from baseline run** If no source pipeline exists, export the root spec from the baseline run: ```bash -uv run tangle sdk pipeline-runs export BASELINE_RUN_ID --output $SCENARIO_DIR/pipeline.yaml +tangle sdk pipeline-runs export BASELINE_RUN_ID --output $SCENARIO_DIR/pipeline.yaml ``` `export` writes the root spec as-is. There is no `--dehydrate` flag: if the exported YAML carries full inline `spec:` blocks, `--hydrate` on submit is a no-op @@ -94,8 +93,8 @@ submitting. 3. Initialize `$SCENARIO_DIR/logs/events.jsonl` (create if it doesn't exist) ## Gate — do NOT proceed to Step 1 until all pass: -- [ ] `uv run tangle --help` works (CLI reachable; see `references/setup.md` if not) -- [ ] `uv run tangle quickstart` ran successfully +- [ ] `tangle --help` works via the published CLI (or `uvx --from tangle-cli tangle --help` for one-off execution) +- [ ] `tangle quickstart` ran successfully - [ ] `SCENARIO_DIR` set to absolute path - [ ] `scenario.yaml` read and understood - [ ] `MEMORY.md` read diff --git a/skills/tangent/references/step-3-submit.md b/skills/tangent/references/step-3-submit.md index 3034d94..1a948a2 100644 --- a/skills/tangent/references/step-3-submit.md +++ b/skills/tangent/references/step-3-submit.md @@ -28,7 +28,7 @@ Auto-loop bookkeeping rides along as generic `--annotation K=V` pairs: ```bash # experiment args + auto-loop annotations, assembled on the submit line -uv run tangle sdk pipeline-runs submit $SCENARIO_DIR/pipeline.yaml \ +tangle sdk pipeline-runs submit $SCENARIO_DIR/pipeline.yaml \ --arg = \ --annotation session=YYYY-MM-DD- \ --annotation round= \ @@ -77,8 +77,8 @@ fi # in the pipeline must exist under the authenticating identity. A typoed or # not-yet-created name passes step 1 (it's not a credential body) but fails # at runtime, which wastes budget and confuses the user. -# Run under `uv run` so the project env (incl. PyYAML) is available — bare -# python3 may not have PyYAML, per the bundle's uv-run rule (OSS-CONVENTIONS §1). +# Run the helper in a Python environment with PyYAML available. `uv run` is shown +# for scenario repos that manage dependencies with uv; this is not a Tangle CLI invocation. uv run python3 - <<'PY' "$SCENARIO_DIR/pipeline.yaml" import sys, yaml, subprocess, json path = sys.argv[1] @@ -106,7 +106,7 @@ if missing: sys.stderr.write( "ERROR: pipeline references Tangle secrets that don't exist under the " "authenticating identity: " + ", ".join(missing) + "\n" - " Ask the human to create them via: uv run tangle sdk secrets create --from-env \n" + " Ask the human to create them via: tangle sdk secrets create --from-env \n" " (see references/secrets.md § 'If the secret is missing, ask the human to create it').\n" ) sys.exit(1) @@ -127,7 +127,7 @@ stop, surface the failure to the human, and do not submit. ### Submit (only after every pre-submit check above exited cleanly) ```bash -uv run tangle sdk pipeline-runs submit $SCENARIO_DIR/pipeline.yaml \ +tangle sdk pipeline-runs submit $SCENARIO_DIR/pipeline.yaml \ --arg = \ --annotation session=YYYY-MM-DD- \ --annotation round= \ @@ -137,11 +137,11 @@ uv run tangle sdk pipeline-runs submit $SCENARIO_DIR/pipeline.yaml \ Hydration is the default, so component versions are resolved as part of submit. `submit` returns as soon as the run is created — it does **not** wait. To block -on completion, follow up with `uv run tangle sdk pipeline-runs wait RUN_ID`. +on completion, follow up with `tangle sdk pipeline-runs wait RUN_ID`. ### If you modified component source code: 1. Rebuild from your Python source, pointing at the image you built and pushed - yourself: `uv run tangle sdk components generate from-python source.py --image --output component.yaml` + yourself: `tangle sdk components generate from-python source.py --image --output component.yaml` 2. Update ref in pipeline YAML: swap `digest: ...` with `url: file://` 3. Submit with the command above @@ -149,14 +149,14 @@ See `agents/builder.md` for the full workflow. ## Post-Submission -`uv run tangle sdk pipeline-runs submit` returns a **`run_id`** for each submitted +`tangle sdk pipeline-runs submit` returns a **`run_id`** for each submitted pipeline. Treat `run_id` as a first-class session concept: 1. Log to `sessions/YYYY-MM-DD.md` — record the `run_id` in a `## Run Log` section with timestamp, round, label, config diff. Order is chronological. 2. **Write to MEMORY.md "Active Runs" immediately** — `run_id`, run link (`/runs/`, or inspect via - `uv run tangle sdk pipeline-runs details RUN_ID`), label, config summary, + `tangle sdk pipeline-runs details RUN_ID`), label, config summary, timestamp. Survives session interruptions. 3. The `run_id` is what keys learnings records in Step 7 (`learning-.json` under `$LEARNINGS_DIR//`), so make sure diff --git a/skills/tangent/references/step-4-monitor.md b/skills/tangent/references/step-4-monitor.md index 6d8502e..7a12d3e 100644 --- a/skills/tangent/references/step-4-monitor.md +++ b/skills/tangent/references/step-4-monitor.md @@ -29,19 +29,19 @@ and graph state, the CLI commands below are the supported path). Light status for a single run (run + derived status summary): ```bash -uv run tangle sdk pipeline-runs status RUN_ID +tangle sdk pipeline-runs status RUN_ID ``` Graph execution state (per-task status counts; takes an EXECUTION_ID): ```bash -uv run tangle sdk pipeline-runs graph-state EXECUTION_ID +tangle sdk pipeline-runs graph-state EXECUTION_ID ``` For multiple runs, call `status` once per run id: ```bash for rid in RUN_1 RUN_2 RUN_3; do echo "$rid:" - uv run tangle sdk pipeline-runs status "$rid" + tangle sdk pipeline-runs status "$rid" done ``` @@ -54,7 +54,7 @@ Mark runs exceeding 2x `scenario.timing.total_seconds` as STUCK and replace. When a run completes (SUCCEEDED or FAILED), immediately run: ```bash -uv run tangle sdk pipeline-runs details RUN_ID --include-execution-state +tangle sdk pipeline-runs details RUN_ID --include-execution-state ``` This returns the execution tree with per-component status. Check for: @@ -99,14 +99,14 @@ Act on the diagnosis: Only cancel when the user asks or a run is blocking resources. ```bash -uv run tangle sdk pipeline-runs cancel RUN_ID +tangle sdk pipeline-runs cancel RUN_ID ``` ## Waiting Use `dispatch` for non-blocking wait (if available), or sleep between light polls: ``` -dispatch({ command: "uv run tangle sdk pipeline-runs wait --max-wait --poll-interval 10 --exit-on-first-failure" }) +dispatch({ command: "tangle sdk pipeline-runs wait --max-wait --poll-interval 10 --exit-on-first-failure" }) ``` Interval: 180s (short pipelines), 600s (medium), 900s (long). `wait` defaults to `--max-wait 600` and `--poll-interval 10` if you omit them. diff --git a/skills/tangent/references/step-5-evaluate.md b/skills/tangent/references/step-5-evaluate.md index 6fdd180..d472c55 100644 --- a/skills/tangent/references/step-5-evaluate.md +++ b/skills/tangent/references/step-5-evaluate.md @@ -5,7 +5,7 @@ Two parts: collect metrics, then analyze. ## Part 1: Collect Metrics For each completed run: -1. Get artifact metadata for the eval task with `uv run tangle sdk artifacts get RUN_ID -q '{"tasks": {"": [""]}}'`. This returns metadata records (`{id, uri, size, hash}`) — it does **not** download bytes. Read the `uri` scheme-agnostically (under the OSS backend it is typically `hf://…`); never assume a particular storage scheme. To read the metric JSON contents, follow the signed-URL fetch recipe in [`OSS-CONVENTIONS.md`](../OSS-CONVENTIONS.md) §5: `artifacts get` → `tangle api artifacts signed-artifact-url` → fetch with `curl -L` (or `huggingface_hub` for `hf://` URIs). +1. Get artifact metadata for the eval task with `tangle sdk artifacts get RUN_ID -q '{"tasks": {"": [""]}}'`. This returns metadata records (`{id, uri, size, hash}`) — it does **not** download bytes. Read the `uri` scheme-agnostically (under the OSS backend it is typically `hf://…`); never assume a particular storage scheme. To read the metric JSON contents, follow the signed-URL fetch recipe in [`OSS-CONVENTIONS.md`](../OSS-CONVENTIONS.md) §5: `artifacts get` → `tangle api artifacts signed-artifact-url` → fetch with `curl -L` (or `huggingface_hub` for `hf://` URIs). 2. Extract target metric (`scenario.metrics.target.path`) and common metrics 3. Check guard metrics (`scenario.metrics.guards`) 4. Remove from MEMORY.md "Active Runs" @@ -19,7 +19,7 @@ Present results sorted by target metric. Include all common metrics. For the best run and any anomalous results, fetch container logs from the training component: ```bash -uv run tangle sdk pipeline-runs logs EXECUTION_ID +tangle sdk pipeline-runs logs EXECUTION_ID ``` Use the execution_id recorded in Step 4 (logs are keyed by EXECUTION_ID, not run id). Look for: - Training convergence (loss progression) diff --git a/skills/tangent/references/tangle-tools.md b/skills/tangent/references/tangle-tools.md index 308db35..4873668 100644 --- a/skills/tangent/references/tangle-tools.md +++ b/skills/tangent/references/tangle-tools.md @@ -14,38 +14,36 @@ with new commands and flags — discover the current surface with `--help` and ## Install / Invoke -From a checkout, run commands as `uv run tangle …`: - -```bash -uv run tangle quickstart -uv run tangle --help -uv run tangle sdk --help -uv run tangle api --help -``` - -For a persistent user-level CLI install, prefer uv tools: +For normal Tangent usage, install the published CLI as a persistent uv tool: ```bash uv tool install tangle-cli tangle quickstart -tangle-cli --help +tangle --help +tangle sdk --help +tangle api --help ``` For one-off execution without a persistent install, use `uvx`: ```bash uvx --from tangle-cli tangle --help +uvx --from tangle-cli tangle quickstart ``` Generic Python environments may also use `pip install tangle-cli`; use `uv pip install tangle-cli` only inside an explicitly managed virtualenv. +When intentionally validating a local checkout of the `tangle-cli` repo, prefix +examples with `uv run` (for example, `uv run tangle quickstart`). Skill examples +otherwise use the installed-tool form (`tangle …` / `tangle-cli …`). + The default `tangle-cli` install includes `tangle-api` and enables static API-backed commands plus the handwritten `TangleApiClient` (see [Programmatic client](#programmatic-client-python)). In the `tangle-cli` workspace, `uv` installs the workspace `tangle-api` package automatically for dev/tests. The old `native` extra is a compatibility/no-op alias. ## Discover Available Commands ```bash -uv run tangle quickstart +tangle quickstart ``` This prints static onboarding text. Use it at the start of every session to learn @@ -57,12 +55,12 @@ Help is standard cyclopts `--help` — there is no `--help-extended` / `--help-full`: ```bash -uv run tangle sdk --help -uv run tangle api --help +tangle sdk --help +tangle api --help ``` For broader docs, point at `tangle sdk --help`, the curated standard -library (`uv run tangle sdk published-components library`), and the public OSS +library (`tangle sdk published-components library`), and the public OSS docs at `github.com/TangleML/website/tree/master/docs`. ## Running Commands @@ -72,8 +70,8 @@ wrappers) and `tangle sdk …` (hand-written SDK / local / compound commands). Most workflow commands live under `tangle sdk`: ```bash -uv run tangle sdk pipeline-runs submit pipeline.yaml --arg shop=acme --annotation session=2026-06-23-ranking -uv run tangle sdk pipeline-runs details RUN_ID --include-execution-state +tangle sdk pipeline-runs submit pipeline.yaml --arg shop=acme --annotation session=2026-06-23-ranking +tangle sdk pipeline-runs details RUN_ID --include-execution-state ``` Auth flags (see [Auth & environment](#auth--environment)) attach to any @@ -104,10 +102,10 @@ There is **no** `-f config.yaml`. Pass pipeline run arguments with repeatable file is preferred): ```bash -uv run tangle sdk pipeline-runs submit pipeline.yaml \ +tangle sdk pipeline-runs submit pipeline.yaml \ --arg model=baseline --arg epochs=3 -uv run tangle sdk pipeline-runs submit pipeline.yaml \ +tangle sdk pipeline-runs submit pipeline.yaml \ --args-json '{"model": "baseline", "epochs": 3}' ``` @@ -128,7 +126,7 @@ searchable; all are optional: | `source` | `tangle-cli` | Optional provenance marker (only if you want it) | ```bash -uv run tangle sdk pipeline-runs submit pipeline.yaml \ +tangle sdk pipeline-runs submit pipeline.yaml \ --arg model=baseline \ --annotation session=2026-06-23-ranking \ --annotation round=1 \ @@ -139,15 +137,15 @@ uv run tangle sdk pipeline-runs submit pipeline.yaml \ Or set after submission: ```bash -uv run tangle sdk pipeline-runs annotations set RUN_ID session 2026-06-23-ranking -uv run tangle sdk pipeline-runs annotations list RUN_ID -uv run tangle sdk pipeline-runs annotations delete RUN_ID round +tangle sdk pipeline-runs annotations set RUN_ID session 2026-06-23-ranking +tangle sdk pipeline-runs annotations list RUN_ID +tangle sdk pipeline-runs annotations delete RUN_ID round ``` ### Preview without submitting ```bash -uv run tangle sdk pipeline-runs submit pipeline.yaml --dry-run +tangle sdk pipeline-runs submit pipeline.yaml --dry-run ``` `--dry-run` prints the submit body and creates no run. @@ -155,7 +153,7 @@ uv run tangle sdk pipeline-runs submit pipeline.yaml --dry-run ### Canonical submit command ```bash -uv run tangle sdk pipeline-runs submit pipeline.yaml \ +tangle sdk pipeline-runs submit pipeline.yaml \ --arg K=V --annotation session=YYYY-MM-DD-scenario ``` @@ -164,10 +162,10 @@ uv run tangle sdk pipeline-runs submit pipeline.yaml \ Local pipeline operations live under `pipelines` (NOT `pipeline-runs`): ```bash -uv run tangle sdk pipelines validate pipeline.yaml -uv run tangle sdk pipelines layout pipeline.yaml [--recursive] [-o out.yaml] -uv run tangle sdk pipelines hydrate template.yaml -o out.yaml [--var K=V] -uv run tangle sdk pipelines diagram pipeline.yaml # Mermaid (no GUI viewer) +tangle sdk pipelines validate pipeline.yaml +tangle sdk pipelines layout pipeline.yaml [--recursive] [-o out.yaml] +tangle sdk pipelines hydrate template.yaml -o out.yaml [--var K=V] +tangle sdk pipelines diagram pipeline.yaml # Mermaid (no GUI viewer) ``` There is no `dehydrate` command or `--dehydrate` flag in OSS. To iterate on an @@ -180,18 +178,18 @@ the default) — see [`references/iterating-on-runs.md`](iterating-on-runs.md). hand-rolled Python loop: ```bash -uv run tangle sdk pipeline-runs status RUN_ID # run + derived status summary -uv run tangle sdk pipeline-runs graph-state EXECUTION_ID # graph execution state +tangle sdk pipeline-runs status RUN_ID # run + derived status summary +tangle sdk pipeline-runs graph-state EXECUTION_ID # graph execution state ``` **Heavy** — use only after completion, for debugging or extracting `execution_id`s: ```bash -uv run tangle sdk pipeline-runs details RUN_ID --include-execution-state -uv run tangle sdk pipeline-runs details RUN_ID --include-implementations -uv run tangle sdk pipeline-runs details RUN_ID --include-annotations -uv run tangle sdk pipeline-runs details RUN_ID --execution-id EXEC_ID +tangle sdk pipeline-runs details RUN_ID --include-execution-state +tangle sdk pipeline-runs details RUN_ID --include-implementations +tangle sdk pipeline-runs details RUN_ID --include-annotations +tangle sdk pipeline-runs details RUN_ID --execution-id EXEC_ID ``` ## Waiting / Polling @@ -199,7 +197,7 @@ uv run tangle sdk pipeline-runs details RUN_ID --execution-id EXEC_ID To block until a run completes (bounded): ```bash -uv run tangle sdk pipeline-runs wait RUN_ID \ +tangle sdk pipeline-runs wait RUN_ID \ --max-wait 600 --poll-interval 10 [--exit-on-first-failure] ``` @@ -208,7 +206,7 @@ Defaults: `--max-wait` 600s, `--poll-interval` 10s. ## Searching Runs ```bash -uv run tangle sdk pipeline-runs search --name NAME \ +tangle sdk pipeline-runs search --name NAME \ [--created-by USER] [--annotation K=V] \ [--start-date DATE] [--end-date DATE] [--limit N] [--query JSON] [QUERY] ``` @@ -216,7 +214,7 @@ uv run tangle sdk pipeline-runs search --name NAME \ ## Exporting a Run ```bash -uv run tangle sdk pipeline-runs export RUN_ID --output out.yaml # omit --output to print to stdout +tangle sdk pipeline-runs export RUN_ID --output out.yaml # omit --output to print to stdout ``` Exports the root spec as-is; there is no `--dehydrate`. @@ -226,7 +224,7 @@ Exports the root spec as-is; there is no `--dehydrate`. For application logs (stack traces, code errors), keyed by **EXECUTION_ID**: ```bash -uv run tangle sdk pipeline-runs logs EXECUTION_ID +tangle sdk pipeline-runs logs EXECUTION_ID ``` This backend-native container log surface is the **only** log surface the Tangle @@ -259,7 +257,7 @@ diagnosis, lean on container logs plus your launcher's native events — see `hf://datasets//@/`. ```bash -uv run tangle sdk artifacts get RUN_ID -q '{"artifact_ids":[""]}' +tangle sdk artifacts get RUN_ID -q '{"artifact_ids":[""]}' ``` `-q`/`--query` is a JSON string with optional keys `tasks`, `components`, @@ -271,7 +269,7 @@ standard recipe — see [`OSS-CONVENTIONS.md` §5](../OSS-CONVENTIONS.md)): 1. Get metadata and read the `uri` (above). 2. Ask the backend for a signed URL: ```bash - uv run tangle api artifacts signed-artifact-url --id + tangle api artifacts signed-artifact-url --id ``` 3. Fetch with a generic client — `curl -L "" -o ./out`, or for `hf://` URIs `huggingface_hub` (`hf_hub_download` / `snapshot_download`). @@ -286,12 +284,12 @@ Local authoring lives under `components`; the registry lives under ```bash # Generate a component from a Python source file (user-built image) -uv run tangle sdk components generate from-python source.py \ +tangle sdk components generate from-python source.py \ [--function NAME] [--image REG/IMG:TAG] [--output OUT] [--name NAME] \ [--mode inline|bundle] [--dependencies-from REQ] [--strip-code] [--resolve-root DIR] # Bump a local component's version -uv run tangle sdk components bump-version component.yaml [--set-version V] [--update-timestamp] +tangle sdk components bump-version component.yaml [--set-version V] [--update-timestamp] ``` There is no image build/push in the CLI. Build and push the image yourself (your @@ -301,22 +299,22 @@ own docker/podman), then pass `--image ` to ```bash # Publish to the registry -uv run tangle sdk published-components publish component.yaml \ +tangle sdk published-components publish component.yaml \ [--image …] [--name …] [--description …] [--annotations JSON] [--dry-run] [--published-by …] # Inspect (exactly one of NAME or --digest) -uv run tangle sdk published-components inspect --name NAME --full-spec -uv run tangle sdk published-components inspect --digest DIGEST +tangle sdk published-components inspect --name NAME --full-spec +tangle sdk published-components inspect --digest DIGEST # Search — keyword/name/digest only -uv run tangle sdk published-components search NAME \ +tangle sdk published-components search NAME \ [--digest D] [--published-by U] [--include-deprecated] # Deprecate -uv run tangle sdk published-components deprecate DIGEST [--superseded-by DIGEST] +tangle sdk published-components deprecate DIGEST [--superseded-by DIGEST] # Curated standard library -uv run tangle sdk published-components library +tangle sdk published-components library ``` To publish many components at once, pass a `--config` YAML/JSON list (or @@ -331,10 +329,10 @@ fresh install — never a hard prerequisite of a workflow step. ## Secrets ```bash -uv run tangle sdk secrets list -uv run tangle sdk secrets create NAME --from-env ENVVAR [-d DESCRIPTION] [--expires-at WHEN] -uv run tangle sdk secrets update NAME --from-env ENVVAR -uv run tangle sdk secrets delete NAME [--force] +tangle sdk secrets list +tangle sdk secrets create NAME --from-env ENVVAR [-d DESCRIPTION] [--expires-at WHEN] +tangle sdk secrets update NAME --from-env ENVVAR +tangle sdk secrets delete NAME [--force] ``` Prefer `--from-env`/`-e ENVVAR` over `--value`/`-v` to avoid leaking the value @@ -344,7 +342,7 @@ authenticating identity — see [`references/secrets.md`](secrets.md). ## Cancelling a Run ```bash -uv run tangle sdk pipeline-runs cancel RUN_ID +tangle sdk pipeline-runs cancel RUN_ID ``` ## Programmatic client (Python) @@ -396,12 +394,12 @@ environment default. There is no `auth` command group. | — | `TANGLE_VERBOSE=1` | Redacted HTTP request/response diagnostics. | Run links: there is no hosted dashboard URL to assume — use `/runs/` -or inspect via `uv run tangle sdk pipeline-runs details RUN_ID`. +or inspect via `tangle sdk pipeline-runs details RUN_ID`. Example for a protected backend: ```bash -uv run tangle sdk pipeline-runs submit pipeline.yaml \ +tangle sdk pipeline-runs submit pipeline.yaml \ --base-url https://api.example \ --auth-header 'Bearer …' \ -H 'X-Gateway-Auth: …' \ diff --git a/skills/tangent/references/uploading-artifacts.md b/skills/tangent/references/uploading-artifacts.md index d4896f1..0c1b2c7 100644 --- a/skills/tangent/references/uploading-artifacts.md +++ b/skills/tangent/references/uploading-artifacts.md @@ -18,8 +18,8 @@ it into a pipeline — that hides the dependency from the graph. > **Backend-dependent.** The OSS `tangle` core does **not** ship a built-in ingest > component. Whether one is available — and what its name, inputs, and outputs are > — depends on what components your backend has published. Discover what's -> available with `uv run tangle sdk published-components library` and -> `uv run tangle sdk published-components search ` (search is **optional** and +> available with `tangle sdk published-components library` and +> `tangle sdk published-components search ` (search is **optional** and > may return empty on a fresh OSS install — see > [`OSS-CONVENTIONS.md` §10 D11](../OSS-CONVENTIONS.md)). If your backend provides > no ingest component at all, fall back to a Python component that reads the URI @@ -38,9 +38,9 @@ A typical ingest component looks like this: Inspect whatever your backend provides before wiring it in: ```bash -uv run tangle sdk published-components inspect --name "" --full-spec +tangle sdk published-components inspect --name "" --full-spec # or, if you already have the digest: -uv run tangle sdk published-components inspect --digest --full-spec +tangle sdk published-components inspect --digest --full-spec ``` ## Recipe A — Add a new ingest task to an existing pipeline @@ -51,7 +51,7 @@ external evaluation set. 1. **Export the pipeline's root spec** so you can edit it locally: ```bash - uv run tangle sdk pipeline-runs export --output /tmp/pipeline.yaml + tangle sdk pipeline-runs export --output /tmp/pipeline.yaml ``` `export` writes the root spec as-is (there is no `--dehydrate`; omit `--output` to print to stdout). To iterate on the run, hand-edit this file and `submit` it — @@ -87,10 +87,10 @@ external evaluation set. 4. **Validate, then submit** (hydrate is the default; `submit` never waits — block afterward with `pipeline-runs wait` if you need to): ```bash - uv run tangle sdk pipelines validate /tmp/pipeline.yaml - uv run tangle sdk pipeline-runs submit /tmp/pipeline.yaml \ + tangle sdk pipelines validate /tmp/pipeline.yaml + tangle sdk pipeline-runs submit /tmp/pipeline.yaml \ --arg input_artifact_uri="://path/to/artifact/" - uv run tangle sdk pipeline-runs wait --max-wait 600 + tangle sdk pipeline-runs wait --max-wait 600 ``` (Pass `--arg` only if you wired the URI as a `graphInput` in step 2; for a @@ -141,10 +141,10 @@ staged variants. 3. Supply the URI per run with `--arg` (or `--args-json`). **Run arguments bind to the pipeline's top-level `inputs:`** — they are distinct from task-level `arguments:` wiring inside the pipeline YAML (as shown in step 2 above). See - `uv run tangle sdk pipeline-runs submit --help` for the full surface, and + `tangle sdk pipeline-runs submit --help` for the full surface, and [`references/tangle-tools.md`](tangle-tools.md) for the canonical submit form. ```bash - uv run tangle sdk pipeline-runs submit pipeline.yaml \ + tangle sdk pipeline-runs submit pipeline.yaml \ --arg input_artifact_uri="://path/to/artifact/" ``` @@ -215,7 +215,7 @@ hard-coded into the YAML. - **No ingest component? Read the URI in a Python component.** If your backend registers no ingest component, generate a small one from a Python source file that fetches the URI and writes a `Data` output: - `uv run tangle sdk components generate from-python fetch.py --image ` + `tangle sdk components generate from-python fetch.py --image ` (build/push the image yourself; `set-container-image` is a stub — do not use it). See [`agents/builder.md`](../agents/builder.md). - **Don't hand-roll throwaway ingest.** If you find yourself shelling out to copy diff --git a/tests/test_packaging.py b/tests/test_packaging.py index f083f6a..41106c4 100644 --- a/tests/test_packaging.py +++ b/tests/test_packaging.py @@ -144,8 +144,11 @@ def test_tangent_skill_bundle_is_in_repo_and_current() -> None: assert "not yet a public PyPI package" not in markdown assert "pip install 'tangle-cli[native]'" not in markdown assert "uv install" not in markdown + assert "Run commands as `tangle …` from a checkout" not in markdown + assert "Published-package usage is the default" in markdown assert "uv tool install tangle-cli" in markdown assert "uvx --from tangle-cli tangle" in markdown + assert "installed-tool form" in markdown assert "uv pip install tangle-cli` only inside an explicitly managed virtualenv" in markdown assert "pip install tangle-cli" in markdown assert "compatibility/no-op" in markdown