avsm/ai-disclosure

OCaml AI Content Disclosure

When to Use

Annotate AI disclosure when you:

• Generate new OCaml modules or functions
• Edit existing OCaml code with AI assistance
• Create or modify .opam files for packages with AI-involved code

Disclosure Values

Four values, identical to the W3C AI Content Disclosure vocabulary:

| Value | When to use | |-------|-------------| | none | Positive assertion: no AI was involved | | ai-assisted | Human-authored, AI edited or refined | | ai-generated | AI-generated with human prompting/review | | autonomous | AI-generated without human oversight |

No annotation = unknown. Only use none as an affirmative claim.

Granularity Rules

Prefer per-module. Use per-item only when individual bindings differ.

1. If the entire file has a single disclosure level, use a module-level floating attribute.
2. If most of the file shares one level but a few items differ, use module-level for the dominant level and item-level overrides for exceptions.
3. Never annotate every function individually when a single module-level attribute suffices.

Declare the dominant level; tooling infers heterogeneity from overrides.

Syntax

Module-level (floating attribute, applies to entire file)

[@@@ai_disclosure "ai-generated"]
[@@@ai_model "claude-opus-4"]
[@@@ai_provider "Anthropic"]

Raplce the ai_model and ai_provider with your own information. Place these after any copyright header and open statements, before the first definition.

Item-level (declaration attribute, applies to one binding)

let merge_sort xs =
  ...
[@@ai_disclosure "ai-assisted"]

Interface files (.mli)

Annotate .mli independently of .ml. The interface records AI involvement in API design; the implementation records AI involvement in code.

opam Package Level

For each package in the project, create or update a <package>.opam.template file with the x-ai-* extension fields. Dune merges .opam.template contents into the generated .opam file, so these fields survive dune build @install and opam file regeneration.

x-ai-disclosure: "ai-generated"
x-ai-model: "claude-opus-4"
x-ai-provider: "Anthropic"

If the .opam.template file does not yet exist, create it with just the disclosure fields. If it already exists, append the fields.

Use the dominant disclosure level as the package default. Individual modules override where they differ.

A future dune language version will support these as first-class fields in the (package) stanza, eliminating the need for .opam.template:

(package
 (name foo)
 (ai_disclosure
  (level ai-generated)
  (model "claude-opus-4")
  (provider "Anthropic")))

Common Patterns

Entire file generated by AI:

[@@@ai_disclosure "ai-generated"]
[@@@ai_model "claude-opus-4"]
[@@@ai_provider "Anthropic"]

let foo = ...
let bar = ...

Human file with one AI-generated function:

[@@@ai_disclosure "ai-assisted"]

let human_written x = ...

let ai_helper y =
  ...
[@@ai_disclosure "ai-generated"]

Agent-generated code without human review:

[@@@ai_disclosure "autonomous"]
[@@@ai_model "claude-opus-4"]
[@@@ai_provider "Anthropic"]

What NOT to Annotate

• Do not annotate files you did not create or modify.
• Do not change existing disclosure annotations unless the code itself changed.
• Do not annotate non-OCaml files with OCaml attributes (use opam x-fields for package metadata).