Registry formula specification

A formula is the submission format for publishing a package to the kdeps registry. It is a YAML document that tells kdeps registry install where to download the package and how to verify it.

Applies to both workflow mode and agent mode.

Formulas are the submission layer. You PR a formula file to get listed. The registry at kdeps.io runs on a database - formulas are ingested on merge and served from the DB for browsing, search, and install metadata.

Formulas live in github.com/kdeps/registry under formulas/<name>.yaml. To publish a package, open a PR adding your formula.

Formula fields

# formulas/my-agent.yaml
name: my-agent                         # required - unique package name in the registry
version: 1.2.0                         # required - semantic version
type: agent                            # required - component | workflow | agency
github: owner/repo                     # required - GitHub owner/repo containing the release
tarball: https://github.com/owner/repo/archive/refs/tags/v1.2.0.tar.gz  # required
sha256: abc123...                      # required - SHA256 of the tarball; computed by kdeps registry submit
description: A one-line summary.       # required
tags: [llm, chat]                      # optional - search keywords
license: Apache-2.0                    # optional - SPDX identifier

Field reference

Field	Required	Description
name	yes	Unique package name. Lowercase, alphanumeric + hyphens.
version	yes	Semantic version (1.2.0). One formula per version.
type	yes	component, workflow, or agency. Must match the manifest kind in the tarball.
github	yes	owner/repo string. The repo containing the tagged release.
tarball	yes	Full URL to the release tarball. Use GitHub's /archive/refs/tags/v{version}.tar.gz pattern.
sha256	yes	Hex-encoded SHA256 of the tarball. Computed by kdeps registry submit --tag.
description	yes	One sentence describing what the package does.
tags	no	List of search keywords. Use lowercase, no spaces.
license	no	SPDX license identifier (MIT, Apache-2.0, etc.).

Package types

Component

A reusable resource bundle invoked via component: in any workflow. Manifest: kind: Component, archive: .komponent.

type: component

Example: scraper, search, browser, tts, email

Workflow

A complete DAG pipeline that runs standalone via kdeps run. Manifest: kind: Workflow, archive: .kdeps.

type: workflow

Example: summarizer, classifier, invoice-extractor

Agency

A multi-agent orchestration bundle. Manifest: kind: Agency, archive: .kagency.

type: agency

Example: cv-matcher, research-pipeline

Publishing workflow

1. Create a release

Tag your repo with a semantic version:

git tag v1.2.0 && git push --tags

The tag must match the version field in the formula.

2. Generate the formula

Run kdeps registry submit from your package directory:

cd my-package/
kdeps registry submit --tag v1.2.0

This downloads the tarball, computes the SHA256, and prints the formula YAML.

3. Submit a PR

Open a pull request to github.com/kdeps/registry adding the formula as formulas/<name>.yaml. One formula file per package per version. The PR is reviewed for:

• Unique name (no collisions)
• Valid SHA256 (tarball matches)
• Manifest kind matches formula type
• Description is present and meaningful

4. Install

Once merged, anyone can install:

kdeps registry install my-agent

Repository layout

The registry repo structure:

registry/
  formulas/
    scraper.yaml
    search.yaml
    summarizer.yaml
    cv-matcher.yaml
    ...
  README.md

No nested directories. Flat formulas/ folder. One file per package name. Version bumps update the existing file.

See also

• Registry commands - install, search, publish, verify
• Components reference - component.yaml reference
• Packaging commands - archive formats