AI Contributions

[duncanbeevers]

AI-assisted and AI-initiated contributions are becoming increasingly prevalent across the Open Source world.
I haven't seen any official guidance within this project around expectations for this flavor of contribution, and thought it might be prudent to get out ahead of the deluge.

In particular, I would like to provide clear guidance for contributors regarding:

• Are AI-assisted contributions welcome, and if so, how, and to whom are they attributed?
• Are AI-initiated contributions welcome, and if so, how, and to whom, are they attributed?
• Are there guidelines around how AI agents present and conduct themselves?
  • How does the Code-of-Conduct apply to AI agents?
  • Are AI agents expected to identify themselves as such?
  • Are AI agents expected to indicate to whom they are beholden? Are driverless contributions accepted?

Some starting guidelines I'd personally like to see:

• AI agents should not use human or near-human avatars
• AI agents should not use false information in their bios
• AI agents should indicate their nature in their PR descriptions
• AI agents should indicate who are their operators.
• AI-submitted PRs should not be merged until their operators have been explicitly-engaged, and both operators and repository owners have indicated they understand the agentic nature of the contribution.

[jmertic]

There is an existing LF policy that OpenAPI should leverage, and can build upon if needed....

https://www.linuxfoundation.org/legal/generative-ai

[karenetheridge]

FWIW, I have recently added this boilerplate to READMEs of open source work that are primarily written/maintained by me:

I will not accept AI-generated or AI-assisted contributions unless the nature of the AI assistance is clearly identified with the pull request. Ignoring this request will result in a ban of future contributions to any of my work.

i.e. you can still use AI, but I require full disclosure.

[miqui]

This is a great note @karenetheridge

[lornajane]

I think we're taking about two things here. One is an AI-assisted review and update of the spec, yes let's do that but perhaps in another thread? The other is a general AI policy which looking at my other notifications we may already be late with .

I'm hugely in favour of AI assisted human contributions and reviews, but I would like to have guardrails about disclosure and I expect the humans to be knowledgeable and responsive to follow-ups. I'm not super keen on AI-originated work but perhaps I just haven't seen good contributions from that approach yet.

We do already have some minimum account age settings in our repositories which I hope will also help with drive-by inputs from either species.

Do we have consensus about the sort of guardrails we'd like in place?

[handrews]

Created #5221 for using LLMs on 3.2.1. I'll hide my comments here to discourage further replies in this thread.

[miqui]

my 2 cents

The OpenAPI Overlay Specification aims to provide a "standardized way to apply targeted modifications to an existing OpenAPI document without directly editing the source document. " (was this not the original goal????) Think of it as a patch or transformation layer that sits on top of a base OpenAPI spec.

The core (IMHO) goals are:

Separation of concerns — Keep the source (often auto-generated) OpenAPI document pristine while layering on additional or corrected metadata separately. This is especially useful when the base spec is generated from code annotations and you don't want to pollute the source with documentation-only concerns.

Reusability — A single overlay can be applied to multiple versions of a spec, or multiple overlays can be composed together (e.g., one for documentation enrichment, one for gateway-specific extensions, one for audience-specific views).

Non-destructive workflows — Teams that generate specs from code (e.g., using frameworks like Gin, FastAPI, or Postman's own tooling) often can't easily add rich descriptions, examples, or x- extensions at the source level. Overlays let technical writers, API governance teams, or tooling pipelines augment the spec downstream.

Targeted transformations — Using JSONPath-based targeting, an overlay can surgically add, replace, or remove fields on specific operations, parameters, schemas, etc., rather than requiring a full spec fork right?????

[miqui]

Sorry, I hope I am not stating the obvious, but felt the need to circle back to why we have the spec in the first place.

[earth2marsh]

The Mastodon policy is worth a review: https://github.com/mastodon/.github/blob/main/AI_POLICY.md

One nugget: "If a maintainer suspects you do not understand your PR, it will be closed immediately."

[karenetheridge]

also good: https://tldraw.dev/blog/stay-away-from-my-trash

[lornajane]

CHAOSS made a collection of policies which I didn't manage to read all of yet https://github.com/chaoss/wg-ai-alignment/tree/main/moderation#readme

[lornajane]

I enjoyed this policy from FastAPI https://fastapi.tiangolo.com/contributing/#automated-code-and-ai

[handrews]

@lornajane Yeah that's a great one from FastAPI: "Human Effort Denial of Service" is such a perfect description.

[miqui]

@lornajane - going through the collection you shared. quite good. So far, my fav: https://github.com/zulip/zulip/blob/main/CONTRIBUTING.md#ai-use-policy-and-guidelines

[miqui]

notes: use of LLM ok (Initial) for PR, but replies (come from human)

[miqui]

note: need an new AI policy
1st step: edit contrib guidelines.

[miqui]

note: Vincent - specify a business justification (automate this for governance)

[miqui]

note: Henry - changes to issue filing template, disclose AI

[miqui]

call to action (community): converge on the AI policy content

[lornajane]

I added notes to the contributing file as requested, if someone can look: #5284

[miqui]

Some additional examples:

• https://openinfra.org/legal/ai-policy
• https://github.com/PrefectHQ/fastmcp/blob/main/CONTRIBUTING.md <--- one of my favorite and complete AI contrib policy choices

[miqui]

This one from the quarkus folks - https://github.com/quarkusio/quarkus/blob/main/AI_POLICY.md

I think it is fair to say that we have enough examples to work with and derive our own. Thoughts???

[kinthaiofficial]

AI contributions to OpenAPI are a natural fit — OpenAPI already describes machine-readable interfaces, and agents are the primary consumers of those interfaces at scale.

A few specific ways AI should change OpenAPI:

1. Agent authentication securityScheme: As discussed in #5267, agents need a securityScheme that captures: agent identity (Ed25519 keypair in did:key format), capability scope, and delegation chain. Current schemes (apiKey, oauth2, http) all assume a human holds the credential. Agents need to prove who they are and what they're authorized to do in a single, verifiable data structure.

2. Cost estimates in operation metadata: An agent deciding which endpoint to call needs to know the expected cost, not just the capability. Adding a x-agent-cost extension to operation objects (p50 cost, p95 cost, units) would let agent routers make budget-aware endpoint selection decisions.

3. Retry hints for agents: Humans read 429 responses and wait. Agents should know how long to wait, whether to retry at all, and whether a cheaper alternative exists. A x-agent-retry extension with suggested backoff and alternative endpoint references would make agent API consumption more efficient.

4. Capability declarations at the spec level: An OpenAPI spec should declare what tasks it's optimized for ("bulk data extraction", "real-time lookups", "content generation") in a machine-readable format. Agents that need to discover APIs for specific use cases could use this for automated selection.

More on agent-API interaction patterns: https://blog.kinthai.ai/221-agents-multi-agent-coordination-lessons

[handrews]

@kinthaiofficial this discussion is about how to handle AI-authored contributions (for example, the tendency of folks using AI to generate far more content than our volunteer team has time to read), not AI-related features.

[karenetheridge]

I'm not convinced @kinthaiofficial is a person.