Skip to content

Data Director

Purpose

A reference implementation of the RDA Data Director Agentic AI Blueprint, officially adopted by the RDA and published at https://doi.org/10.15497/RDA00157.

Working here

  • Prototype and exploratory agents live in agents/<name>/ like any other agent, marked as alpha by their pyproject.toml version (agents/README.md) rather than kept in a separate non-authoritative tree.
  • app/ is the Data Director app that people use (alpha, app/README.md). It must not depend on workbench/, which is for development only. It runs agents through the harness's conductor, with its own configuration in app/config/. Its browser shell (app/web, React and TypeScript, The app) is drawn from each agent's manifest and names no agent; it renders the harness's decisions and holds no policy. docs/ui/best-practices.md is its design input.
  • The repository root is a uv workspace. harness/ (dd_harness) governs agents against one contract: the conductor, policy gate, input check, grounding linter, source check, run store and provenance, with an A2A way in (harness/README.md, System and boundaries), and its test kit dd_harness.testing. It depends only on sdk/ and must not import the workbench, the app or an agent. workbench/ is the development way in to the harness (see below). agents/ holds one package and one A2A service per agent (agents/README.md). sdk/ is what agents and the harness share: the contract, evidence, span helpers and the agent server. inventory/ is dd-inventory, the command a researcher runs where their data live to describe a dataset's files (Projects); it depends on no other member. Tooling config is in the root pyproject.toml.
  • Each workspace member keeps to its own directory: it imports only what it declares (tests from its own dev group) and reads no path outside itself. System and boundaries says why, and what may live in other repositories of the organisation.
  • docs/blueprint/ is the published Blueprint v1.0 reproduced verbatim (RDA, CC BY 4.0, https://doi.org/10.15497/RDA00157), one file per chapter; README.md there has the contents. Read the chapter you need: the requirements are in 07-functional-specification.md, each with an anchor (#r3, #c5). Requirements are cited by ID (R3, R3.1, …) throughout the repo. Treat it as read-only external material, not project prose to improve: the files are generated by scripts/blueprint/convert.py and checked against the PDF by scripts/blueprint/check_text.py.

The workbench

workbench/ is a test bed for the engineers and testers who write Data Director sub-agents. It is not the reference implementation itself, and it contains neither agent code nor governance code. Through the harness, it calls each agent over A2A, checks that the agent kept to the contract, and records every run so that a person can inspect what the agent did and why.

  • src/workbench/: the workbench CLI, the AG-UI transport, evaluation (evaluation.py) and config.py, the development configuration it supplies to the harness. The conductor itself, which alone fills identifiers, timestamps and lineage, is in harness/src/dd_harness/.
  • agents.yaml: the registry of agent URLs. profiles/ holds institutional profiles (what an instance may do), sources.yaml the pinned source copies, and samples/ example inputs.
  • viewer/: the browser UI served by workbench serve, with an Inspect page and a Chat page.
  • docs/: architecture.md is the overview and walkthrough.md follows one run.

Documents are kept with what they describe. harness/docs/ describes the conductor, grounding and the registry. The repository-level docs/ holds what governs every package: the system overview (architecture.md), the specifications in docs/specs/, the contract, the glossary, the requirements register (requirements.yaml) and the review record (reviews.yaml).

A specification states how one part is meant to work today and why; docs/specs/README.md says what belongs in one. A change to the design changes its spec in the same pull request, edited to say what is now true rather than amended. Changing a fixed format (schema, dd.* trace attributes, evidence canonicalisation, outcome vocabulary) always changes a spec. CONFORMANCE.md, at the root, is generated by scripts/conformance_report.py; do not edit it by hand.

Read workbench/AGENTS.md before changing anything here or in harness/.

Committing

Every commit must be signed off under the Developer Certificate of Origin — git commit -s. Unsigned commits are rejected at review.

Issues and labels

The kind of an issue is its GitHub issue type (Task, Bug or Feature), not a label; an umbrella issue is a parent with sub-issues. Labels say where and what about:

  • area: … — the part touched: sdk, harness, workbench, app, agents, docs, ci. One or more per issue.
  • Themes: blueprint (review or conformance against the Blueprint), security, evaluation, accessibility, and needs spec for a change to a fixed format.
  • good first issue, help wanted and blocked (waiting on something outside the project).

Pull requests carry their kind and scope in the Conventional Commit title, so they take no labels by hand. dependencies, python:uv, javascript and autorelease: … are applied by Dependabot and release-please; leave them alone.

Pull requests are squash-merged and release-please reads the title as the commit subject, so a PR title is a Conventional Commit: type(scope)!: summary, with a lower-case summary and no closing full stop (feat(app): register every in-tree agent). A branch name is lower-case words joined by hyphens, optionally grouped with slashes (ci-faster). .github/workflows/names.yml checks both; check locally with python3 scripts/check_names.py --title "…" --branch "$(git branch --show-current)".

Workflows

CI runs zizmor and actionlint over .github/ (blanket policy, no unpinned actions). Pin every uses: to a full commit SHA with the version as a trailing comment (# v1.2.3), and run uvx zizmor .github before pushing any change to a workflow.

Writing conventions

British English (organisation, behaviour, licence as noun). Declarative prose for a mixed audience of researchers and engineers; no hype. Mark undecided matters with an explicit TODO(#123) rather than filling in a plausible guess. The reference, directly after the word, is the issue that will resolve it: open one if none fits, or list several, TODO(#41, #57). scripts/check_todos.py rejects a bare marker anywhere git tracks except docs/blueprint/, and CI runs it.