waldronlab / waldronlab/agent-protocol-standard

Define a canonical fully-qualified name syntax for protocols

Open
#24 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
3
Forks
1
Avg merge
14h 8m
Merged PRs (30d)
23

Description

As the federation grows, name collisions across repositories are inevitable — deseq2-differential-expression is not a name any one lab owns. The protocols_used object already disambiguates in frontmatter, but there is no canonical string form for naming a protocol unambiguously in a log line, a provenance block, a tool call, or a sentence.

The runner already needs this. Step 2.1 treats a user-named repository or version as a hard filter — "the waldronlab/agent-protocols version", "v1.2.0" — but there is no defined way to write that reference down. The behavior exists; the syntax for invoking it does not.

Proposed

Define a canonical fully-qualified form in PROTOCOL_STANDARD.md:

<owner>/<repository>::<protocol-name>@<version>
waldronlab/agent-protocols::humann4-sgb-aggregation@1.0.0

:: separates repository from protocol because a bare @repository/protocol collides with version pinning, and because repository names cannot contain ::. Since protocols_used.version is an exact requirement rather than a minimum, the version belongs in the canonical form; a reference without one is a query, not an identifier.

Standardize it for:

  • agent tool calls and user requests,
  • execution logs,
  • the Method Provenance block,
  • the departures summary and drafted Methods section.
Scope: display and reference, not storage

The three-field object form in protocols_used stays:

protocols_used:
  - name: humann4-sgb-aggregation
    repository: waldronlab/agent-protocols
    version: 1.0.0

It is what the validator checks, it is more readable in YAML, and it diffs field-by-field. This issue adds a string rendering for the places a YAML object cannot go — it is not a migration of the frontmatter, and the two forms must round-trip.

Notes
  • The grammar needs to say what is permitted in each position so the form is parseable rather than merely conventional; protocol names are already constrained to kebab-case by PROTOCOL_STANDARD.md.
  • Worth deciding whether a version-less owner/repo::name is legal as an explicit "any version" query, or whether that ambiguity is best refused outright. Given that the runner aborts rather than substituting a different release, refusing is more consistent.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading PROTOCOL_STANDARD.md, especially the existing kebab-case protocol-name constraint and the protocols_used object definition. Specify the grammar and version requirement for the fully-qualified string, resolve the version-less query question, and document its use in tool calls, requests, logs, provenance, departures, and Methods text. Done means the string and object forms round-trip without changing storage.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.