Optional AI Generation Feature Plan

##### This plan was created by @haseebmalik18!

# AI generation for code.json

## Fields the AI should fill

Free text:

- `longDescription`
- `description`
- `tags`

Picked from a fixed list of values:

- `softwareType`, `platforms`, `repositoryType`, `subsetInHealthcare`, `userType`, which are enums in the schema, so anything off-list gets rejected for us
- `categories`, where the schema takes any string and only points at the publiccode list in its description, so we'd check that one against the list ourselves

Something to consider: `localisation` and `userInput` have no blank state, so the AI would be overwriting `false` rather than filling a gap.

## The flow

When the action runs to update code.json, either triggered manually or on a schedule:

1. The action reads the repo and fills in the fields it can work out on its own.
2. If the AI settings are missing it stops here and opens the PR as normal.
3. It picks out the fields above that are still blank. With the regen flag on it takes all of them.
4. If nothing is blank, no request goes out.
5. It sends one request: the top level file tree, the README, the current code.json, the blank fields, and the valid values for each one. It asks for JSON back.
6. Every answer gets checked against the schema on its own. Bad ones are dropped and logged.
7. What passes goes into those blank fields and nowhere else.
8. The PR opens, and the body says which fields the AI wrote.

Two minute timeout, no retry. If the call fails we log it, open the PR anyway, and the next run tries again.

The action's other mode is the PR check. When code.json is edited in a pull request, that run only validates the file against the schema, so none of the above applies there, AI included.

## Config

```yaml
AI_MODEL: "claude-sonnet-5"
AI_API_KEY: ${{ secrets.AI_API_KEY }}
AI_REGENERATE: "false"
```

All optional, since the action works without any of them. For AI generation the model and key are both required, and missing either turns the step off. `AI_REGENERATE` defaults to `false`.

The user only names a model. We work the endpoint out from the name, so `gpt-` goes to OpenAI, `claude-` to Anthropic and `gemini-` to Google. Matching on the prefix means new model versions work without a code change, and anything outside those three is rejected with a message saying which are supported.

The request itself is OpenAI chat completions shaped, which all three of those accept.

## Guardrails

Anything that comes back is checked against the schema before it goes near code.json, and the list of fields the AI can write lives in our code rather than the prompt, so a bad response can't widen its own scope.

The schema only checks `longDescription` for length though, not for whether any of it is accurate. So the PR body lists every field the AI wrote and says plainly that they need a human read before merge.

Fields that already have a value are left alone unless the regen flag is on. If the call fails we log it and finish the run without it, so a broken endpoint can't take the action down with it.

Enabling this sends repo contents to whichever provider the model name resolves to. That should be documented in the README alongside the AI inputs and in the `action.yml` input descriptions, so it's visible while the workflow is being set up.

Start with the action's code.json update and pull-request validation modes, then read README and action.yml for the existing configuration and inputs. Trace how schema validation, logging, and PR creation currently work before planning the provider-specific request flow. Done means optional AI generation is isolated from validation, failures do not block PRs, and the README and action.yml document data sharing and inputs.

Written by the indexing model from the issue text.