---
name: ai-disclosure
description: Use when writing or modifying OCaml code to annotate AI involvement. Triggers on any code generation, editing, or autonomous agent output in .ml/.mli files. Also use when creating or updating .opam files for packages containing AI-involved code.
---

# 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)

```ocaml
[@@@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)

```ocaml
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`:

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

## Common Patterns

**Entire file generated by AI:**
```ocaml
[@@@ai_disclosure "ai-generated"]
[@@@ai_model "claude-opus-4"]
[@@@ai_provider "Anthropic"]

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

**Human file with one AI-generated function:**
```ocaml
[@@@ai_disclosure "ai-assisted"]

let human_written x = ...

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

**Agent-generated code without human review:**
```ocaml
[@@@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).