ag-ui-protocol / ag-ui-protocol/ag-ui

[Feature]: Add event sequence validation (`validate_sequence`) to Python SDK

Aperta
#1,322 3 commenti 1 reazione 0 assegnatari Vedi su GitHub
enhancement
Lingua principale
Python
Stelle
15.9k
Fork
1.4k
Merge medio
1g 17h
PR unite (30g)
163

Descrizione

### Pre-flight Checklist

- [x] I have searched existing issues and this hasn't been requested yet.

### Problem or Motivation

The Go SDK provides `ValidateSequence` (sdks/community/go/pkg/core/events/events.go) and the TypeScript SDK provides `verifyEvents` (sdks/typescript/packages/client/src/verify/verify.ts) for validating that AG-UI event streams conform to the protocol's state machine rules (run lifecycle, message/tool call/step open-close pairing, no duplicates, etc.).

The Python SDK (`ag-ui-protocol`) has no equivalent. There is only get Pydantic type validation on individual events, but no sequence-level validation.

### Proposed Solution

Add a `validate_sequence` function (or similar) to the Python SDK under `ag_ui.verify` (or `ag_ui.core`), mirroring the rules enforced by the Go and TypeScript implementations:

- **Run lifecycle**: No duplicate starts, no finishing/erroring unstarted runs, no restarting finished runs
- **Message lifecycle**: TEXT_MESSAGE_CONTENT/END require an active message started with TEXT_MESSAGE_START
- **Tool call lifecycle**: TOOL_CALL_ARGS/END require an active tool call started with TOOL_CALL_START
- **Step lifecycle**: No duplicate step names, can't finish unstarted steps
- **Reasoning lifecycle**: Same open-close pairing as messages

### Alternatives Considered

Manually implementing validation in each project that uses the Python SDK

### Additional Context

Reference implementations:
- Go: https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/go/pkg/core/events/events.go#L229 (ValidateSequence)
- TypeScript: https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/client/src/verify/verify.ts#L5 (verifyEvents)

Guida per i contributori

Apri la guida per i contributori

Valutazione

Questa issue non è ancora stata valutata.

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.