diff --git a/.claude/skills/seclai-changelog/SKILL.md b/.claude/skills/seclai-changelog/SKILL.md index 3365c87..638d022 100644 --- a/.claude/skills/seclai-changelog/SKILL.md +++ b/.claude/skills/seclai-changelog/SKILL.md @@ -64,13 +64,13 @@ forward. ## Determine the version -Do not guess the next version. Releases are cut by `seclai/github-tag-action` in `.github/workflows/main-build.yaml`, which reads the **merge commit message**: +Do not guess the next version. Releases are cut by `seclai/github-tag-action` in `.github/workflows/main-build.yaml`, which scans the **commit messages** for a bump keyword. The PR title is not scanned: - contains `#major` → major bump - contains `#minor` → minor bump - otherwise → `DEFAULT_BUMP: patch` -So a change that adds endpoints must say `#minor` in a commit message, or the heading you write will not match the tag that gets cut. The keyword goes in the commit message, not the PR title. Confirm the intended bump with the user when it isn't stated, and flag the mismatch risk if no commit message carries the keyword. +Put `#minor` / `#major` in a branch commit message; never tell the user that the PR title will do. The keyword reaches `main` in the squash commit's message, so keep it when editing the message in the merge dialog. A change that adds endpoints needs `#minor` in a commit message, or it ships as a patch and the heading you write will not match the tag that gets cut. Confirm the intended bump with the user when it isn't stated, and flag the mismatch risk if no branch commit message carries the keyword. Check `git tag --sort=-v:refname | head -1` for the current latest, then apply the bump. diff --git a/.claude/skills/seclai-sdk-review-triage/SKILL.md b/.claude/skills/seclai-sdk-review-triage/SKILL.md new file mode 100644 index 0000000..9ea8150 --- /dev/null +++ b/.claude/skills/seclai-sdk-review-triage/SKILL.md @@ -0,0 +1,181 @@ +--- +name: seclai-sdk-review-triage +description: Triage PR review comments in a Seclai SDK repo (seclai-python, seclai-javascript, seclai-go, seclai-csharp, seclai-cli, seclai-mcp) or in sdk-tools, by evidence class, by how many SDKs share the site, and by whether it touches published surface, into fix here / fix in every SDK / ask / nothing / upstream / push back. Use when addressing review comments or unresolved PR threads, when a /code-review result is pasted in, before replying to or resolving threads, before reporting a review round, and when review rounds keep finding new problems. +--- + +# Triaging SDK review comments + +> **Vendored file — do not edit in place.** The canonical copy lives in the +> `seclai/sdk-tools` repository at `skills/seclai-sdk-review-triage/`, and is +> mirrored into each SDK repo with `git subtree`. Edits made here are reported as +> drift by `sdk-tools/sync.sh --check` and are overwritten on the next pull. + +Adapted from the `seclai` repo's `pr-review-triage` for SDK work, where the stakes +are published surface and wire behaviour, and one finding usually exists in four +SDKs at once. + +**Fetch the PR's own threads first.** A pasted `/code-review` result is a second +input, not a substitute: + +``` +gh api graphql -f query='{ repository(owner:"seclai",name:"") { + pullRequest(number:) { reviewThreads(first:100) { nodes { + id isResolved comments(first:1){ nodes { path line databaseId body } } } } } }' +``` + +**State what the PR is for before reading a finding**, a sentence each: its goal +(sync to which spec, plus any backlog the user agreed to), the design it chose, and +what it ruled out. Weigh every finding against that. A finding that re-opens a +decision already made in this PR or an earlier round is answered by citing the +decision, not by changing the code back. + +**A spec-sync PR changes only what the spec diff changed**, plus backlog the user +agreed to before the review. A Proven finding about behaviour that is already in the +last release goes to an issue, however cheap the fix looks, and the thread links it; +other classes keep their §1 disposition. A Contract finding on prose this PR wrote is +still fixed here. + +**Read `rules.md` next to this file** (each SDK `CLAUDE.md` imports it). Its +cold-review gate runs on your response diff before you reply (§7). + +## 1. Classify each finding + +| Class | Test | Disposition | +|---|---|---| +| **Proven** | You can write a failing test today from input that occurs | Fix (§3) | +| **Contract** | A published statement is false: README, CHANGELOG, docstring, SKILL.md, a comment | Make it true once, by the smallest change; deleting the claim counts | +| **Latent** | Provably wrong when reached; you can name the absent condition | **Nothing**, unless it would ship a break or a wrong request to consumers (§4) | +| **Speculative** | Hypothesised from code shape | Nothing | +| **Opinion** | Naming, reuse, dedupe, where a rule lives, a narrower type | Internals: **nothing**. New public surface: **ask** (§2) | +| **Consequence** | A true statement about an effect elsewhere | Record it in the reply | + +The class is yours to assign; a label arriving with the finding is an input. + +**Check that the finding is right before acting.** Name the command whose output +would prove your answer wrong, and run it: build the consumer, run the audit, read +the backend handler. Confident it is wrong: push back and change nothing. Unsure: +say which part you doubt, then act. Right diagnosis with a wrong suggested fix: take +the diagnosis, replace the repair, say both. + +## 2. What it touches decides the process + +| It touches | Then | +|---|---| +| **Published surface**: a public name or signature, what goes on the wire (query keys, null vs omitted, body shape), what a response deserializes into, version constants, a CHANGELOG heading or **Breaking:** label | **Decide, don't patch.** Check `surface` against the last tag; ask the user when the fix trades one consumer outcome for another | +| **Internal code** in this PR | Fix if proven or contract; otherwise nothing | +| **Trivial**: an internal comment, a test name, helper dedupe, a log line | One pass (delete, or the smallest true change) or nothing. Never a second pass | + +**Unreleased public surface can still change freely; released surface cannot.** +An opinion on a public name added in this PR is a decision to make now, with the +user, because a rename after release is breaking. The same opinion on a released +name is a major-version question. + +**A finding on generated code** (`seclai/_generated/`, `src/openapi.ts`, +`generated/seclai.gen.go`) is fixed in the generator's flags or upstream in the +spec, never in the output. + +**A spec defect goes upstream.** An undocumented null, a response schema that inlines +a string instead of `$ref`-ing the enum, untyped list items: reply on the thread, +and suggest the spec fix in `seclai`. Don't work around it in four SDKs unless the +user asks. + +## 3. One SDK, or all of them? + +**Count the sites across the sibling SDKs before fixing.** Most findings are about a +behaviour the four SDKs share: an optional `agent_id`, how `days` and the dates +combine, how a null clears a field. Fixing it in one SDK leaves three wrong and +invites the next round to find them. Check the siblings, fix them all the same way +in this round, or say the count in the reply ("one of four SDKs"). + +Two or more sites, or a fix that needed another fix where both changed behaviour, +means a design question first: give the options and a recommendation, and let the +user choose before any code. + +## 4. Latent findings and the audit tool + +A latent finding gets **nothing** unless learning it the breaking way would ship a +break or a wrong request to consumers, and nothing else would catch it first. Say +the assessment on the thread, so the reviewer knows it was weighed, not missed. + +For `sdksync.py` in sdk-tools, sdk-tools' CLAUDE.md governs. In short: `surface` and +`returns` report what they cannot read as UNREADABLE, so a parsing limit there is a +false alarm, never a silent miss. A latent parsing finding is not reportable unless +it gets past that guard. The stop condition is **no finding that changes an audit +result on a real SDK file**. Check it by running the audits on all four checkouts +before and after. + +## 5. Measure the round before fixing it + +Signals that the rounds are churning instead of converging: + +- the finding count stays flat or rises across three rounds; +- a fix needed another fix, and both changed behaviour; +- the response diff approaches the size of the change under review; +- more than half the findings land on the previous round's fixes (on a full-diff + review; a delta review lands there by construction). + +**Two firing, or the fix-needs-a-fix one alone: stop fixing finding by finding.** +Name the signal, name the requirement or design that is unclear, propose the way +out (often: make the failure mode loud, so latent cases become visible false +alarms; or split the adjacent work), and let the user decide. + +**The default way out is to freeze the mechanism.** When a fix to a mechanism (a +helper's timeout, fallback, retry or error rules) needs a fix, and both changed +behaviour, propose that this PR stop changing it: later findings on it go to one +issue listing every affected repo, and a fix that created a regression is reverted +rather than fixed forward. + +After the first round, review only the delta since the last reviewed commit, not +`HEAD~1..HEAD` counted by hand. + +## 6. Your own fixes + +**Delete, or add a guard. Do not add a named concept** (a new function, type, +option, or config key) to the code under review to answer a finding. Each new name is +surface for the next round. If a fix seems to need one, stop and say so. + +**Do not widen scope to make a test easy.** Supporting a shape no SDK has, because a +test needed it, is new work with its own review rounds. + +**A fix that adds or changes a mechanism is a new change, not a repair**: a new +option, timeout, fallback, retry, client or error type. Do not write it in answer to +a finding. Write down what it must do for each case (each way a stream or poll ends, +and its outcome, per SDK), agree it with the user, then implement it in every SDK +at once, in its own PR unless the user puts it in this one. Without that, each review round re-derives the design and finds the next +edge case. + +**A test added for a finding must fail without the fix.** Undo the fix, watch the +test fail, restore it. Say that you did. That proves the fix does what it says, not +that it is right; when the cold-review gate runs, its Break prompt checks the second. + +## 7. Replies and threads + +- One reply per thread, posted after lint, tests and the cold-review gate on the + response diff (`rules.md`) pass. The user commits and pushes, so say the change is in + the working tree. +- **Resolve only after the user reports the push** and + `gh pr view --json headRefOid` shows the new head, and only threads you changed. + A pushback, a doubt, or a question for the user stays open unless the user says to + resolve it. +- **Lead with the disagreement** when there is one. Dispute the claim, not the + reviewer. +- A review written against unpushed commits has no threads. Reply with one PR + comment once the commits are pushed. + +## 8. Reporting the round + +Lead with the class counts and how many findings changed behaviour. For example: +"9 findings: 2 proven, 4 latent, 1 contract, 2 opinion; 2 changed behaviour". When +none changed behaviour, say so in the first line: that is the stop condition. Then +list the pushbacks and doubts before the fixes. Report the classes you assigned, +not the ones the review claimed. Say what the cold-review gate found on the +response diff. End with: + +``` +Findings that change behaviour: N +Sibling SDKs checked: N of 4 — fixed in N +Pushed back / asked: N +Below the bar: N — said on the thread +Fixes verified by undoing them: N of N +Cold-review gate on the response diff: N findings, N changed behaviour | skipped (<10 lines) +``` diff --git a/.claude/skills/seclai-sdk-review-triage/rules.md b/.claude/skills/seclai-sdk-review-triage/rules.md new file mode 100644 index 0000000..05e84e6 --- /dev/null +++ b/.claude/skills/seclai-sdk-review-triage/rules.md @@ -0,0 +1,77 @@ +# Rules for changing and reviewing an SDK repo + +> **Vendored file — do not edit in place.** The canonical copy lives in +> `seclai/sdk-tools` at `skills/seclai-sdk-review-triage/rules.md`. Each SDK +> repo's `CLAUDE.md` imports its own vendored copy. + +Adapted from the `seclai` repo's `CLAUDE.md`. These rules apply to every task in an +SDK repo, whether you are writing the change or reviewing one. In sdk-tools they +arrive through the triage skill, and its own `CLAUDE.md` rules for audit findings +take precedence. The gates before this one are each repo's lint and test targets. + +## The cold-review gate: review your own diff before you report + +**Run it before you report a change as done, and before you draft replies to a +review round.** A reply is a published claim, and the next cold review finds what +this gate skips. Skip it for a diff under ~10 changed lines, and say so. Skip it when +you are a subagent: the agent that reports to the user runs it on the whole diff it +reports, including what subagents wrote. Do not report completion while a subagent +you started is still running. + +Delegate it, scoped to the diff being reported. Subagents get this file but not your +reasoning, and not inheriting your belief is the point. Run four prompts in parallel: + +- **Falsify** each claim your report, replies, CHANGELOG and docs are about to + make. Hand over the claim and the artifact that settles it: the code, the spec, + the last release tag. Never hand over your reasoning. +- **Break** each function you added or changed: "produce an input where these tests + pass and the code is wrong." Point the prompt at what has bitten SDK changes: + - a caller-supplied or replaced `HTTPClient`/transport; + - cancellation versus timeout; + - a cut or partial stream; + - an error from a 4xx (auth) versus a 5xx; + - the released behaviour at the last tag; + - the sync/async twin. +- **Read** the prose and test names you added: "which assert a fact, and is each + one true? Which prevent no wrong action a reader would otherwise take? Those are + deleted. For each that ranges over a set (every, each, never, a count), list the + set from the code and name a member it misses." +- **Trace** what the change does to code it does not touch: "list each caller of + every changed function, and each variant it runs under (overloads, the async + twin, the same helper in the sibling SDKs). Name one whose behaviour, comment, + test or doc sentence the change makes wrong." + +**Passing is reporting what came back, including nothing.** Triage its findings with +`seclai-sdk-review-triage`, the same as a reviewer's. A fix arising here runs the +gate again on that fix. + +**Never predict what the next review round will find.** Report what this gate +found on the diff: "the cold-review gate found no finding that changes behaviour", +or the list it did find. That is a claim about this diff, not about the next round. + +## Producing review findings + +For the agent writing findings, not the author triaging them. + +- **State the evidence each finding carries.** + - *Proven*: you can write a failing test today from input that occurs. + - *Contract*: a published statement is false (README, CHANGELOG, docstring, + comment). + - *Latent*: provably wrong when reached, and you can name the absent condition. + - *Speculative*: hypothesised from code shape. + - *Consequence*: a true statement about an effect elsewhere. +- **Say whether the behaviour is already in the last release.** Check the last tag. + A defect the PR did not introduce is reported as pre-existing; in a spec-sync PR + the author files it as an issue rather than fixing it there. +- **Do not report speculative hardening**, such as "a server could send X", "a + caller could reuse Y", unbounded inputs, races or timing margins. Report a latent + finding only when it would ship a break or a wrong request to consumers. +- **Every finding names a concrete failure**: the input or state, and the wrong + result. If it cannot be stated that way, it is an opinion; say so. +- **Contract means false, not incomplete.** A sentence that leaves something out is + an opinion, unless the omission makes what it says false. +- **Read the PR description and the earlier threads before reporting on code they + cover.** Do not report a finding that reverses a decision recorded there; quote + the decision and argue it, if you must. +- **Terminate on severity, not emptiness.** "No finding that changes behaviour or + the published surface" is decidable, and it is the stopping point. diff --git a/.claude/skills/seclai-sdk-sync/SKILL.md b/.claude/skills/seclai-sdk-sync/SKILL.md index 2f72dd5..ef619c2 100644 --- a/.claude/skills/seclai-sdk-sync/SKILL.md +++ b/.claude/skills/seclai-sdk-sync/SKILL.md @@ -97,8 +97,8 @@ schema, and splits the result by how much it costs you: - **SHAPE MISMATCH** (error) — the client commits to a list and the endpoint returns an object, or the reverse. This throws at deserialization; a shipped SDK is already broken. This is the 2026-07 envelope change. -- **NAME DIFFERS** (warning) — same shape, different type name. All four SDKs - drop the spec's `Model` and `Api` affixes by convention, so this tier is mostly +- **NAME DIFFERS** (warning) — same shape, different type name. The SDKs' own + type names often drop the spec's `Model` and `Api` affixes, so this tier is mostly noise by design. Keep it out of CI with `--quiet-renamed`. - **UNTYPED** (warning) — the spec names a schema and the client returns `JsonElement` / `json.RawMessage` / `unknown` / `JSONValue`. Not a defect, but @@ -153,39 +153,101 @@ diff called 21 JavaScript changes breaking when none were: - **REMOVED / BREAKING** (error) — a released signature no longer works: method gone, parameter list changed, or a return type changed in a static language. -- **WARN** — compatible but worth checking: a *trailing* optional parameter - (source compatible; flagged as binary breaking for C#), `unknown` narrowed to a - concrete type in TypeScript (safe), an optional member added to an inline - TypeScript options object such as `opts: { signal?: AbortSignal } = {}` (never - to an empty `{}`, which accepts any value the new type may reject; every - other member unchanged or only widened to accept `undefined`, the parameter's - name and its default unchanged; usually source - compatible, but a caller passing a non-literal object that already carries a - same-named property of another type — `const o = { signal: "abc" }` — no - longer compiles, since excess-property checks only cover literals), an - optional options-object member widened to accept `undefined` - (`x?: T` -> `x?: T | undefined`; source compatible), a TypeScript parameter - type wrapped in `Omit` (usually source compatible: an object literal - that sets an omitted key no longer compiles) or `Partial` (source - compatible), a TypeScript options parameter retyped to another **named** type - whose members, resolved from the declarations under `src/` at the tag and in - the working tree (interfaces, `extends`, aliases, `&`, `Omit`, `Pick`, - `Partial`), keep every old member with the same optionality and type and add - only optional ones — a member whose type names a local type counts as - unchanged only if that type's declaration is identical at both revisions, and - a type that does not resolve (generic, import, indexed access, union) stays - breaking — a required Python or TypeScript parameter made optional in place - (`id: str` -> `id: str | None = None`, `id: string` -> `id?: string`; same - name and position, positional stays positional, type unchanged or only widened - by `None`/`undefined`; not graded this way for C#), or a Python return - annotation (not enforced — but confirm the runtime value did not change too). +- **WARN** — compatible but worth checking. One line per kind: + - **Trailing optional parameter**: source compatible, but flagged as binary + breaking for C#. + - **`unknown` narrowed** to a concrete TypeScript return type, keeping its + wrapper: `unknown` to any type, `unknown[]` to `X[]` or `Array`, + `Promise` to `Promise`, `Promise` to + `Promise`. Changing the wrapper (`unknown[]` to `Promise`) breaks + callers that `.map` or `await`, so it stays BREAKING, as does an + `unknown` anywhere else (a callback parameter, a type-parameter + constraint, `Record`). + - **Options-object member added**: an optional member added to an inline + TypeScript options object such as `opts: { signal?: AbortSignal } = {}`, with + every other member, the parameter's name and its default unchanged. Usually + source compatible, but a caller passing a non-literal object that already + has a same-named property of another type (`const o = { signal: "abc" }`) no + longer compiles, since excess-property checks only cover literals. Never + graded this way for an empty `{}`, which accepts values the new type rejects. + - **Widened to `undefined`**: an optional options-object member `x?: T` -> + `x?: T | undefined`. Source compatible. A callback whose *return* type gained + `| undefined` is not this, and stays breaking. + - **`Omit`**: a TypeScript parameter type wrapped in it. Usually source + compatible; an object literal that sets an omitted key no longer compiles. + - **`Partial`**: a TypeScript parameter type wrapped in it. Source compatible. + - **Retyped to another named type**: a TypeScript options parameter whose new + type, resolved from the declarations under `src/` at the tag and in the + working tree (interfaces, `extends`, aliases, `&`, `Omit`, `Pick`, `Partial`), + keeps every old member with the same optionality and type and adds only + optional ones. A member whose type names a local type counts as unchanged + only if that declaration is identical at both revisions. A type that does + not resolve (generic, import, indexed access, union) stays breaking. + - **Required parameter made optional in place**: Python `id: str` -> + `id: str | None = None`, TypeScript `id: string` -> `id?: string`. Same name + and position, positional stays positional, type unchanged or only widened by + `None`/`undefined`. Not graded this way for C#. + - **Python return annotation changed**: not enforced, but confirm the runtime + value did not change too. + The parameter-level kinds combine: each old parameter must be unchanged or changed in one of these ways, and any added parameter must be optional and at the end. +A reformat is not a change: parameter lists are compared as their split, +whitespace-normalised members, so a trailing comma added when prettier or black +wraps a signature is invisible. Python's bare `*` is kept, since making a +parameter keyword-only does break callers. + +The return type is read up to the `{` that opens the body, at bracket depth 0, +so a lone Go `error`, a TypeScript constructor with no annotation, +`Promise<{ id: string }>`, a generic prettier wraps onto its own lines, and a +conditional type (`T extends U ? { a: 1 } : never`) are all read whole. An async +generator (`async *runStreamingAgent(`) is a method like any other, and a +generic method's type parameters (`paginate(`, wrapped or +holding a `() => void`) are recorded with its return type: changing one, or +its constraint, is BREAKING ("type parameters changed"). Until +2026-10-31 a regex read it instead, and 27 seclai-go methods returning a lone +value, plus the TypeScript constructor, were invisible: removing one reported +"no breaking change". + +A head the scan matches but cannot read — type parameters or a return type it +never closes, a parameter list that does not balance — is reported as +**UNREADABLE** and fails the run, at either revision, even when nothing changed. +Before, such a method was silently left out of the surface and its removal +reported "no breaking change"; every scanner bug found in the 2026-10 reviews +was that. Now an unfamiliar shape costs a look instead of a missed break: fix +the scanner and add a test, then rerun. A statement the pattern also matches +(`setup(x);` at class-member indent) is not a method and is not listed. + Only exported Go methods are surface. A lowercase method is unreachable outside the package, so a change to one breaks no caller. +**Go struct fields are surface too.** seclai-go's request/response types are +aliases (`type SetSlackTriggerConfigRequest = +generated.SetSlackTriggerConfigApiRequest`) of oapi-codegen structs, and +`generated` is a public package, so a field dropped by regeneration breaks +callers while every method signature is unchanged. `surface` diffs the exported +fields of exported structs in package `seclai` (read through the alias) and in +`generated/`, and the names of their other exported types, constants and +variables (an enum value the spec drops removes a generated constant): a removed +field, type, constant or variable is REMOVED; a changed field type, or a changed +declared type of a constant or variable, is BREAKING; an added one is ADDED. For +a non-struct type only the first line of its definition is compared (`string`, +an alias's target, `interface {`), so a change after the first line (a method of +a multi-line interface) is not seen. An alias to an exported struct in `seclai` +or `generated/` is compared by its fields, so re-pointing it at a struct with +the same fields is not seen either; if the old target is removed, its REMOVED +line still catches that. An alias to a struct in another package (`type File = +openapi_types.File`) is compared by its target's name only. Tags and comments +are ignored; in a nested struct only backtick tags are, the form oapi-codegen +writes. A struct it cannot read, or one embedding an unexported struct, is +UNREADABLE, as for a method head. Methods on generated types (union accessors +such as `AsValidationErrorLoc0`) are not read. It found one shipped break: +v1.8.0 renamed `generated.InsufficientCreditsDetail.Error` and +`generated.InsufficientCreditsResponse.Detail`. C# has the same blind spot for +model properties, and it is not covered. + An optional parameter inserted *mid-list* is graded breaking, not a warning: in C# a positional `M(id, token)` then tries to bind `token` to the new parameter. Use an overload rather than growing a parameter list. @@ -207,12 +269,22 @@ both revisions. Only seclai-csharp: everywhere else regeneration keeps models in step. Use `--since `, which limits the report to properties a schema **gained** since -that rev. Without it you get every long-standing coverage gap — 27 for -seclai-csharp, none of them actionable, which is how a gate gets muted. - -It cannot see models whose schema is declared inline rather than as a named -component; it prints how many are unchecked for that reason. Two of the six -models left stale in 2026-07 were in that blind spot, so treat the count as real. +that rev. Without it you get every long-standing coverage gap, which is how a +gate gets muted. + +A class is matched to its schema by name with the module prefix and the `Api` / +`Model` affixes dropped (`SlackTriggerConfigApiResponse` is +`SlackTriggerConfigResponse`), and by the +client's own methods: the class a method returns, or takes as its body, models +that operation's schema. That links `ContentFileUploadResponse` and picks which +`FileUploadResponse` a class is. Until 2026-11 an affixed class was never +matched, so `--since` did not report the Slack `alias` addition. A name that +still matches several schemas is listed as AMBIGUOUS and checked only for the +properties they all declare. + +It cannot see models with no named schema (an inline body, an SSE event, a +client-side options class); it names them as unchecked. Two of the six models +left stale in 2026-07 were in that blind spot, so read the list. ## `docexamples` — compile the README @@ -238,7 +310,7 @@ cover README snippets, and two shipped PRs contained examples that could not com | --- | --- | --- | --- | | seclai-python | generated + hand-written wrappers | yes | `make generate`, then black | | seclai-javascript | types generated, methods hand-written | yes | `npm run generate` | -| seclai-go | hand-written | yes | | +| seclai-go | types generated, methods hand-written | yes | `make generate`; `types.go` aliases the `generated/` structs | | seclai-csharp | hand-rolled from the start | **no** | no codegen library was suitable; still at near-full parity — sync it like the others | | seclai-cli | wraps `@seclai/sdk` | no | coverage question is command-to-SDK-method | | seclai-mcp | no client source | no | | @@ -271,7 +343,11 @@ For repos without a bundled spec, point at one: generator formats with ruff but the repo commits black, so raw output shows ~240 changed files that collapse to ~60 real ones. - javascript: `npm run generate` (no churn; types only). - - go / csharp: nothing to regenerate. + - go: `make generate` (`go generate ./...`, directives in `generated/gen.go`): + `cmd/specfix` converts the 3.1 spec to 3.0, then oapi-codegen v2.4.1 writes + `generated/seclai.gen.go`. To keep a field the spec removed, compiling and + marked deprecated, add it to `retainedRequestFields` in `cmd/specfix`. + - csharp: nothing to regenerate; hand-written models are what `models` checks. 4. **`parity`** to list what is missing. Implement every path, not just the ones that look interesting — binary/stream endpoints with no JSON schema are the ones that get skipped. @@ -350,7 +426,6 @@ local conventions (`searchDocs` / `search_docs` / `SearchDocs`). ## Release -The version comes from the merge commit message, read by `seclai/github-tag-action` -with `DEFAULT_BUMP: patch`. A sync that adds endpoints needs `#minor` in a commit -message (not the PR title), or it ships as a patch and the changelog heading -will not match the tag. +A sync that adds endpoints needs a `#minor` bump; where the keyword goes and how +the squash commit carries it is in the `seclai-changelog` skill, "Determine the +version". diff --git a/.claude/skills/seclai-sdk-sync/sdksync.py b/.claude/skills/seclai-sdk-sync/sdksync.py index 428f6a7..02b6529 100755 --- a/.claude/skills/seclai-sdk-sync/sdksync.py +++ b/.claude/skills/seclai-sdk-sync/sdksync.py @@ -53,8 +53,12 @@ # `[^)]*` class: a callback type or a `(default: 2000)` doc # comment would end it early, the method would drop out of the # surface and be reported REMOVED. -# sig_tail_re — matched straight after the closing `)` (the return type). -# sig_groups — head groups, then "params", then tail groups. +# The return type after the closing `)` is read by `_read_return_tail`, not a +# regex: `Promise<{ id: string }>` and Go's single, untupled `error` both +# defeated one. +# sig_groups — head groups, then "params", then "ret" when it comes after. +# type_params — a `<...>` type-parameter list may sit between the name and +# `(`; it is read and recorded with the return type. # line_comment — the line-comment marker; `public_surface` strips these, and # `/* */` too when it is `//`, from the whole file. Default `//`. # Endpoint helpers, used by `params` and `returns` (see `request_blocks`): @@ -68,7 +72,6 @@ LANGS = { "python": { "sig_re": r"\n (?:async )?def ([a-z]\w*)\(", - "sig_tail_re": r"\s*->\s*([^:]+):", "line_comment": "#", "sig_groups": ("name", "params", "ret"), "detect": "seclai/seclai.py", @@ -79,7 +82,7 @@ # calls. `api_key`, a plain property, was credited with GET /sources. "boundary_re": r"^[ \t]*(?:async )?def |^class ", "verb_re": r'"(GET|POST|PUT|PATCH|DELETE)"', - "return_re": r"\s*->\s*([^:\n]+):", + "return_after_params": True, "dict_at": [r"params\s*=\s*(?:_strip_none\()?\s*"], "dict_key_re": r'"([a-zA-Z_][a-zA-Z0-9_]*)"\s*:', "helper_re": r"^[ \t]+(?:async )?def (_[a-z0-9][a-z0-9_]*)\(", @@ -87,8 +90,14 @@ "skip": {"request", "request_raw", "stream", "paginate"}, }, "javascript": { - "sig_re": r"\n (?:async )?(\w+)\(", - "sig_tail_re": r"\s*:\s*([^{\n]+?)\s*\{", + # `async *name(` (an async generator, e.g. `runStreamingAgent`) and + # `name(` too: either one missing from the pattern left the method out + # of the surface, so removing it went unreported. The match stops before + # the `<` or `(`; `public_surface` reads a type-parameter list with + # `balanced_slice`, so parens and prettier's line wrapping inside it are + # fine, and records it with the return type (see `_split_type_params`). + "sig_re": r"\n (?:async )?\*?(\w+)(?=[<(])", + "type_params": True, "sig_groups": ("name", "params", "ret"), "detect": "src/client.ts", "sources": ["src/client.ts"], @@ -102,7 +111,7 @@ r"(?!(?:if|for|while|switch|catch|do|else|try|return|new|typeof|await)\b)" r"([a-zA-Z_][a-zA-Z0-9_]*)\s*[(<]"), "verb_re": r'"(GET|POST|PUT|PATCH|DELETE)"', - "return_re": r"\s*:\s*([^{\n]+?)\s*\{", + "return_after_params": True, "dict_at": [r"query:\s*"], "dict_key_re": r'["\']?([a-zA-Z_][a-zA-Z0-9_]*)["\']?\s*:', # Read a query literal member by member rather than with dict_key_re: @@ -125,7 +134,6 @@ # so a change to one breaks no caller. `alertConfigsBody` and # `modelAlertsBody` were graded BREAKING for that reason alone. "sig_re": r"func \(c \*Client\) ([A-Z]\w*)\(", - "sig_tail_re": r" \(([^)]*)\)", "sig_groups": ("name", "params", "ret"), "detect": "client.go", "sources": ["*.go"], @@ -135,8 +143,8 @@ # between two client methods are read as part of the earlier one. "boundary_re": r"^(?:func|type|var|const)\b", "verb_re": r"http\.Method(Get|Post|Put|Patch|Delete)", - # Go returns `(*T, error)`; take the first element of the tuple. - "return_re": r"\s*\(?\s*([^,{\n]+?)\s*(?:,\s*error)?\s*\)?\s*\{", + # Go returns `(*T, error)`; `block_return` takes the tuple's first element. + "return_after_params": True, "key_re": r'q\["([a-zA-Z_][a-zA-Z0-9_]*)"\]\s*=', # Go builds a query either by subscript assignment (key_re) or as a map # literal. Reading only the former made Search and SearchDocs — whose @@ -178,6 +186,10 @@ }, } +# The scanner each language's source needs (see `strip_comments`). +for _name, _cfg in LANGS.items(): + _cfg["lexer"] = _name + NOT_APPLICABLE = { "seclai-cli": "wraps @seclai/sdk; coverage is SDK-method-to-command, not spec-path", "seclai-mcp": "ships no client source", @@ -272,16 +284,79 @@ def _quoted_end(text: str, i: int) -> int | None: return None +def _norm(x: str | None) -> str: + """Whitespace-normalised text: every run of whitespace becomes one space.""" + return " ".join((x or "").split()) + + +def _norm_ts(x: str | None) -> str: + """`_norm` for a piece of TypeScript signature, with prettier's wrapped angle + brackets joined first: `Record<\n string,\n unknown,\n>` becomes + `Record`, as it is written on one line. + + Plain `_norm` turned the wrapped closer's line break into a space on each + side of the `>`, which `_bracket` then read as a comparison, so a later scan + of the normalised text lost its depth. It assumes a `<` ending a line and a + `>` starting one are brackets. That is wrong for a comparison broken across + lines in a parameter default (`a <\n b`): the join then miscounts depth, which + can only produce a false BREAKING, never a missed one. No SDK file has it.""" + x = re.sub(r"<[ \t]*\n\s*", "<", x or "") + x = re.sub(r",?\s*\n[ \t]*>", ">", x) + return _norm(x) + + +def _bracket(s: str, j: int) -> int: + """+1 if `s[j]` opens a bracket, -1 if it closes one, 0 otherwise. + + The one place that decides whether `<` and `>` are brackets, shared by every + depth-counting scanner here. They are, as generics (`Map>`), except: + `=>` and `->` (an arrow), `<=` and `>=`, `<-` (Go's `<-chan`, `chan<-`), a + shift `<<`, and a `<` or `>` with a space on both sides (`a > b` in a default + value). Counting those drove the depth negative or left it open, so the + commas after them stopped splitting and arity came out wrong. + + A `>` that starts its line is a closer even with a space on both sides: + prettier wraps a long generic as `Promise<\n A | B\n > {`, and reading + that `>` as a comparison left the return type open, so the method fell out + of the surface and removing it reported nothing. A comparison does not start + a line: prettier breaks a binary expression after its operator. + """ + c = s[j] + if c in "([{": + return 1 + if c in ")]}": + return -1 + if c not in "<>": + return 0 + prev = s[j - 1] if j else "" + nxt = s[j + 1] if j + 1 < len(s) else "" + if prev == " " and nxt == " " and not (c == ">" and _starts_line(s, j)): + return 0 + if c == "<": + return 0 if (nxt in "-=<" or prev == "<") else 1 + return 0 if (prev in "=-" or nxt == "=") else -1 + + +def _starts_line(s: str, j: int) -> bool: + """True when only spaces or tabs precede `s[j]` on its line.""" + k = j - 1 + while k >= 0 and s[k] in " \t": + k -= 1 + return k < 0 or s[k] == "\n" + + def balanced_slice(text: str, at: int, opener: str = "{", closer: str = "}") -> str | None: """Return the bracket-delimited literal starting at or after `at`. Regex cannot do this: query literals span lines and nest, and a non-greedy match silently truncates at the first inner `}`. Brackets inside a string - literal (`fmt?: "{id}"`, `sep = ")"`) are text, not structure. + literal (`fmt?: "{id}"`, `sep = ")"`) are text, not structure. For `<`/`>`, + which of them count is `_bracket`'s call: the `>` of `=>` does not. """ i = text.find(opener, at) if i == -1: return None + angle = opener == "<" depth, j = 0, i while j < len(text): ch = text[j] @@ -290,9 +365,9 @@ def balanced_slice(text: str, at: int, opener: str = "{", closer: str = "}") -> if end is not None: j = end continue - if ch == opener: + if ch == opener and (not angle or _bracket(text, j) == 1): depth += 1 - elif ch == closer: + elif ch == closer and (not angle or _bracket(text, j) == -1): depth -= 1 if depth == 0: return text[i + 1: j] @@ -300,22 +375,133 @@ def balanced_slice(text: str, at: int, opener: str = "{", closer: str = "}") -> return None -def strip_comments(text: str, line: str = "//") -> str: +def _triple_end(text: str, i: int) -> int | None: + """Index just past the Python triple-quoted string opening at `text[i]`.""" + q = text[i:i + 3] + j = i + 3 + while j < len(text): + if text[j] == "\\": + j += 2 + continue + if text.startswith(q, j): + return j + 3 + j += 1 + return None + + +def _template_end(text: str, i: int) -> int | None: + """Index just past the JavaScript template literal opening at `text[i]`. + It may span lines, and a `${...}` inside may hold strings and templates.""" + j, n = i + 1, len(text) + while j < n: + ch = text[j] + if ch == "\\": + j += 2 + continue + if ch == "`": + return j + 1 + if text.startswith("${", j): + depth, j = 1, j + 2 + while j < n and depth: + c = text[j] + if c == "`": + end = _template_end(text, j) + if end is None: + return None + j = end + continue + if c in "\"'": + end = _quoted_end(text, j) + j = end if end is not None else j + 1 + continue + depth += 1 if c == "{" else -1 if c == "}" else 0 + j += 1 + continue + j += 1 + return None + + +# After one of these characters or words a `/` starts a regex literal, not a division. +_REGEX_AFTER_CHARS = set("(,=:[!&|?{};+-*%<>~^") +_REGEX_AFTER_WORDS = {"return", "typeof", "case", "do", "else", "in", "of", "new", + "delete", "void", "throw", "yield", "await", "instanceof"} + + +def _regex_end(text: str, i: int, before: str) -> int | None: + """Index just past the JavaScript regex literal opening at `text[i]`, or None + when the `/` is a division. `before` is the code preceding it. + + Which one a `/` is depends on the grammar; this is the usual previous-token + heuristic. It is still a limit: a regex directly after `)` (`if (x) /re/.test(s)`) + or `]` is read as a division, and its body as code. A literal must close on + its own line, as the grammar requires. + """ + if text.startswith(("//", "/*"), i): + return None + tail = before.rstrip() + word = re.search(r"[A-Za-z_$][\w$]*$", tail) + if tail and tail[-1] not in _REGEX_AFTER_CHARS and not (word and word.group() in _REGEX_AFTER_WORDS): + return None + j, in_class = i + 1, False + while j < len(text): + c = text[j] + if c == "\\": + j += 2 + continue + if c == "\n": + return None + if in_class: + in_class = c != "]" + elif c == "[": + in_class = True + elif c == "/": + j += 1 + while j < len(text) and (text[j].isalnum() or text[j] in "_$"): + j += 1 + return j + j += 1 + return None + + +def strip_comments(text: str, line: str = "//", lexer: str | None = None, + drop_triple: bool = False) -> str: """`text` with `/* ... */` and `line`-to-end-of-line comments replaced by a space. String literals are left intact, so `"https://x"` is not a comment. Python passes `line="#"` and has no block comments; `/*` there would be an operator sequence, never a comment, so it is only honoured for `//`. + + `lexer` (a `LANGS` key) adds the literals that span lines or hold comment + markers, so a `/*` in one cannot swallow method heads up to the next `*/`: + Python triple-quoted strings (replaced by `""` with `drop_triple`, which is + how docstrings are kept out of request scanning), JavaScript template and + regex literals, Go raw strings. Without it, a literal must close on its own + line. C# verbatim strings are a known limit. """ out, j, n = [], 0, len(text) + recent = "" # the last code emitted, for the regex-literal heuristic while j < n: ch = text[j] - if ch in "\"'`": - end = _quoted_end(text, j) + end = None + if lexer == "python" and text.startswith(('"""', "'''"), j): + end = _triple_end(text, j) if end is not None: - out.append(text[j:end]) - j = end + out.append('""' if drop_triple else text[j:end]) + recent, j = '""', end continue + if ch == "`" and lexer == "javascript": + end = _template_end(text, j) + elif ch == "`" and lexer == "go": + close = text.find("`", j + 1) + end = None if close == -1 else close + 1 + elif ch in "\"'`": + end = _quoted_end(text, j) + elif ch == "/" and lexer == "javascript": + end = _regex_end(text, j, recent) + if end is not None: + out.append(text[j:end]) + recent, j = text[j:end], end + continue if line == "//" and text.startswith("/*", j): end = text.find("*/", j + 2) j = n if end == -1 else end + 2 @@ -327,6 +513,7 @@ def strip_comments(text: str, line: str = "//") -> str: out.append(" ") continue out.append(ch) + recent = (recent + ch)[-24:] j += 1 return "".join(out) @@ -336,12 +523,12 @@ def split_args(sig: str, seps: str = ",", keep_star: bool = False) -> list[str]: A naive `split(",")` turns `Dictionary q` into two entries, which over-counts arity for the query helpers and reports a phantom - signature change for `surface`. The `>` of a TypeScript arrow `=>` is not a - closing bracket: counting it would split `cb: (a: A, b: B) => void` after - the arrow. `seps` lets an object-literal type body split on `;` too. - Separators and brackets inside string literals are text. + signature change for `surface`. Which `<`/`>` are brackets is `_bracket`'s + call: the `>` of `cb: (a: A, b: B) => void`, Go's `<-chan` and the `>=` of a + default value are not. `seps` lets an object-literal type body split on `;` + too. Separators and brackets inside string literals are text. """ - out, depth, cur, prev = [], 0, [], "" + out, depth, cur = [], 0, [] j, n = 0, len(sig) while j < n: ch = sig[j] @@ -351,11 +538,7 @@ def split_args(sig: str, seps: str = ",", keep_star: bool = False) -> list[str]: cur.append(sig[j:end]) j = end continue - if ch in "<([{": - depth += 1 - elif ch in ")]}" or (ch == ">" and prev != "="): - depth -= 1 - prev = ch + depth += _bracket(sig, j) if ch in seps and depth == 0: out.append("".join(cur).strip()) cur = [] @@ -434,15 +617,22 @@ def block_call(body: str, verb_re: str) -> tuple[str, str] | None: return v.group(1).upper(), path -def strip_docs(text: str) -> str: - """Drop docstrings, block comments and whole-line comments. - - Helper detection reads through this: a docstring's `"GET"` and `"/sources"` - example made seclai-python's `_raise_for_openapi_response` look like the - request behind twenty methods that never issue one. +def code_only(text: str, cfg: dict) -> str: + """`text` without comments or Python docstrings, for request scanning. + + Every scan strips comments with `strip_comments` and the language's lexer: + `surface` and the TypeScript declaration readers (`ts_declarations`, + `_ts_object_members`, `_ts_typed_members`) and the JavaScript query-literal + reader `object_literal_keys` do too, so a multi-line template + literal holding `/*` is read the same way everywhere. A + docstring's `"GET"` and `"/sources"` example made seclai-python's + `_raise_for_openapi_response` look like the request behind twenty methods + that never issue one, and a trailing `// (default: 2000)` held a `)` that + ended a parameter list early. Triple-quoted strings are dropped (as `""`) + rather than kept, which is right for docstrings and harmless elsewhere: + no request path or query key is written in one. """ - text = re.sub(r'"""[\s\S]*?"""|\'\'\'[\s\S]*?\'\'\'|/\*[\s\S]*?\*/', "", text) - return re.sub(r"(?m)^[ \t]*(?://|#).*$", "", text) + return strip_comments(text, cfg.get("line_comment", "//"), cfg.get("lexer"), drop_triple=True) def endpoint_helpers(text: str, cfg: dict) -> dict[str, str]: @@ -454,16 +644,16 @@ def endpoint_helpers(text: str, cfg: dict) -> dict[str, str]: """ if "helper_re" not in cfg: return {} - ends = sorted({m.start() - for pat in (cfg["helper_re"], cfg["method_re"], cfg.get("boundary_re")) if pat - for m in re.finditer(pat, text, re.M)}) + # dict.fromkeys: the JavaScript boundary_re IS helper_re; scan it once. + patterns = dict.fromkeys(p for p in (cfg["helper_re"], cfg["method_re"], cfg.get("boundary_re")) if p) + ends = sorted({m.start() for pat in patterns for m in re.finditer(pat, text, re.M)}) out: dict[str, str] = {} for m in re.finditer(cfg["helper_re"], text, re.M): name = m.group(1) if name in cfg.get("skip", ()) or name in out: continue end = next((e for e in ends if e > m.start()), len(text)) - body = strip_docs(text[m.start():end]) + body = code_only(text[m.start():end], cfg) if block_call(body, cfg["verb_re"]): out[name] = body return out @@ -471,7 +661,7 @@ def endpoint_helpers(text: str, cfg: dict) -> dict[str, str]: def helper_called(body: str, cfg: dict, helpers: dict[str, str]) -> str | None: """Name of the first endpoint helper a method body calls, if any.""" - code = strip_docs(body) # a comment naming a helper is not a call to it + code = code_only(body, cfg) # a comment naming a helper is not a call to it first: tuple[int, str] | None = None for name in helpers: m = re.search(cfg["helper_call"].replace("{name}", re.escape(name)), code) @@ -487,7 +677,10 @@ def request_blocks(texts: list[str], cfg: dict): defining one is read through that helper — ONE hop. `body` stays the public method's, so its declared return type is what `returns` compares; `request_body` is where query keys are read. `helper` is None for own requests. + Every text is read without comments or docstrings (see `code_only`), so a + commented-out request is not a request and a `)` in a comment is not code. """ + texts = [code_only(t, cfg) for t in texts] shared: dict[str, str] = {} if cfg.get("helper_scope") == "package": for text in texts: @@ -523,7 +716,7 @@ def object_literal_keys(lit: str) -> tuple[set[str], bool]: """ keys: set[str] = set() ok = True - for member in split_args(strip_comments(lit)): + for member in split_args(strip_comments(lit, "//", "javascript")): # JS only (`dict_members`) m = re.match(r"""(?:"([^"]+)"|'([^']+)'|([A-Za-z_$][\w$]*))\s*:""", member) if m: keys.add(next(g for g in m.groups() if g)) @@ -571,8 +764,9 @@ def resolve(name: str, stack: tuple[str, ...]) -> tuple[set[str], bool]: def _calls(body: str, name: str) -> bool: - """A call to the free function `name(` — not `x.name(`, not `othername(`.""" - return re.search(rf"(? str: def block_return(body: str, cfg: dict) -> str | None: - """The declared return type of the method a block starts with. + """The declared return type of the method a block starts with; None when it + declares none or cannot be read (`read_block_return` tells them apart).""" + return read_block_return(body, cfg)[0] + + +def read_block_return(body: str, cfg: dict) -> tuple[str | None, bool]: + """(declared return type, unreadable) of the method a block starts with. + The block is known to be a method that makes a request, so anything short of + reading its return — or finding it has no annotation — is unreadable, and + `returns` must not count it as "nothing to check". Read by slicing the parameter list with paren matching rather than by regex: signatures wrap across lines and contain nested parens and generics, both of @@ -1075,22 +1278,23 @@ def block_return(body: str, cfg: dict) -> str | None: """ if "return_head_re" in cfg: m = re.match(cfg["return_head_re"], body, re.S) - return m.group(1).strip() if m else None + return (m.group(1).strip(), False) if m else (None, True) # Start at the paren the method anchor itself ends on. Taking the first `(` # in the block instead picks up Go's receiver — `func (c *Client) GetMe(` — # so the "return type" came back as the rest of the signature. anchor = re.match(cfg["method_re"], body, re.M) if not anchor: - return None - open_paren = body.find("(", anchor.end() - 1) - if open_paren == -1: - return None - params = balanced_slice(body, open_paren, "(", ")") - if params is None: - return None - rest = body[open_paren + len(params) + 2:] - m = re.match(cfg["return_re"], rest, re.S) - return m.group(1).strip() if m else None + return None, True + sliced = _after_params(body, body.find("(", anchor.end() - 1)) + if sliced is None: + return None, True + ret, _ = _read_return_tail(body, sliced[1], cfg["lexer"]) + if ret is None: + return None, True + if cfg["lexer"] == "go": + parts = split_args(ret) # `*T, error` -> `*T` + return (parts[0] if parts else ""), False + return (ret or None), False # no annotation declares nothing to check def cmd_returns(args) -> int: @@ -1102,7 +1306,7 @@ def cmd_returns(args) -> int: if not lang: die(f"cannot detect SDK language in {repo}") cfg = LANGS[lang] - if "return_re" not in cfg and "return_head_re" not in cfg: + if "return_after_params" not in cfg and "return_head_re" not in cfg: print(f"{repo.name} [{lang}] — return types are not declared; nothing to check.") return 0 files = source_files(repo, cfg) @@ -1124,12 +1328,15 @@ def cmd_returns(args) -> int: _schema_label(_json_schema(op, "response", code))) break - mismatched, renamed, untyped, n, via_helper = [], [], [], 0, 0 + mismatched, renamed, untyped, unreadable, n, via_helper = [], [], [], [], 0, 0 texts = [path.read_text(encoding="utf-8", errors="replace") for path in files] for mname, body, call, _request_body, helper in request_blocks(texts, cfg): if call not in want: continue - declared = block_return(body, cfg) + declared, unread = read_block_return(body, cfg) + if unread: + unreadable.append((mname, call)) + continue if declared is None: continue n += 1 @@ -1178,39 +1385,170 @@ def cmd_returns(args) -> int: for name, (verb, p), expect, declared in untyped: print(f" {name} ({verb} {p}): {declared}, spec declares {expect}") + if unreadable: + print(f"\nUNREADABLE ({len(unreadable)}) — request methods whose return type this " + "scan could not read; a shape mismatch there would go unreported:") + for name, (verb, p) in unreadable: + print(f" {name} ({verb} {p})") if mismatched: print(f"\n{len(mismatched)} return type(s) disagree with the spec in SHAPE.") return 1 + if unreadable: + print(f"\n{len(unreadable)} unreadable return type(s) — the result above is incomplete.") + return 1 print("\nno return type disagrees with the spec in shape") return 0 # ── surface ────────────────────────────────────────────────────────────────── +def _after_params(text: str, open_paren: int) -> tuple[str, int] | None: + """(parameter list, index just past its closing `)`) for the `(` at + `open_paren`, sliced by paren matching. Shared by `surface` and `returns`, so + the offset past the `)` is written once.""" + if open_paren < 0: + return None + params = balanced_slice(text, open_paren, "(", ")") + if params is None: + return None + return params, open_paren + len(params) + 2 + + +def _read_return_tail(text: str, i: int, lexer: str) -> tuple[str | None, bool]: + """(return type, unreadable). The type is None with unreadable False when + what follows is a statement, not a method; with unreadable True when the + scan never reached the body — the case `surface` must not stay quiet about. + + A scan, not a regex. The type ends at the `{` that opens the body, at depth + 0 — so `Promise<{ id: string }>` (its `{` is inside `<>`), an object type + literal right after `:` or a `|`, and Go's `interface{}` are read whole. The + regexes this replaced stopped at the first `{` and recorded `Promise<`, so a + change inside that type was invisible, and Go's matched only a `(...)` tuple, + so every method returning a lone `error` was missing from the surface. + """ + if lexer == "csharp": + return "", False # read from the head; see sig_groups + if lexer == "python": + m = re.compile(r"\s*(?:->\s*([^:]+?))?\s*:").match(text, i) + # Every match of Python's pattern is a `def`, so a miss is a misread. + return (_norm(m.group(1)), False) if m else (None, True) + j, n = i, len(text) + if lexer == "javascript": + m = re.compile(r"\s*:").match(text, j) + if m is None: + m = re.compile(r"\s*\{").match(text, j) + return ("", False) if m else (None, False) # `foo(x);` is a call + j = m.end() + start, depth = j, 0 + while j < n: + c = text[j] + if c in "\"'`": + end = _quoted_end(text, j) + if end is not None: + j = end + continue + if c in ";=" and depth == 0 and not text.startswith("=>", j): + return None, False # a statement or a field initialiser, not a method + if c == "{" and depth == 0: + so_far = text[start:j].rstrip() + # A TypeScript `{` opens a type literal, not the body, wherever a type + # can start: after `|`, `&`, `=>`, `:`, `,`, and in a conditional type + # after `?` or `extends` (`T extends { a: 1 } ? { b: 2 } : never`). + literal = (lexer == "go" and re.search(r"\b(?:interface|struct)$", so_far)) or ( + lexer == "javascript" and ( + not so_far or so_far.endswith(("|", "&", "=>", ":", ",", "?")) + or re.search(r"\bextends$", so_far))) + if not literal: + ret = (_norm_ts if lexer == "javascript" else _norm)(text[start:j]) + # A Go result tuple is recorded without its parens, `*Run, error`. + if lexer == "go" and ret.startswith("(") and balanced_slice(ret, 0, "(", ")") == ret[1:-1]: + ret = _norm(ret[1:-1]) + return ret, False + body = balanced_slice(text, j) + if body is None: + return None, True + j += len(body) + 2 + continue + depth += _bracket(text, j) + j += 1 + return None, True # ran off the end: the body was never found + + def public_surface(text: str, cfg: dict) -> dict[str, set[tuple[str, str]]]: """method name -> {(return type, parameter list)}. A set, because C# and Go - both allow overloads/variants under one name.""" - out: dict[str, set[tuple[str, str]]] = {} - order = cfg["sig_groups"] + both allow overloads/variants under one name. + + The parameter list is stored as its split, normalised members joined by + ", ", so a reformat — prettier or black wrapping a signature and adding a + trailing comma — is not a change. Python's bare `*` is kept: making a + parameter keyword-only is one. + """ + return scan_surface(text, cfg)[0] - def norm(x: str | None) -> str: - return " ".join((x or "").split()) - tail_re = re.compile(cfg.get("sig_tail_re", ""), re.S) +def scan_surface(text: str, cfg: dict) -> tuple[dict[str, set[tuple[str, str]]], list[str]]: + """(`public_surface`, `unreadable_heads`) from one pass over `text`.""" + out: dict[str, set[tuple[str, str]]] = {} + unreadable: set[str] = set() # Comments are not signature, and stripped before slicing so a `)` or an # apostrophe in one cannot end the parameter list early. - text = strip_comments(text, cfg.get("line_comment", "//")) + text = strip_comments(text, cfg.get("line_comment", "//"), cfg["lexer"]) for m in re.finditer(cfg["sig_re"], text, re.S): - open_paren = m.end() - 1 - params = balanced_slice(text, open_paren, "(", ")") - if params is None: - continue - tail = tail_re.match(text, open_paren + len(params) + 2) - if tail is None: - continue - parts = dict(zip(order, m.groups() + (params,) + tail.groups())) - out.setdefault(norm(parts["name"]), set()).add((norm(parts["ret"]), norm(parts["params"]))) - return out + status, name, entry = _read_head(text, m, cfg) + if status == "ok": + out.setdefault(name, set()).add(entry) + elif status == "unreadable": + unreadable.add(name) + return out, sorted(unreadable) + + +def unreadable_heads(text: str, cfg: dict) -> list[str]: + """Names of public method heads `public_surface` matched but could not read. + + Such a method is missing from the surface at that revision, so its removal + or change would report nothing. `surface` lists these and fails, which turns + any shape the scanner does not understand into a visible error rather than a + silent miss. A statement the pattern also matches (`foo(x);`) is not listed. + """ + return scan_surface(text, cfg)[1] + + +def _read_head(text: str, m: re.Match, cfg: dict) -> tuple[str, str, tuple[str, str] | None]: + """("ok", name, (return type, parameters)), ("skip", name, None) for a match + that is not a method, or ("unreadable", name, None).""" + order = cfg["sig_groups"] + name = _norm(dict(zip(order, m.groups()))["name"]) + # Most patterns end on the `(`; JavaScript's stops before it, so a + # type-parameter list can come first. + at = m.end() - 1 if text[m.end() - 1] == "(" else m.end() + tparams = None + if cfg.get("type_params") and text.startswith("<", at): + tp = balanced_slice(text, at, "<", ">") + if tp is None: + return "unreadable", name, None + # Split and rejoined like the parameters, so prettier's trailing comma + # on a wrapped list is not a change. + tparams = ", ".join(_norm_ts(x) for x in split_args(tp)) + at += len(tp) + 2 + while at < len(text) and text[at] in " \t\n": + at += 1 + if not text.startswith("(", at): + return ("unreadable" if tparams is not None else "skip"), name, None + sliced = _after_params(text, at) + if sliced is None: + return "unreadable", name, None + params, after = sliced + ret, unreadable = _read_return_tail(text, after, cfg["lexer"]) + if ret is None: + return ("unreadable" if unreadable else "skip"), name, None + if tparams is not None: + ret = _join_type_params(tparams, ret) + parts = dict(zip(order, m.groups() + (params,))) + if "ret" not in parts: + parts["ret"] = ret + norm = _norm_ts if cfg["lexer"] == "javascript" else _norm + canon = ", ".join(norm(p) for p in split_args(params, keep_star=True)) + return "ok", _norm(parts["name"]), (_norm(parts["ret"]), canon) @@ -1218,6 +1556,15 @@ def norm(x: str | None) -> str: _params = split_args +# A TypeScript parameter's head, `name?: `, and an object member's name and `?`. +_TS_PARAM_HEAD_RE = re.compile(r"\s*([\w$]+\s*\??\s*:\s*)") +_TS_MEMBER_NAME = r"(?:readonly\s+)?([\w$]+|\"[^\"]*\"|'[^']*')\s*(\?)?\s*" +# A property member, `name?: type`, with the type captured. +_TS_MEMBER_RE = re.compile(_TS_MEMBER_NAME + r":\s*(.*)$", re.S) +# Any named member: a property, or a method `name(...)`. +_TS_NAMED_MEMBER_RE = re.compile(_TS_MEMBER_NAME + r"[:(]") + + def _ts_inline_object(param: str) -> tuple[str, str, str] | None: """(prefix, body, suffix) when a TypeScript parameter's type is an inline object literal: `opts: { a?: string } = {}` -> ("opts:", "a?: string", "= {}"). @@ -1225,44 +1572,68 @@ def _ts_inline_object(param: str) -> tuple[str, str, str] | None: The `{` must follow the annotation colon directly, so a default value such as `x = {}` or a generic `Partial<{...}>` never qualifies. None otherwise. """ - m = re.match(r"\s*[\w$]+\s*\??\s*:\s*\{", param) - if not m: + m = _TS_PARAM_HEAD_RE.match(param) + if not m or not param.startswith("{", m.end()): return None - start = m.end() - 1 + start = m.end() body = balanced_slice(param, start) if body is None: return None end = start + len(body) + 1 - return (" ".join(param[:start].split()), body, " ".join(param[end + 1:].split())) + return (_norm(param[:start]), body, _norm(param[end + 1:])) def _ts_object_members(body: str) -> dict[str, tuple[bool, str]] | None: """member name -> (optional, normalised text) for an object-literal type body, split on depth-0 `;` or `,`. None when any member cannot be named (index signatures, call signatures, spread-like text) or a name repeats — the caller - then refuses to call the change compatible. Comments are dropped first: + then refuses to call the change compatible. Comments are dropped here even + though `public_surface` already stripped them: `classify_change` is also + called directly with raw signature text, and the bodies are a few lines, so + the second pass costs nothing worth a precondition. Comments are dropped first: seclai-javascript documents each member with `/** ... */`, which would otherwise hide the member's name, and a `,` or `;` inside one would split it. """ - parts = split_args(strip_comments(body), ";,") + parts = split_args(strip_comments(body, "//", "javascript"), ";,") out: dict[str, tuple[bool, str]] = {} for raw in parts: - text = " ".join(raw.split()) + text = _norm(raw) if not text: continue - m = re.match(r"(?:readonly\s+)?([\w$]+|\"[^\"]*\"|'[^']*')\s*(\?)?\s*[:(]", text) + m = _TS_NAMED_MEMBER_RE.match(text) if not m or m.group(1) in out: return None out[m.group(1)] = (bool(m.group(2)), text) return out -_TS_MEMBER_RE = re.compile(r"(?:readonly\s+)?([\w$]+|\"[^\"]*\"|'[^']*')\s*(\?)?\s*:\s*(.*)$", re.S) + +def _arrow_at_top(t: str) -> bool: + """`t` is a function type: it has an `=>` at bracket depth 0.""" + depth, j = 0, 0 + while j < len(t): + if t[j] in "\"'`": + end = _quoted_end(t, j) + if end is not None: + j = end + continue + if depth == 0 and t.startswith("=>", j): + return True + depth += _bracket(t, j) + j += 1 + return False def _ts_union(t: str) -> list[str]: - """Top-level `|` members of a type, whitespace-normalised and sorted.""" - return sorted(" ".join(x.split()) for x in split_args(t, "|")) + """Top-level `|` members of a type, whitespace-normalised and sorted. + + A function type is one member: in `(e: E) => T | undefined` the `|` belongs + to the return type, so splitting it there called a callback whose return + type changed "optional property widened to accept undefined". + """ + if _arrow_at_top(t): + return [_norm(t)] + return sorted(_norm(x) for x in split_args(t, "|")) def _ts_widened_to_undefined(old: str, new: str) -> bool: @@ -1314,9 +1685,8 @@ def _ts_wrapped_type(o: str, n: str) -> str | None: optionality and the default textually unchanged. Every old argument still fits both. None otherwise — including `Pick<>` and an `Omit<>` of another type.""" - ho = re.match(r"\s*([\w$]+\s*\??\s*:\s*)", o) - hn = re.match(r"\s*([\w$]+\s*\??\s*:\s*)", n) - if not ho or not hn or " ".join(ho.group(1).split()) != " ".join(hn.group(1).split()): + ho, hn = _TS_PARAM_HEAD_RE.match(o), _TS_PARAM_HEAD_RE.match(n) + if not ho or not hn or _norm(ho.group(1)) != _norm(hn.group(1)): return None rest_o, rest_n = o[ho.end():], n[hn.end():] w = re.match(r"(Omit|Partial)\s*<", rest_n) @@ -1336,8 +1706,7 @@ def _ts_wrapped_type(o: str, n: str) -> str | None: return None elif len(args) != 1: return None - norm = lambda x: " ".join(x.split()) # noqa: E731 - return kind if norm(rest_o) == norm(args[0] + after) else None + return kind if _norm(rest_o) == _norm(args[0] + after) else None _TS_COMPATIBLE_LABELS = { @@ -1398,10 +1767,9 @@ def _top_level_index(s: str, ch: str) -> int: if end is not None: j, prev = end, "" continue - if c in "<([{": - depth += 1 - elif c in ")]}" or (c == ">" and prev != "="): - depth -= 1 + b = _bracket(s, j) + if b: + depth += b elif c == ch and depth == 0: nxt = s[j + 1] if j + 1 < len(s) else "" if ch != "=" or (nxt not in "=>" and prev not in "=!<>"): @@ -1414,8 +1782,8 @@ def _top_level_index(s: str, ch: str) -> int: def _union_members(t: str) -> set[str]: m = re.fullmatch(r"\s*Optional\[(.*)\]\s*", t, re.S) if m: - return {" ".join(x.split()) for x in split_args(m.group(1), "|")} | {"None"} - return {" ".join(x.split()) for x in split_args(t, "|")} + return {_norm(x) for x in split_args(m.group(1), "|")} | {"None"} + return {_norm(x) for x in split_args(t, "|")} def _py_param(p: str) -> tuple[str, str, str | None] | None: @@ -1425,17 +1793,17 @@ def _py_param(p: str) -> tuple[str, str, str | None] | None: m = re.fullmatch(r"\s*([A-Za-z_]\w*)\s*(?::\s*(.+?))?\s*", head, re.S) if not m: return None - return m.group(1), " ".join((m.group(2) or "").split()), default + return m.group(1), _norm(m.group(2)), default def _ts_param(p: str) -> tuple[str, bool, str, str | None] | None: """(name, optional `?`, type, default) of one TypeScript parameter, or None.""" eq = _top_level_index(p, "=") - head, default = (p, None) if eq < 0 else (p[:eq], " ".join(p[eq + 1:].split())) + head, default = (p, None) if eq < 0 else (p[:eq], _norm(p[eq + 1:])) m = re.fullmatch(r"\s*([A-Za-z_$][\w$]*)\s*(\?)?\s*(?::\s*(.+?))?\s*", head, re.S) if not m: return None - return m.group(1), bool(m.group(2)), " ".join((m.group(3) or "").split()), default + return m.group(1), bool(m.group(2)), _norm(m.group(3)), default def _gained_default(lang: str, o: str, n: str) -> bool: @@ -1543,23 +1911,21 @@ def _gained_default_change(lang: str, old_par: str, new_par: str, def _ts_expr_end(text: str, i: int) -> int: """End of a type-alias expression starting at `i`: the first `;` at depth 0, or a blank line / new top-level declaration when the `;` is omitted.""" - depth, j, prev = 0, i, "" + depth, j = 0, i while j < len(text): c = text[j] if c in "\"'`": end = _quoted_end(text, j) if end is not None: - j, prev = end, "" + j = end continue - if c in "<([{": - depth += 1 - elif c in ")]}" or (c == ">" and prev != "="): - depth -= 1 + b = _bracket(text, j) + if b: + depth += b elif depth == 0 and (c == ";" or (c == "\n" and re.match( r"\n\s*(?:\n|(?:export\s+)?(?:interface|type|const|function|class|import)\b)", text[j:]))): return j - prev = c j += 1 return len(text) @@ -1576,7 +1942,7 @@ def put(name: str, decl: tuple | None) -> None: out[name] = decl for raw in texts: - text = strip_comments(raw) + text = strip_comments(raw, "//", "javascript") for m in re.finditer(r"(?m)^[ \t]*(?:export\s+)?(?:declare\s+)?interface\s+([\w$]+)\s*(<)?", text): brace = text.find("{", m.end()) @@ -1589,7 +1955,7 @@ def put(name: str, decl: tuple | None) -> None: if ext and not bases: put(m.group(1), None) continue - whole = " ".join(text[m.start():brace + len(body) + 2].split()) + whole = _norm(text[m.start():brace + len(body) + 2]) put(m.group(1), ("interface", bases, body, whole)) for m in re.finditer(r"(?m)^[ \t]*(?:export\s+)?(?:declare\s+)?type\s+([\w$]+)\s*(<)?", text): if m.group(2): @@ -1600,8 +1966,8 @@ def put(name: str, decl: tuple | None) -> None: continue start = m.end() + eq.end() end = _ts_expr_end(text, start) - expr = " ".join(text[start:end].split()) - put(m.group(1), ("alias", expr, " ".join(text[m.start():end].split()))) + expr = _norm(text[start:end]) + put(m.group(1), ("alias", expr, _norm(text[m.start():end]))) return out @@ -1609,14 +1975,14 @@ def _ts_typed_members(body: str) -> dict[str, tuple[bool, str]] | None: """member -> (optional, type) for an object type body; None if any member is not a plain `name?: type` property (methods, index signatures, ...).""" out: dict[str, tuple[bool, str]] = {} - for raw in split_args(strip_comments(body), ";,"): - text = " ".join(raw.split()) + for raw in split_args(strip_comments(body, "//", "javascript"), ";,"): + text = _norm(raw) if not text: continue m = _TS_MEMBER_RE.match(text) if not m or m.group(1) in out: return None - out[m.group(1).strip("\"'")] = (bool(m.group(2)), " ".join(m.group(3).split())) + out[m.group(1).strip("\"'")] = (bool(m.group(2)), _norm(m.group(3))) return out @@ -1630,7 +1996,7 @@ def _ts_string_keys(k: str) -> set[str] | None: def ts_resolve(expr: str, decls: dict, seen: tuple[str, ...] = () ) -> dict[str, tuple[bool, str]] | None: """Members of a TypeScript object type expression, or None if unresolvable.""" - e = " ".join(expr.split()) + e = _norm(expr) while e.startswith("(") and balanced_slice(e, 0, "(", ")") == e[1:-1]: e = e[1:-1].strip() if not e: @@ -1727,6 +2093,82 @@ def ts_named_options_change(o: str, n: str, old_decls: dict, new_decls: dict) -> return kinds or {"same"} +def _join_type_params(tparams: str, ret: str) -> str: + """A generic method's recorded return: `: Promise`. + + Kept with the return type rather than the parameters so that the optional- + parameter rules, which compare parameters by position, are unaffected. No + TypeScript type starts with `<...>:` (a generic function type is `(`), so + `_split_type_params` can always take it apart again.""" + return f"<{tparams}>: {ret}".rstrip() + + +def _unwrap(t: str, wrapper: str) -> str | None: + """`X` when `t` is exactly `wrapper` (`Promise`, `Array`), else None.""" + if not t.startswith(wrapper + "<"): + return None + inner = balanced_slice(t, len(wrapper), "<", ">") + if inner is None or len(wrapper) + len(inner) + 2 != len(t): + return None + return inner.strip() + + +def _array_element(t: str) -> str | None: + """`X` when `t` is an array of `X`: `X[]` for a name or a parenthesised + type, or `Array`. A union like `A | B[]` is not an array, so the element + must be a single name (with type arguments) or wrapped in parens.""" + inner = _unwrap(t, "Array") + if inner is not None: + return inner + if not t.endswith("[]"): + return None + el = t[:-2].strip() + if el.startswith("(") and balanced_slice(el, 0, "(", ")") == el[1:-1]: + return el[1:-1].strip() + m = re.fullmatch(r"[\w$.]+", el) or re.fullmatch(r"[\w$.]+(<.*>)", el) + if m and (m.lastindex is None or _unwrap(el, el[:el.index("<")]) is not None): + return el + return None + + +def _narrowed_from_unknown(old: str, new: str) -> bool: + """True when `new` only replaces the `unknown` in `old` with a concrete type, + keeping everything around it — the one return change a caller cannot + notice except as better types. + + `unknown` is the value the caller reads only when it is the whole return, + its array, or either inside `Promise<>`. The wrapper must survive: callers of + `unknown[]` call `.map`, and callers of `Promise` `await` or + `.then`, so `unknown[]` -> `Promise` breaks them. An `unknown` + anywhere else (a callback parameter, a constraint, `Record`) + stays BREAKING. + """ + if "unknown" in new: + return False + def concrete(x: str | None) -> bool: + return bool(x) and "unknown" not in x + if old == "unknown": + return True + if old == "unknown[]": + return concrete(_array_element(new)) + if old == "Promise": + return concrete(_unwrap(new, "Promise")) + if old == "Promise": + inner = _unwrap(new, "Promise") + return inner is not None and concrete(_array_element(inner)) + return False + + +def _split_type_params(ret: str) -> tuple[str | None, str]: + """(type parameters, return type) of a recorded return; None when the method + is not generic.""" + if ret.startswith("<"): + inner = balanced_slice(ret, 0, "<", ">") + if inner is not None and ret.startswith(":", len(inner) + 2): + return inner, ret[len(inner) + 3:].strip() + return None, ret + + def classify_change(lang: str, old: tuple[str, str], new: tuple[str, str], ts_decls: tuple[dict, dict] | None = None) -> tuple[str, str]: """(severity, label) for one signature change. severity is 'break' or 'warn'. @@ -1740,6 +2182,13 @@ def classify_change(lang: str, old: tuple[str, str], new: tuple[str, str], """ old_ret, old_par = old new_ret, new_par = new + if lang == "javascript": + # A type parameter or its constraint changing cannot be proven safe from + # text: `` -> `` can reject every old call. + old_tp, old_ret = _split_type_params(old_ret) + new_tp, new_ret = _split_type_params(new_ret) + if old_tp != new_tp: + return "break", "type parameters changed" if old_par != new_par: op, np_ = split_args(old_par), split_args(new_par) if lang == "javascript" and old_ret == new_ret: @@ -1776,7 +2225,13 @@ def ts_param_change(o: str, n: str) -> set[str] | None: return "warn", "optional parameters added — source compatible" return "break", "parameter list changed" if old_ret != new_ret: - if lang == "javascript" and "unknown" in old_ret and "unknown" not in new_ret: + # Only where `unknown` is the value the caller reads: the whole return, + # its array, or either inside `Promise<>`. Anywhere else it may be a + # parameter of a callback (`(x: unknown) => void`) or a constraint + # (``), where narrowing rejects calls that worked, so + # it stays BREAKING; a covariant case like `() => unknown` is a false + # alarm this accepts. + if lang == "javascript" and _narrowed_from_unknown(old_ret, new_ret): return "warn", "return narrowed from unknown — safe for consumers" if lang == "python": return "warn", "return annotation changed — not enforced at runtime, but check the value did not change" @@ -1803,6 +2258,201 @@ def _texts_at(repo: Path, rev: str | None, sub: str, suffix: str) -> list[str]: return out +def _go_package_texts(repo: Path, rev: str | None, sub: str) -> list[str]: + """The non-test `.go` files directly in `sub` (one Go package), at `rev` or + in the working tree. Listed at the rev itself, so a file deleted since the + tag still contributes its types to the baseline.""" + if rev is None: + d = repo / sub + return [f.read_text(encoding="utf-8", errors="replace") + for f in sorted(d.glob("*.go")) if not f.name.endswith("_test.go")] + prefix = "" if sub in ("", ".") else sub.rstrip("/") + "/" + ls = subprocess.run(["git", "-C", str(repo), "ls-tree", "--name-only", rev, "--", prefix or "."], + capture_output=True, text=True) + out = [] + for name in ls.stdout.split(): + if name.endswith(".go") and not name.endswith("_test.go") and "/" not in name[len(prefix):]: + p = subprocess.run(["git", "-C", str(repo), "show", f"{rev}:{name}"], + capture_output=True, text=True) + if p.returncode == 0: + out.append(p.stdout) + return out + + +_GO_TYPE_RE = re.compile(r"^type[ \t]+([A-Za-z_]\w*)(?:\[[^\]\n]*\])?[ \t]+", re.M) +_GO_FIELD_RE = re.compile(r"^([A-Za-z_]\w*(?:\s*,\s*[A-Za-z_]\w*)*)\s+(\S.*)$", re.S) +_GO_EMBED_RE = re.compile(r"^\*?([A-Za-z_]\w*\.)?([A-Za-z_]\w*)(?:\[.*\])?$", re.S) + + +def _go_struct_members(body: str) -> list[str] | None: + """A struct body (or `const`/`var` block) split into its declarations at + depth 0: a nested `struct { ... }` or `map[K]V` stays one member. A line + break splits only where Go would end the statement (after an identifier, + literal, `)`, `]` or `}`), so `"a" +` continues onto the next line. None + when it does not balance.""" + out, cur, depth, j = [], [], 0, 0 + while j < len(body): + ch = body[j] + if ch in "\"'`": + end = (body.find("`", j + 1) + 1 or None) if ch == "`" else _quoted_end(body, j) + if end is None: + return None + cur.append(body[j:end]) + j = end + continue + if ch in "([{": + depth += 1 + elif ch in ")]}": + depth -= 1 + if depth < 0: + return None + if depth == 0 and ch in "\n;": + member = "".join(cur) + tail = member.rstrip() + if (ch == ";" or not tail or tail[-1].isalnum() or tail[-1] in "_\"'`)]}" + or tail.endswith(("++", "--")) or re.search(r"(? tuple[dict[str, dict[str, str] | str], list[str]]: + """(declarations, unreadable) for one Go package's source. + + A declaration maps an EXPORTED name to {exported field: type} for a struct, + to the alias target string (`generated.X`) for `type A = B`, to "type T" + for any other type (`type Scope string` -> "type string"), and to + "const T" / "var T" for a package constant or variable, T its declared type + if any. A struct tag is dropped, and a nested struct's backtick tags too: + retagging changes the wire, not what compiles. An embedded field is named by its type, + as Go names it. A struct whose body does not balance, holds a member read as + neither a field nor an embedding, or embeds an unexported struct (whose + promoted fields this scan cannot list) is unreadable. + """ + text = strip_comments(text, "//", "go") + decls: dict[str, dict[str, str] | str] = {} + # A grouped `type ( ... )` block is not read; say so rather than drop it. + unreadable: list[str] = ["type ( ... ) block" + for _ in re.finditer(r"^type[ \t]*\(", text, re.M)] + for m in re.finditer(r"^(const|var)\b[ \t]*(\()?", text, re.M): + kind = m.group(1) + if m.group(2): + body = balanced_slice(text, m.end() - 1, "(", ")") + members = _go_struct_members(body) if body is not None else None + if members is None: + unreadable.append(f"{kind} ( ... ) block") + continue + else: + members = [text[m.end():].split("\n", 1)[0]] + last = "" + for mem in members: + left, eq, _ = mem.partition("=") + head = re.match(r"\s*([\w\s,]*?\w)(?:\s+([^,\s].*?))?\s*$", left) + if head is None: # no name before the type or `=` + unreadable.append(f"{kind} ( ... ) block" if m.group(2) else f"{kind} {left.strip()}") + break + names, typ = head.groups() + if kind == "const" and not eq and not typ: + typ = last # Go repeats the previous spec's type and value + last = typ or "" + for n in re.split(r"\s*,\s*", names): + if n[0].isupper(): + decls[n] = _norm(f"{kind} {typ or ''}") + for m in _GO_TYPE_RE.finditer(text): + name, rest = m.group(1), text[m.end():] + if not name[0].isupper(): + continue + if rest.startswith("="): + decls[name] = _norm(rest[1:].split("\n", 1)[0]) + continue + if not re.match(r"struct\s*\{", rest): + # `type Scope string`, interfaces, func types: the first line of the + # underlying type, so `string` -> `int` is a change. + decls[name] = _norm("type " + rest.split("\n", 1)[0]) + continue + body = balanced_slice(text, m.end()) + members = _go_struct_members(body) if body is not None else None + if members is None: + unreadable.append(f"type {name} struct") + continue + fields: dict[str, str] = {} + ok = True + for mem in members: + mem = re.sub(r"\s*`[^`]*`\s*$|\s*\"(?:[^\"\\]|\\.)*\"\s*$", "", mem) + e = _GO_EMBED_RE.match(mem) + f = _GO_FIELD_RE.match(mem) + if e and not f: + if not e.group(1) and e.group(2)[0].islower(): + ok = False + break + fields[e.group(2)] = "embedded " + _norm(mem) + elif f: + for fname in re.split(r"\s*,\s*", f.group(1)): + fields[fname] = _norm(re.sub(r"\s*`[^`]*`", "", f.group(2))) + else: + ok = False + break + if not ok: + unreadable.append(f"type {name} struct") + continue + decls[name] = {k: v for k, v in fields.items() if k[0].isupper()} + return decls, unreadable + + +def _go_kind(entry: str) -> str: + """What a `go_field_surface` entry declares: "type", "const", "var" or "field". + A field's type text cannot start with these keywords; "struct" alone is a type.""" + word = entry.split(" ", 1)[0] + return "type" if entry == "struct" or word == "type" else word if word in ("const", "var") else "field" + + +def go_field_surface(seclai_texts: list[str], generated_texts: list[str] + ) -> tuple[dict[str, str], list[str]]: + """(surface, unreadable) for package seclai (as `X`) and `generated/` (as + `generated.X`): `Type` -> "struct" and `Type.Field` -> field type for every + exported struct, `Name` -> its `go_struct_fields` value for every other + exported declaration, and "type = target" for any other alias. An alias to + an exported struct in either package (`type Req = generated.ReqApi`) is + listed with the fields it resolves to, since that is what its callers set. + """ + pk: dict[str, dict] = {} + unreadable: list[str] = [] + for prefix, texts in (("", seclai_texts), ("generated.", generated_texts)): + decls = {} + for t in texts: + d, u = go_struct_fields(t) + decls.update(d) + unreadable += [f"{n} in package {prefix.rstrip('.') or 'seclai'}" for n in u] + pk[prefix] = decls + + def resolve(prefix: str, name: str, seen: tuple = ()) -> dict | None: + d = pk[prefix].get(name) + if isinstance(d, dict) or d is None or name in seen: + return d if isinstance(d, dict) else None + if d.startswith("generated."): + return resolve("generated.", d[len("generated."):], seen + (name,)) + if "." in d or not re.fullmatch(r"\w+", d): + return None # another package, or not a plain name: not ours to read + return resolve(prefix, d, seen + (name,)) + + out: dict[str, str] = {} + for prefix, decls in pk.items(): + for name, d in decls.items(): + fields = resolve(prefix, name) + if fields is None: + out[prefix + name] = d if _go_kind(d) != "field" else f"type = {d}" + continue + out[prefix + name] = "struct" + for f, t in fields.items(): + out[f"{prefix}{name}.{f}"] = t + return out, unreadable + + def cmd_surface(args) -> int: """Diff the public API surface against a released tag. @@ -1847,7 +2497,8 @@ def cmd_surface(args) -> int: old_text = "\n".join(old_parts) new_text = "\n".join(f.read_text(encoding="utf-8", errors="replace") for f in files) - old, new = public_surface(old_text, cfg), public_surface(new_text, cfg) + (old, old_unread), (new, new_unread) = scan_surface(old_text, cfg), scan_surface(new_text, cfg) + unreadable = [(args.rev, n) for n in old_unread] + [("now", n) for n in new_unread] ts_decls = None if lang == "javascript": ts_decls = (ts_declarations(_texts_at(repo, args.rev, "src", ".ts")), @@ -1856,8 +2507,34 @@ def cmd_surface(args) -> int: added = sorted(set(new) - set(old)) changed = [k for k in sorted(set(old) & set(new)) if old[k] - new[k]] - print(f"{repo.name} [{lang}] — {len(old)} public method(s) at {args.rev}, {len(new)} now") - + # Go: exported struct fields too. The request/response types are aliases of + # oapi-codegen structs in the public `generated` package, so removing or + # retyping a field breaks callers while every method signature is unchanged. + old_f, new_f = {}, {} + if lang == "go": + old_f, old_fu = go_field_surface(_go_package_texts(repo, args.rev, "."), + _go_package_texts(repo, args.rev, "generated")) + new_f, new_fu = go_field_surface(_go_package_texts(repo, None, "."), + _go_package_texts(repo, None, "generated")) + unreadable += [(args.rev, n) for n in old_fu] + [("now", n) for n in new_fu] + gone_types = {k for k in old_f if old_f[k] == "struct" and k not in new_f} + for k in sorted(set(old_f) - set(new_f)): + if k in gone_types or k.rsplit(".", 1)[0] not in gone_types: + removed.append(f"{k} ({_go_kind(old_f[k])})") + added += [f"{k} ({_go_kind(new_f[k])})" for k in sorted(set(new_f) - set(old_f)) + if _go_kind(new_f[k]) != "field" or k.rsplit(".", 1)[0] in old_f] + + fields_note = (f"; {sum(v == 'struct' for v in old_f.values())} exported struct type(s) " + f"at {args.rev}, {sum(v == 'struct' for v in new_f.values())} now") if lang == "go" else "" + print(f"{repo.name} [{lang}] — {len(old)} public method(s) at {args.rev}, {len(new)} now{fields_note}") + + if unreadable: + print(f"\nUNREADABLE ({len(unreadable)}) — public method heads, or Go declarations, " + "this scan could not read; they are missing from the surface, so a change " + "to them would go " + "unreported. Fix the scanner (and add a test) before trusting this result:") + for rev, n in unreadable: + print(f" {n} (at {rev})") if removed: print(f"\nREMOVED ({len(removed)}) — every caller breaks:") for k in removed: @@ -1870,14 +2547,19 @@ def cmd_surface(args) -> int: if len(gone) == 1 and len(now) == 1: sev, label = classify_change(lang, gone[0], now[0], ts_decls) (breaks if sev == "break" else warns).append((k, label, gone, now)) + for k in sorted(set(old_f) & set(new_f)): + if old_f[k] != new_f[k]: + what = ("field type changed" if _go_kind(old_f[k]) == _go_kind(new_f[k]) == "field" + else "declaration changed") + breaks.append((k, what, [(old_f[k], None)], [(new_f[k], None)])) def show(rows: list) -> None: for k, label, gone, now in rows: print(f" {k} — {label}") for ret, params in gone: - print(f" was: {ret} ({params[:100]})") + print(f" was: {ret}" + ("" if params is None else f" ({params[:100]})")) for ret, params in now: - print(f" now: {ret} ({params[:100]})") + print(f" now: {ret}" + ("" if params is None else f" ({params[:100]})")) if breaks: print(f"\nBREAKING ({len(breaks)}) — a released signature no longer works:") @@ -1893,6 +2575,9 @@ def show(rows: list) -> None: print(f"\n{len(removed) + len(breaks)} breaking change(s). Keep the old form and add " "alongside it, or bump the major.") return 1 + if unreadable: + print(f"\n{len(unreadable)} unreadable declaration(s) — the result above is incomplete.") + return 1 print("\nno breaking change — every released signature still works") return 0 @@ -1940,6 +2625,21 @@ def git_location(spec: Path, fallback: Path) -> tuple[Path, str]: die(f"{full} resolves outside its own work tree {root}; --since cannot read it") +def affix_free(name: str) -> str: + """A schema name with its module qualification and `Api`/`Model` affixes + dropped, as seclai-csharp names its hand-written models: + `routers__api__agents__UpdateAgentRequest` -> `UpdateAgentRequest`, + `SlackTriggerConfigApiResponse` -> `SlackTriggerConfigResponse`, + `CloudDriveResponseModel` -> `CloudDriveResponse`. Only a trailing `Model` + and an `Api` before the last word go, so `EmbeddingModelListResponse`, + `ApiVersionResponse` and `UpdateApiVersionRequest` keep theirs. `models` + matches classes by it. + """ + name = short_label(name) + name = re.sub(r"(?<=[a-z0-9])Model$", "", name) + return re.sub(r"(?<=[a-z0-9])Api(?=[A-Z][a-z0-9]*$)", "", name) + + def spec_schema_index(spec: dict) -> dict[str, list[tuple[str, set[str]]]]: """Short schema name -> [(full name, property names)]. @@ -1949,11 +2649,91 @@ def spec_schema_index(spec: dict) -> dict[str, list[tuple[str, set[str]]]]: """ index: dict[str, list[tuple[str, set[str]]]] = {} for full, sch in (spec.get("components", {}).get("schemas") or {}).items(): - short = full.rsplit("__", 1)[-1] - index.setdefault(short, []).append((full, set(sch.get("properties") or {}))) + index.setdefault(short_label(full), []).append((full, set(sch.get("properties") or {}))) return index +def _element(label: str) -> tuple[bool, str]: + m = re.match(r"^array<(.+)>$", label) + return (True, m.group(1)) if m else (False, label) + + +def operation_models(repo: Path, lang: str, spec: dict, classes: set[str]) -> dict[str, dict[str, set[str]]]: + """Model class -> {full schema name -> client methods} from the client itself. + + A method that returns class X for an operation whose response is schema S, + or takes X as a parameter where the operation's request body is S, says X + models S. That is the client's own declaration, so it settles which of two + same-named schemas (`routers__api__sources__FileUploadResponse` and + `routers__api__contents__FileUploadResponse`) a class is, and links a class + named nothing like its schema (`ContentFileUploadResponse`). A list on one + side and an object on the other links nothing: that is a `returns` finding. + """ + cfg = LANGS.get(lang) + if not cfg or "return_head_re" not in cfg: + return {} + ops = {} + for raw, item in spec.get("paths", {}).items(): + for verb, op in item.items(): + if verb in ("get", "post", "put", "patch", "delete"): + ops[(verb.upper(), normalise(raw))] = op + links: dict[str, dict[str, set[str]]] = {} + + def link(cls: str, label: str, mname: str) -> None: + if cls in classes and "<" not in label and label not in ("object", "none", "unknown"): + links.setdefault(cls, {}).setdefault(label, set()).add(mname) + + texts = [f.read_text(encoding="utf-8", errors="replace") for f in source_files(repo, cfg)] + for mname, body, call, _request_body, _helper in request_blocks(texts, cfg): + op = ops.get(call) + if op is None: + continue + declared, unread = read_block_return(body, cfg) + if declared and not unread: + got_arr, got = _element(normalise_type(declared, lang)) + for code in ("200", "201", "202"): + if code in op.get("responses", {}): + want_arr, want = _element(_schema_label(_json_schema(op, "response", code))) + if got_arr == want_arr: + link(got, want, mname) + break + req = _schema_label(_json_schema(op, "request")) + anchor = re.search(cfg["method_re"], body) + sliced = _after_params(body, body.find("(", anchor.end() - 1)) if anchor else None + if sliced and req not in ("none", "object"): + types = {a.split()[0] for a in split_args(sliced[0]) if a.split()} + for t in types & classes: + link(t, req, mname) + return links + + +def match_models(classes: set[str], spec: dict, + links: dict[str, dict[str, set[str]]]) -> dict[str, list[str]]: + """Model class -> the full schema names it may model ([] when none). + + By name first: the exact short name, else the `affix_free` spelling, + ignoring case (`HttpValidationError` is `HTTPValidationError`). A + class the client links to operations (`operation_models`) is narrowed to + the named candidates it is used for; when it is used for none of them, its + links replace them. More than one result is ambiguous and is reported so; + picking one would check a model against a schema it may not be. + """ + fulls = list((spec.get("components", {}).get("schemas") or {})) + exact: dict[str, list[str]] = {} + loose: dict[str, list[str]] = {} + for full in fulls: + exact.setdefault(short_label(full), []).append(full) + loose.setdefault(affix_free(full).lower(), []).append(full) + out = {} + for cls in classes: + named = exact.get(cls) or loose.get(affix_free(cls).lower()) or [] + used = set(links.get(cls, {})) + if used: + named = sorted(used & set(named)) or sorted(used) + out[cls] = named + return out + + def cmd_models(args) -> int: repo = Path(args.repo).resolve() if repo.name in NOT_APPLICABLE: @@ -1970,7 +2750,8 @@ def cmd_models(args) -> int: return 0 spec = load_spec(args.rev, args.spec, repo) - index = spec_schema_index(spec) + props = {full: set(sch.get("properties") or {}) + for full, sch in (spec.get("components", {}).get("schemas") or {}).items()} # `--since` narrows the report to properties the schema GAINED since a rev. # Without it the C# models show 27 findings, every one a coverage gap that @@ -1980,63 +2761,77 @@ def cmd_models(args) -> int: gained: dict[str, set[str]] | None = None if args.since: spec_repo, rel = git_location(Path(args.spec), repo) - before = spec_schema_index(load_spec(args.since, rel, spec_repo)) + old = load_spec(args.since, rel, spec_repo) + was_full = {f: set(s.get("properties") or {}) + for f, s in (old.get("components", {}).get("schemas") or {}).items()} + was_short = spec_schema_index(old) gained = {} - for short, cands in index.items(): - now = set.union(*(p for _, p in cands)) - was = set.union(*(p for _, p in before[short])) if short in before else set() + for full, now in props.items(): + # A schema that only gained or lost its module qualification since + # the rev is the same schema: compare it with its old short name. + was = was_full.get(full) + if was is None: + was = set().union(*(p for _, p in was_short.get(short_label(full), []))) if now - was: - gained[short] = now - was + gained[full] = now - was files = sorted(repo.glob(cfg["glob"])) scope = f", {len(gained)} schema(s) changed since {args.since}" if gained is not None else "" - print(f"{repo.name} [{lang}] — {len(files)} model file(s), {len(index)} spec schema names{scope}") + print(f"{repo.name} [{lang}] — {len(files)} model file(s), {len(props)} spec schemas{scope}") - missing, extra, unmatched = [], [], [] + models: dict[str, set[str]] = {} for f in files: text = f.read_text(encoding="utf-8", errors="replace") m = re.search(cfg["class_re"], text) - if not m: - continue - cls = m.group(1) - have = set(re.findall(cfg["prop_re"], text)) - cands = index.get(cls) + if m: + models[m.group(1)] = set(re.findall(cfg["prop_re"], text)) + matches = match_models(set(models), spec, operation_models(repo, lang, spec, set(models))) + + missing, extra, unmatched, ambiguous = [], [], [], [] + for cls in sorted(models): + have, cands = models[cls], matches[cls] if not cands: unmatched.append(cls) continue + if len(cands) > 1: + ambiguous.append((cls, cands)) # With more than one candidate, only properties common to all of them are # unambiguously missing. A gate that guesses is a gate that gets muted. - want = set.intersection(*(p for _, p in cands)) + want = set.intersection(*(props[c] for c in cands)) if gained is not None: - want &= gained.get(cls, set()) + want &= set().union(*(gained.get(c, set()) for c in cands)) gone = want - have if gone: - missing.append((cls, sorted(gone), [n for n, _ in cands])) + missing.append((cls, sorted(gone), cands)) if len(cands) == 1 and gained is None: - surplus = have - cands[0][1] + surplus = have - props[cands[0]] if surplus: extra.append((cls, sorted(surplus))) if missing: print(f"\nMISSING PROPERTIES ({len(missing)}) — the spec declares these and the model does not:") - for cls, props, full in missing: + for cls, gone, full in missing: where = f" [{', '.join(full)}]" if full != [cls] else "" - print(f" {cls}{where}\n {', '.join(props)}") + print(f" {cls}{where}\n {', '.join(gone)}") if extra: print(f"\nWARN — EXTRA PROPERTIES ({len(extra)}) — in the model, not in the schema:") - for cls, props in extra: - print(f" {cls}: {', '.join(props)}") - if unmatched and not args.quiet_unmatched and gained is None: - print(f"\nWARN — NOT IN SPEC ({len(unmatched)}) — model classes with no matching schema:") - print(" " + ", ".join(sorted(unmatched))) + for cls, surplus in extra: + print(f" {cls}: {', '.join(surplus)}") + if ambiguous: + print(f"\nWARN — AMBIGUOUS ({len(ambiguous)}) — the class matches several schemas and " + "nothing narrows it to one; only properties all of them declare are checked:") + for cls, cands in ambiguous: + print(f" {cls}: {', '.join(cands)}") if unmatched: # Not a finding: the spec declares some request bodies inline rather than # as a named component, so CreateSourceRequest and UpdateSourceRequest — # both of which WERE left stale in 2026-07 — have nothing to match - # against. Say so, so the count is never read as full coverage. + # against. Say so, and name them, so the count is never read as full + # coverage. print(f"\n note: {len(unmatched)} model class(es) have no named schema " - f"and are unchecked (inline request bodies land here).") + f"and are unchecked (inline request bodies land here)" + + ("." if args.quiet_unmatched else ":\n " + ", ".join(unmatched))) if missing: print(f"\n{len(missing)} model(s) behind the spec.") @@ -2095,7 +2890,7 @@ def main() -> int: help="only report properties the schema gained since this spec rev " "(the sync gate; without it every long-standing gap is listed)") p.add_argument("--quiet-unmatched", action="store_true", - help="suppress the model-classes-with-no-schema report") + help="count the model classes with no schema without naming them") p.set_defaults(func=cmd_models) p = sub.add_parser("spec-diff", help="paths/schemas added, removed or changed between revisions") diff --git a/CHANGELOG.md b/CHANGELOG.md index 8e603dd..3068089 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,33 @@ # Changelog +## [1.10.0] - 2026-11-05 + +### Changed + +- Sync the bundled OpenAPI spec, adding 2 paths and 9 schemas. The typed models gain `result_reported_at` on an agent run and `alias` on the Slack trigger config and its update body +- Move `LATEST_API_VERSION` to `2026-11-04`. A client built with `api_version=LATEST_API_VERSION` also opts into `2026-11-02` and `2026-11-04`, which refuse requests that were accepted before: an agent-definition or sampling-rule write that references a metadata key no trigger declares is refused rather than declaring the key optional (400 from `update_agent_definition()`, 422 from `update_agent()` setting `sampling_config`); and each with a 400, `create_evaluation_result()` refuses `retry_triggered: true`, `update_agent()` refuses `evaluation_mode` `eval_and_retry`, and a new or changed evaluation criterion's `step_id` must name a `display_result` or `streaming_result` step +- Deprecate `input` in the `set_slack_trigger_config()` body. The API ignores the trigger's input template; a run's input is the text after `/seclai `, or the message the shortcut was used on. A body that still sets `input` is sent as before, and the generated `SetSlackTriggerConfigApiRequest` model keeps its `input_` attribute, documented as ignored +- Default `evaluation_mode` on the generated `AgentSummaryResponse` to `sample_and_flag`, as the API now declares, rather than `eval_and_retry`. A model built, or parsed from a payload, without `evaluation_mode` reports `sample_and_flag` +- Note API behavior that changed on every API version, whatever `Seclai-Version` a client sends: a run whose `metadata` has a custom key the trigger does not declare, or lacks a required one, is refused with a 400; an agent definition holding a `gate` or `retry` step is rejected (use `if_else`, or `repeat_until` to run steps again); the `agent_eval_fail` rollback trigger is accepted, never fires, and is no longer in the default rollback triggers (`governance_block` and `agent_run_failed` when none are set); and `max_retries` and `retry_on_failure` are accepted and have no effect +- Accept the generated `AcceptedAttachmentSlot` models, as well as dicts, in `set_accepted_attachments()`, so the slots a previous call returned can be edited and sent back +- Return the `result` snapshot from `run_streaming_agent_and_wait()` when the stream ends after the `event: result` the API now sends but before `done`, as the latest snapshot, rather than the `init` one + +### Added + +- Add `get_metadata_keys()` and `set_metadata_keys()` to read and replace the run metadata keys an agent trigger declares, returning `MetadataKeysResponse`. `set_metadata_keys()` takes dicts or the `MetadataKeyDeclaration` models `get_metadata_keys()` returns +- Add `get_knowledge_base_metadata_key_stats()` to count the item-metadata keys on a knowledge base's content per time window, returning `KnowledgeBaseMetadataKeyStats` +- Document `alias` in the `set_slack_trigger_config()` body, the name people type after `/seclai` to run the agent +- Add `ApiVersion` members for `2026-11-02` and `2026-11-04`, so each can be selected without `allow_unknown_api_version` +- Add `return_on_result` to `run_agent_and_poll()` and `run_streaming_agent_and_wait()`, to return as soon as a run reports its result (`result_reported_at` is set, or the `result` event arrives) instead of waiting for a terminal status or `done`. That run may still be in progress and can still fail +- Add `raise_on_incomplete` to `run_streaming_agent_and_wait()`. It raises `SeclaiStreamingError` when the stream ends, or is cut by a transport error such as `httpx.ReadError`, before the `done` event, instead of returning a run that has not finished or letting the `httpx` error through, with the latest snapshot in the error's `run`. It will become the default in the next major version +- Add `run` to `SeclaiStreamingError`, the latest run snapshot when `run_streaming_agent_and_wait()` times out, or with `raise_on_incomplete` gives up before `done`. The timeout error of `run_streaming_agent_and_wait()` is now this `SeclaiError` subclass; `run_streaming_agent()` still raises `SeclaiError` +- Export `Unset` and `UNSET` from `seclai`, to test for a response field the API omitted without importing a private module + +### Fixed + +- Return the run from a `done` event whose `event:` and `data:` lines `run_streaming_agent_and_wait()` had read when its `timeout` passed, even though the closing blank line had not arrived, rather than raising a timeout error +- Fetch the run with its step outputs in `run_agent_and_poll()` with `include_step_outputs=True` when the `run_agent()` response would already end the poll. A response that was already terminal was returned as is, without the step outputs asked for + ## [1.9.0] - 2026-10-31 ### Changed @@ -255,6 +283,7 @@ _Stable release. Packaging, CI, and documentation deployment only; no API change _Initial release._ +[1.10.0]: https://github.com/seclai/seclai-python/releases/tag/1.10.0 [1.9.0]: https://github.com/seclai/seclai-python/releases/tag/1.9.0 [1.8.0]: https://github.com/seclai/seclai-python/releases/tag/1.8.0 [1.7.2]: https://github.com/seclai/seclai-python/releases/tag/1.7.2 diff --git a/CLAUDE.md b/CLAUDE.md index b9a77e7..446e51a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,5 +1,13 @@ # seclai-python +## Changing and reviewing code + +The rules for writing a change (the cold-review gate on your own diff before you +report) and for producing review findings are shared by every SDK repo. They are +vendored from `sdk-tools` with the review-triage skill: + +@.claude/skills/seclai-sdk-review-triage/rules.md + ## Git and PRs - **Never commit or push.** No `git commit`, `git push`, `gh pr create`, no merging, not after finishing a task, not after addressing review comments, not after checks pass. The user commits all work themselves. Leave the changes in the working tree and say the work is ready. Do not offer to commit either. diff --git a/Makefile b/Makefile index 71f6fbd..10c72bb 100644 --- a/Makefile +++ b/Makefile @@ -60,7 +60,8 @@ test: generate: @echo "Generating OpenAPI client into seclai/_generated..." - poetry run openapi-python-client generate --meta none --path openapi/seclai.openapi.json --output-path seclai/_generated --overwrite + poetry run python scripts/specfix.py openapi/seclai.openapi.json build/generate/seclai.openapi.json + poetry run openapi-python-client generate --meta none --path build/generate/seclai.openapi.json --output-path seclai/_generated --overwrite docs: @echo "Generating SDK documentation into build/docs..." diff --git a/README.md b/README.md index 69ec5f6..a5ff53f 100644 --- a/README.md +++ b/README.md @@ -245,6 +245,8 @@ client decodes: | `2026-10-19` | `create_source()` refuses `polling_max_items` with a 400 on any source other than an RSS feed | | `2026-10-21` | An evaluation result whose evaluator returned no verdict (`error`) is left out of `failed` and of the pass and failure rates in `get_non_manual_evaluation_summary()`; `get_evaluation_criteria_summary()`'s `average_score` averages only passed and failed results; `test_draft_evaluation()` returns `score` and `passed` as `None` for an `error` result instead of 0.5 and `False` | | `2026-10-28` | An `if_else` or `switch` step's `output` is the result of the arm it took (its input when that arm is empty or it took none), rather than the `{"branch": ...}` marker with no `attachments`. The arm is in the step's `decision` on every version | +| `2026-11-02` | An agent-definition or sampling-rule write (other than an import) that references a metadata key no trigger declares is refused, rather than the key being declared optional: `update_agent_definition()` answers 400, and `update_agent()` setting `sampling_config` answers 422 | +| `2026-11-04` | `create_evaluation_result()` refuses `retry_triggered: true`, and `update_agent()` refuses `evaluation_mode` `eval_and_retry` (earlier versions store it as `sample_and_flag`), each with a 400; a new or changed evaluation criterion's `step_id` must name a `display_result` or `streaming_result` step | Moving to a later version can still change a value your code branches on, or reject a request that used to work. From `2026-10-05`, a content item held for @@ -258,7 +260,9 @@ as a bool, or does arithmetic on its `score`, gets `None` when `status` is `error`, and `get_non_manual_evaluation_summary()`'s `failed` no longer counts those results: read its `error` count. From `2026-10-28`, code that parses an `if_else` or `switch` step's `output` for the `{"branch": ...}` marker gets the -arm's result instead: read `decision`. Passing +arm's result instead: read `decision`. `2026-11-02` and `2026-11-04` turn +requests that were accepted before into 400s: declare metadata keys with +`set_metadata_keys()` before referencing them. Passing `api_version=LATEST_API_VERSION` opts into all of these at once. ## Resources @@ -364,18 +368,45 @@ client.cancel_agent_run("run_id") The SDK provides two streaming patterns over the SSE `/runs/stream` endpoint. -**Block until done** — returns the final `done` payload or raises on timeout: +**Block until done** — returns the run from the `done` event. Pass +`raise_on_incomplete=True` (recommended; it becomes the default in the next +major version) so a run that has not finished is never returned: ```python -from seclai import AgentRunStreamRequest +from seclai import AgentRunStreamRequest, SeclaiStreamingError -run = client.run_streaming_agent_and_wait( - "agent_id", - body=AgentRunStreamRequest(input="Hello from streaming", metadata={}), - timeout=60.0, -) +try: + run = client.run_streaming_agent_and_wait( + "agent_id", + body=AgentRunStreamRequest(input="Hello from streaming", metadata={}), + timeout=60.0, + raise_on_incomplete=True, + ) +except SeclaiStreamingError as e: + # Timed out, or the stream ended or was cut, before `done`. `e.run` is the + # latest snapshot: the `result` one if it arrived, so its `output` is the + # answer even though the run had not finished. + if e.run is not None and e.run.result_reported_at: + print(e.run.output) + else: + raise ``` +With `raise_on_incomplete=True`, on `timeout`, or when the stream ends or is +cut before `done`, it raises `SeclaiStreamingError` with the latest snapshot +in `e.run` (or `None` if none arrived). + +By default it behaves as in earlier releases: when the stream ends before +`done` it returns the latest snapshot, which may be a run that has not +finished, so check `status` and `result_reported_at`; a connection cut +mid-stream raises the `httpx` error (such as `httpx.ReadError`). On `timeout` +it raises `SeclaiStreamingError`, with `e.run`, either way. + +Pass `return_on_result=True` to return the `result` snapshot as soon as it +arrives, without waiting for `done`. That run may still be in progress: its +`status` may not be terminal and it can still fail. Check +`result_reported_at`, not `status`. + **Generator-based** — yields every SSE event as `(event_type, data)` tuples: ```python @@ -389,8 +420,8 @@ for event_type, data in client.run_streaming_agent( Set `include_reasoning=True` in the request to also receive `stream_reasoning` events with the model's reasoning, for a `streaming_result` step whose author enabled `show_reasoning`. `run_streaming_agent_and_wait()` keeps only the -`init` and `done` events, so it removes `include_reasoning` from the body -before sending. +`init`, `result` and `done` events, so it removes `include_reasoning` from the +body before sending. Every key of `AgentRunStreamRequest` is optional, so a run on an uploaded file can send just `AgentRunStreamRequest(input_upload_id=upload["upload_id"])`. @@ -419,6 +450,11 @@ result = client.run_agent_and_poll( ) ``` +It returns once the run's status is `completed` or `failed`. With +`return_on_result=True` it returns the first snapshot with +`result_reported_at` set; that run may still be in progress and can still +fail, so check `result_reported_at`, not `status`. + ### Agent input uploads ```python @@ -446,6 +482,39 @@ upload = client.upload_agent_input("agent_id", file=b"data", file_name="input.pd status = client.get_agent_input_upload_status("agent_id", upload["upload_id"]) ``` +### Trigger metadata keys + +Declare custom keys with `set_metadata_keys()` before sending them in a run's +`metadata`. + +```python +from seclai import Unset + +# The run metadata keys a trigger declares. Steps reference one as +# {{metadata.}}; a run you start is refused with a 400 when it lacks a +# required key or sends a custom key the trigger does not declare. +keys = client.get_metadata_keys("agent_id", "trigger_id") +print([k.key for k in keys.metadata_keys]) +print([k.key for k in keys.declarable_keys]) # system/source keys on offer + +# Replace the whole declaration. Only a custom key can be required. The API +# answers 400 if the agent references a key no trigger of its branch declares. +updated = client.set_metadata_keys( + "agent_id", + "trigger_id", + [ + {"key": "topic", "origin": "custom", "required": True}, + {"key": "trigger_type", "origin": "system"}, + ], +) +if not isinstance(updated.warnings, Unset): + print(updated.warnings) # agents whose call_agent mapping no longer fits + +# Or edit what get_metadata_keys() returned and send its models back. +keys.metadata_keys[0].required = False +client.set_metadata_keys("agent_id", "trigger_id", keys.metadata_keys) +``` + ### Agent run attachments ```python @@ -516,6 +585,12 @@ kb = client.create_knowledge_base({"name": "My KB"}) fetched = client.get_knowledge_base("kb_id") client.update_knowledge_base("kb_id", {"name": "Renamed"}) client.delete_knowledge_base("kb_id") + +# How often each item-metadata key appears on the KB's content, for choosing +# the keys a content trigger declares (set_metadata_keys) +stats = client.get_knowledge_base_metadata_key_stats("kb_id") +for window in stats.windows: # all_time, last_30_days, last_7_days + print(window.window, window.total_items, [k.key for k in window.keys]) ``` ### Memory banks @@ -790,6 +865,7 @@ config = client.set_slack_trigger_config( "trigger_id", { "mcp_client_id": "mcp_client_id", # the account's connected Slack MCP client + "alias": "support", # run as /seclai support; defaults from the agent name "scope": "selected_channels", "channel_ids": ["C0123456789"], "activation": "channel_opt_in", # or "everywhere" in scope @@ -802,6 +878,10 @@ config = client.set_slack_trigger_config( print(config["missing_scopes"]) # Slack scopes needed for optional features ``` +A run's input is the text after `/seclai `, or the message the shortcut +was used on; form values reach it as `{{metadata.}}`. The `input` field +(the trigger's input template) is deprecated: the API ignores it if sent. + ### Agent email governance ```python @@ -976,7 +1056,7 @@ except SeclaiConfigurationError as e: | `SeclaiConfigurationError` | Missing API key, invalid configuration | | `SeclaiAPIStatusError` | Non-2xx HTTP response | | `SeclaiAPIValidationError` | HTTP 422 (inherits `SeclaiAPIStatusError`) | -| `SeclaiStreamingError` | SSE stream error event received | +| `SeclaiStreamingError` | SSE stream error event received; `run_streaming_agent_and_wait()` timed out, or, with `raise_on_incomplete=True`, its stream ended or was cut before `done` (`e.run` holds the latest snapshot) | ## Low-level access diff --git a/openapi/seclai.openapi.json b/openapi/seclai.openapi.json index 4220dcc..bee860b 100644 --- a/openapi/seclai.openapi.json +++ b/openapi/seclai.openapi.json @@ -277,7 +277,7 @@ }, "definition": { "additionalProperties": true, - "description": "The agent definition containing name, description, tags, and step workflow tree. Step types include prompt_call, retrieval, regex_replace, gate, retry, evaluate_step, extract_data, extract_content, add_chat_turn, load_chat_history, add_memory, search_memory, load_memory, streaming_result, send_email, webhook_call, call_agent, write_metadata, write_content_attachment, load_content_attachment, load_content, display_result, merge, for_each, if_else, switch, and others.", + "description": "The agent definition containing name, description, tags, and step workflow tree. Step types include prompt_call, retrieval, regex_replace, evaluate_step, extract_data, extract_content, add_chat_turn, load_chat_history, add_memory, search_memory, load_memory, streaming_result, send_email, webhook_call, call_agent, write_metadata, write_content_attachment, load_content_attachment, load_content, display_result, merge, for_each, if_else, switch, and others.", "title": "Definition", "type": "object" }, @@ -492,7 +492,7 @@ "title": "Evaluation Criteria" }, "export_version": { - "description": "Schema version of the export format (currently \"5\").", + "description": "Schema version of the export format (currently \"6\").", "title": "Export Version", "type": "string" }, @@ -720,7 +720,7 @@ "type": "null" } ], - "description": "Metadata to make available for string substitution expressions in agent tasks.", + "description": "Metadata for string substitution in agent tasks. Each key must be one the agent's trigger declares (or sets); a run that sends another custom key, or lacks a required one, is refused with HTTP 400.", "title": "Metadata" }, "priority": { @@ -806,7 +806,7 @@ "type": "null" } ], - "description": "Result of the governance input evaluation: safe, blocked, skipped, or timed_out.", + "description": "Result of the governance input evaluation: pending, safe, blocked, skipped, timed_out, or error.", "title": "Governance Input Status" }, "governance_input_wait_ms": { @@ -830,7 +830,7 @@ "type": "null" } ], - "description": "Cumulative milliseconds the run was parked waiting for a human decision on a human_in_the_loop step. Subtracted from active duration in run-detail and duration-stats responses.", + "description": "Sum over the run's human_in_the_loop steps of each one's wait for a decision, in milliseconds. Waits that overlap are each counted in full, so the sum can exceed the run's duration.", "title": "Hitl Wait Ms" }, "input": { @@ -886,6 +886,19 @@ "title": "Priority", "type": "boolean" }, + "result_reported_at": { + "anyOf": [ + { + "format": "date-time", + "type": "string" + }, + { + "type": "null" + } + ], + "description": "When the run reported success: for an agent whose `report_success` is `on_result`, once its result step published, or once its run started if it has no result step; else when the run completed. From then on `output` is the run's answer and never changes; stop polling here if you only need the answer. `status` still follows every step, so a run can report success and later fail. Null until the run reports, for a run that failed before reporting, and for runs that ended before this field existed.", + "title": "Result Reported At" + }, "run_id": { "description": "Unique identifier for the agent run.", "title": "Run Id", @@ -944,7 +957,7 @@ "type": "null" } ], - "description": "Cumulative milliseconds the run was parked on standard-mode wait steps. Subtracted from active duration in run-detail and duration-stats responses, exactly like hitl_wait_ms. Priority waits block inline and are not counted here.", + "description": "Sum over the run's standard-mode wait steps of each one's wait, in milliseconds. Waits that overlap are each counted in full. Priority waits block inline and are not counted here.", "title": "Wait Ms" } }, @@ -1175,7 +1188,7 @@ "type": "null" } ], - "description": "Metadata to make available for string substitution expressions in agent tasks.", + "description": "Metadata for string substitution in agent tasks. Each key must be one the agent's trigger declares (or sets); a run that sends another custom key, or lacks a required one, is refused with HTTP 400.", "title": "Metadata" }, "replay_of_run_id": { @@ -1389,8 +1402,8 @@ "title": "Disabled Reason" }, "evaluation_mode": { - "default": "eval_and_retry", - "description": "Evaluation mode: output_expectation, eval_and_retry, or sample_and_flag.", + "default": "sample_and_flag", + "description": "Evaluation mode: output_expectation or sample_and_flag.", "title": "Evaluation Mode", "type": "string" }, @@ -1440,7 +1453,7 @@ }, "max_retries": { "default": 3, - "description": "Max retries for eval_and_retry mode.", + "description": "Deprecated: has no effect.", "title": "Max Retries", "type": "integer" }, @@ -1503,7 +1516,7 @@ "type": "null" } ], - "description": "Failure signals that trigger rollback. Defaults to agent_eval_fail, governance_block, agent_run_failed when null.", + "description": "Failure signals that trigger rollback. Defaults to governance_block, agent_run_failed when null.", "title": "Prompt Model Auto Rollback Triggers" }, "prompt_model_auto_upgrade_strategy": { @@ -1514,7 +1527,7 @@ }, "retry_on_failure": { "default": true, - "description": "Whether to retry on evaluation failure.", + "description": "Deprecated: has no effect.", "title": "Retry On Failure", "type": "boolean" }, @@ -3412,7 +3425,7 @@ "type": "object" }, "CreateEvaluationCriteriaRequest": { - "description": "Request body for creating an evaluation criteria.\n\nThe evaluation mode, retry settings, and sample frequency are set at the\nagent level, not per-criteria.", + "description": "Request body for creating an evaluation criteria.\n\nstep_id names the display_result or streaming_result step to score. The\nevaluation mode and sample frequency are set at the\nagent level, not per-criteria.", "properties": { "description": { "anyOf": [ @@ -3522,12 +3535,14 @@ }, "retry_count": { "default": 0, + "description": "Deprecated: has no effect on any count.", "minimum": 0.0, "title": "Retry Count", "type": "integer" }, "retry_triggered": { "default": false, + "description": "Retired; true returns 400 from Seclai-Version 2026-11-04.", "title": "Retry Triggered", "type": "boolean" }, @@ -4127,6 +4142,29 @@ "title": "CreateSourceBody", "type": "object" }, + "DeclarableMetadataKey": { + "properties": { + "always_present": { + "description": "Whether every run carries this key.", + "title": "Always Present", + "type": "boolean" + }, + "key": { + "title": "Key", + "type": "string" + }, + "origin": { + "$ref": "#/components/schemas/MetadataOrigin" + } + }, + "required": [ + "key", + "origin", + "always_present" + ], + "title": "DeclarableMetadataKey", + "type": "object" + }, "DmarcFailingSourceResponse": { "properties": { "failed_count": { @@ -5062,7 +5100,7 @@ "type": "boolean" }, "evaluation_mode": { - "description": "Runtime behavior mode. output_expectation (manual validation), eval_and_retry (every run + retry), sample_and_flag (sampled monitoring).", + "description": "Runtime behavior mode. output_expectation (manual validation), sample_and_flag (sampled monitoring).", "title": "Evaluation Mode", "type": "string" }, @@ -5106,6 +5144,7 @@ "type": "string" }, "max_retries": { + "description": "Deprecated: has no effect.", "title": "Max Retries", "type": "integer" }, @@ -5124,6 +5163,7 @@ "type": "object" }, "retry_on_failure": { + "description": "Deprecated: has no effect.", "title": "Retry On Failure", "type": "boolean" }, @@ -5253,10 +5293,12 @@ "type": "string" }, "retry_count": { + "description": "Deprecated.", "title": "Retry Count", "type": "integer" }, "retry_triggered": { + "description": "Deprecated.", "title": "Retry Triggered", "type": "boolean" }, @@ -5439,10 +5481,12 @@ "type": "string" }, "retry_count": { + "description": "Deprecated.", "title": "Retry Count", "type": "integer" }, "retry_triggered": { + "description": "Deprecated.", "title": "Retry Triggered", "type": "boolean" }, @@ -6118,7 +6162,7 @@ "title": "Step Id" }, "step_type": { - "description": "The step type to generate config for (e.g. 'regex_replace', 'gate', 'text', 'prompt_call', 'retrieval').", + "description": "The step type to generate config for (e.g. 'regex_replace', 'if_else', 'text', 'prompt_call', 'retrieval').", "title": "Step Type", "type": "string" }, @@ -6726,6 +6770,27 @@ "title": "KnowledgeBaseListResponseModel", "type": "object" }, + "KnowledgeBaseMetadataKeyStatsResponse": { + "properties": { + "knowledge_base_id": { + "title": "Knowledge Base Id", + "type": "string" + }, + "windows": { + "items": { + "$ref": "#/components/schemas/MetadataKeyWindowResponse" + }, + "title": "Windows", + "type": "array" + } + }, + "required": [ + "knowledge_base_id", + "windows" + ], + "title": "KnowledgeBaseMetadataKeyStats", + "type": "object" + }, "KnowledgeBaseResponseModel": { "description": "Response model for a single knowledge base.", "properties": { @@ -7278,6 +7343,198 @@ "title": "MemoryBank", "type": "object" }, + "MetadataKeyCountResponse": { + "properties": { + "distinct_values": { + "description": "How many different values it takes.", + "title": "Distinct Values", + "type": "integer" + }, + "items": { + "description": "Items in the window carrying the key.", + "title": "Items", + "type": "integer" + }, + "key": { + "description": "The item-metadata key.", + "title": "Key", + "type": "string" + }, + "top_values": { + "description": "Its 5 most frequent values, most frequent first.", + "items": { + "$ref": "#/components/schemas/MetadataValueCountResponse" + }, + "title": "Top Values", + "type": "array" + } + }, + "required": [ + "key", + "items", + "distinct_values", + "top_values" + ], + "title": "MetadataKeyCountResponse", + "type": "object" + }, + "MetadataKeyDeclaration": { + "additionalProperties": false, + "properties": { + "key": { + "description": "Steps reference the key as ``{{metadata.}}``.", + "maxLength": 255, + "minLength": 1, + "title": "Key", + "type": "string" + }, + "origin": { + "$ref": "#/components/schemas/MetadataOrigin", + "description": "``system`` and ``source`` keys are written by the platform; ``custom`` keys are sent by the caller or set on the trigger." + }, + "required": { + "default": false, + "description": "A caller-started run without this key is refused. Only a ``custom`` key can be required.", + "title": "Required", + "type": "boolean" + } + }, + "required": [ + "key", + "origin" + ], + "title": "MetadataKeyDeclaration", + "type": "object" + }, + "MetadataKeyWindowResponse": { + "properties": { + "keys": { + "description": "Keys seen in the window, most frequent first.", + "items": { + "$ref": "#/components/schemas/MetadataKeyCountResponse" + }, + "title": "Keys", + "type": "array" + }, + "since": { + "anyOf": [ + { + "format": "date-time", + "type": "string" + }, + { + "type": "null" + } + ], + "description": "The window's start; null for all time.", + "title": "Since" + }, + "total_items": { + "description": "Items in the window.", + "title": "Total Items", + "type": "integer" + }, + "window": { + "enum": [ + "all_time", + "last_30_days", + "last_7_days" + ], + "title": "Window", + "type": "string" + } + }, + "required": [ + "window", + "since", + "total_items", + "keys" + ], + "title": "MetadataKeyWindowResponse", + "type": "object" + }, + "MetadataKeysResponse": { + "properties": { + "accepts_any_source_key": { + "description": "True for content triggers, which may declare any item-metadata key.", + "title": "Accepts Any Source Key", + "type": "boolean" + }, + "agent_id": { + "format": "uuid", + "title": "Agent Id", + "type": "string" + }, + "declarable_keys": { + "description": "The system and source keys this trigger's type can declare.", + "items": { + "$ref": "#/components/schemas/DeclarableMetadataKey" + }, + "title": "Declarable Keys", + "type": "array" + }, + "metadata_keys": { + "description": "The keys the agent's steps may reference. Static trigger metadata and Slack form fields are declared custom keys too, and are not repeated here.", + "items": { + "$ref": "#/components/schemas/MetadataKeyDeclaration" + }, + "title": "Metadata Keys", + "type": "array" + }, + "trigger_id": { + "format": "uuid", + "title": "Trigger Id", + "type": "string" + }, + "warnings": { + "description": "Set by a PUT that changes the declaration: agents whose `call_agent` mapping no longer fits it. Always empty on GET.", + "items": { + "type": "string" + }, + "title": "Warnings", + "type": "array" + } + }, + "required": [ + "trigger_id", + "agent_id", + "metadata_keys", + "declarable_keys", + "accepts_any_source_key" + ], + "title": "MetadataKeysResponse", + "type": "object" + }, + "MetadataOrigin": { + "description": "Who writes a run metadata key (docs/architecture/run-metadata.md, Q2).", + "enum": [ + "system", + "source", + "custom" + ], + "title": "MetadataOrigin", + "type": "string" + }, + "MetadataValueCountResponse": { + "properties": { + "items": { + "description": "Items carrying this value.", + "title": "Items", + "type": "integer" + }, + "value": { + "description": "The value as text, cut to 100 characters; an object is shown as {\u2026} and a list as [\u2026].", + "title": "Value", + "type": "string" + } + }, + "required": [ + "value", + "items" + ], + "title": "MetadataValueCountResponse", + "type": "object" + }, "ModalityRateResponse": { "description": "Per-modality rate for an LLM that prices image/audio/video output\n(or input) at a rate distinct from the default text rate.\n\nExample: Gemini 3.1 Flash Image charges $3/1M output tokens for\ntext but $60/1M output tokens for generated images. The image rate\nsurfaces here with ``modality=\"image\"`` and ``output_credits_per_1000_tokens``\nset; the default text rate stays on the parent model fields.", "properties": { @@ -7969,6 +8226,23 @@ "title": "SetAutoBlockModeRequest", "type": "object" }, + "SetMetadataKeysRequest": { + "properties": { + "metadata_keys": { + "description": "The whole declaration; replaces the trigger's current one.", + "items": { + "$ref": "#/components/schemas/MetadataKeyDeclaration" + }, + "title": "Metadata Keys", + "type": "array" + } + }, + "required": [ + "metadata_keys" + ], + "title": "SetMetadataKeysRequest", + "type": "object" + }, "SetSlackTriggerConfigApiRequest": { "description": "Omitted fields are left unchanged.", "properties": { @@ -7983,6 +8257,18 @@ ], "description": "`everywhere` in scope, or `channel_opt_in`." }, + "alias": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "The name people type after `/seclai` to run this agent: lowercase letters, digits and hyphens, starting with a letter, unique in the Slack workspace. Generated from the agent's name when not set or empty.", + "title": "Alias" + }, "allow_dms": { "anyOf": [ { @@ -8022,7 +8308,7 @@ "type": "null" } ], - "description": "Form fields `{key, label, type, required, hint, choices, max_length}`. `type`: short_text, long_text, number, single_choice, multi_choice, yes_no, date, slack_user or slack_channel. Each value reaches the run as `{{metadata.}}`.", + "description": "Form fields `{key, label, type, required, hint, choices, max_length}`. `type`: short_text, long_text, number, single_choice, multi_choice, yes_no, date, slack_user or slack_channel. Each value reaches the run as `{{metadata.}}`, not in the run's input, which is the text after `/seclai ` or the message the shortcut was used on, and its files.", "title": "Form" }, "include_invoker_email": { @@ -8036,18 +8322,6 @@ ], "title": "Include Invoker Email" }, - "input": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "description": "The trigger's input template. Each `{{metadata.}}` in it must be a form field key or a platform key; it is checked together with `form`.", - "title": "Input" - }, "max_turns": { "anyOf": [ { @@ -8225,6 +8499,18 @@ "title": "Agent Id", "type": "string" }, + "alias": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "The name people type after `/seclai` to run this agent.", + "title": "Alias" + }, "allow_dms": { "title": "Allow Dms", "type": "boolean" @@ -9817,7 +10103,7 @@ "type": "object" }, "UpdateEvaluationCriteriaRequest": { - "description": "Request body for updating an evaluation criteria.\n\nRetry settings and sample frequency are set at the agent level.", + "description": "Request body for updating an evaluation criteria.\n\nThe evaluation mode and sample frequency are set at the agent level.", "properties": { "description": { "anyOf": [ @@ -11115,7 +11401,7 @@ "type": "null" } ], - "description": "Evaluation mode: 'output_expectation', 'eval_and_retry', or 'sample_and_flag'.", + "description": "Evaluation mode: 'output_expectation' or 'sample_and_flag'. From Seclai-Version 2026-11-04 'eval_and_retry' returns 400; earlier versions store it as 'sample_and_flag'.", "title": "Evaluation Mode" }, "max_credits_per_period": { @@ -11153,7 +11439,7 @@ "type": "null" } ], - "description": "Max retries for eval_and_retry mode (1-10).", + "description": "Deprecated: accepted and has no effect.", "title": "Max Retries" }, "max_runs_per_day": { @@ -11231,7 +11517,7 @@ "type": "null" } ], - "description": "Failure signals that trigger rollback: agent_eval_fail, governance_flag, governance_block, agent_run_failed.", + "description": "Failure signals that trigger rollback: governance_flag, governance_block, agent_run_failed. agent_eval_fail is accepted and never fires; in the list, a run with a failed evaluation is never picked as the rollback target.", "title": "Prompt Model Auto Rollback Triggers" }, "prompt_model_auto_upgrade_strategy": { @@ -11254,7 +11540,7 @@ "type": "null" } ], - "description": "Whether to retry on evaluation failure.", + "description": "Deprecated: accepted and has no effect.", "title": "Retry On Failure" }, "sampling_config": { @@ -14955,7 +15241,7 @@ ] }, "patch": { - "description": "Update an evaluation criteria.\n\nAccepts a partial update \u2013 only the fields included in the request body\nare modified. Use this to toggle enabled/disabled, change the\nevaluation prompt, adjust retries, or rename the criteria.", + "description": "Update an evaluation criteria.\n\nAccepts a partial update \u2013 only the fields included in the request body\nare modified. Use this to toggle enabled/disabled, change the\nevaluation prompt, or rename the criteria. From Seclai-Version 2026-11-04 a\nchanged `step_id` must name a `display_result` or `streaming_result` step.", "operationId": "update_evaluation_criteria_api_agents_evaluation_criteria__criteria_id__patch", "parameters": [ { @@ -15285,7 +15571,7 @@ ] }, "post": { - "description": "Record an evaluation result for a criteria.\n\nUse this endpoint to push results from external test harnesses, CI/CD\npipelines, or custom evaluation logic. Each result is linked to an\nagent run and optionally a specific step run.", + "description": "Record an evaluation result for a criteria.\n\nUse this endpoint to push results from external test harnesses, CI/CD\npipelines, or custom evaluation logic. Each result is linked to an\nagent run and optionally a specific step run. From Seclai-Version 2026-11-04\n`retry_triggered: true` returns 400: evaluations never retry a step.", "operationId": "create_evaluation_result_api_agents_evaluation_criteria__criteria_id__results_post", "parameters": [ { @@ -15429,7 +15715,7 @@ }, "/agents/evaluation-results/non-manual-summary": { "get": { - "description": "Get an evaluation summary for API key clients.\n\nReturns aggregated pass/fail/flagged counts and pass rates for each evaluation mode (eval_and_retry, sample_and_flag).\n\nWith ``2026-10-21`` or later, ``error`` results (the evaluator returned no\nverdict) are left out of ``failed``, and the rates are over passed and\nfailed results. Earlier versions count them in ``failed`` and rate over\nevery result. ``error`` is returned on every version.\n\nThe ``agent_id`` scoping parameter is part of the ``2026-07-27`` changeset\n(opt in via the ``Seclai-Version`` header). Clients on the legacy baseline\nalways receive the account-wide rollup; ``agent_id`` is ignored for them so\nthe endpoint's behavior is frozen. With ``2026-07-27`` or later, the summary\nis scoped to ``agent_id`` when supplied (and returns 404 if it doesn't exist).", + "description": "Get an evaluation summary for API key clients.\n\nReturns aggregated pass/fail/flagged counts and pass rates for each automatic evaluation mode.\n\nWith ``2026-10-21`` or later, ``error`` results (the evaluator returned no\nverdict) are left out of ``failed``, and the rates are over passed and\nfailed results. Earlier versions count them in ``failed`` and rate over\nevery result. ``error`` is returned on every version.\n\nThe ``agent_id`` scoping parameter is part of the ``2026-07-27`` changeset\n(opt in via the ``Seclai-Version`` header). Clients on the legacy baseline\nalways receive the account-wide rollup; ``agent_id`` is ignored for them so\nthe endpoint's behavior is frozen. With ``2026-07-27`` or later, the summary\nis scoped to ``agent_id`` when supplied (and returns 404 if it doesn't exist).", "operationId": "get_non_manual_evaluation_summary_api_agents_evaluation_results_non_manual_summary_get", "parameters": [ { @@ -16309,7 +16595,7 @@ ] }, "put": { - "description": "Update an agent's name, description, evaluation settings, model lifecycle settings and run limits.\n\nEvaluation settings: `evaluation_mode` ('output_expectation', 'eval_and_retry', 'sample_and_flag'), `default_evaluation_tier` ('fast', 'balanced', 'thorough'), `max_retries`, `retry_on_failure`, `sampling_config`.\n\nModel lifecycle settings: `prompt_model_auto_upgrade_strategy` ('none', 'early_adopter', 'middle_of_road', 'cautious_adopter'), `prompt_model_auto_rollback_enabled`, `prompt_model_auto_rollback_triggers` (list of 'agent_eval_fail', 'governance_flag', 'governance_block', 'agent_run_failed').\n\nRun limits (each must be greater than 0; pass the paired `set_: true` with the value omitted to remove one): `max_credits_per_run`, `max_credits_per_period`, `max_runs_per_hour`, `max_runs_per_day`, `max_runs_total`. A runs-per-hour or per-day value above the plan's run quota is rejected with 400.\n\nReplacing the workflow from an export:\n- Pass `agent_definition` with the JSON shape produced by `GET /agents/{id}/export`. Update only touches the workflow + agent metadata \u2014 alert_configs, evaluation_criteria, governance_policies, schedules, and solution links from the imported file are NOT applied (use the dedicated endpoints for those, or `POST /agents` to import as a new agent).\n- `entity_remap: {source_uuid: target_uuid}` substitutes workflow entity refs before save (same shape as `POST /agents`).\n\nAt least one field must be provided.\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token. You can only update agents belonging to your account.", + "description": "Update an agent's name, description, evaluation settings, model lifecycle settings and run limits.\n\nEvaluation settings: `evaluation_mode` ('output_expectation', 'sample_and_flag'; see the field), `default_evaluation_tier` ('fast', 'balanced', 'thorough'), `sampling_config`. `max_retries` and `retry_on_failure` are accepted and have no effect.\n\nModel lifecycle settings: `prompt_model_auto_upgrade_strategy` ('none', 'early_adopter', 'middle_of_road', 'cautious_adopter'), `prompt_model_auto_rollback_enabled`, `prompt_model_auto_rollback_triggers` (list of 'governance_flag', 'governance_block', 'agent_run_failed'; 'agent_eval_fail' never fires, and in the list keeps a run with a failed evaluation from being a rollback target).\n\nRun limits (each must be greater than 0; pass the paired `set_: true` with the value omitted to remove one): `max_credits_per_run`, `max_credits_per_period`, `max_runs_per_hour`, `max_runs_per_day`, `max_runs_total`. A runs-per-hour or per-day value above the plan's run quota is rejected with 400.\n\nReplacing the workflow from an export:\n- Pass `agent_definition` with the JSON shape produced by `GET /agents/{id}/export`. Update only touches the workflow + agent metadata \u2014 alert_configs, evaluation_criteria, governance_policies, schedules, and solution links from the imported file are NOT applied (use the dedicated endpoints for those, or `POST /agents` to import as a new agent).\n- `entity_remap: {source_uuid: target_uuid}` substitutes workflow entity refs before save (same shape as `POST /agents`).\n\nAt least one field must be provided.\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token. You can only update agents belonging to your account.", "operationId": "update_agent_api_agents__agent_id__put", "parameters": [ { @@ -16887,7 +17173,7 @@ }, "/agents/{agent_id}/definition": { "get": { - "description": "Fetch the current agent definition from the main branch.\n\nThe response includes `change_id` which must be provided when updating the definition (optimistic locking).\n\nThe definition contains the agent's step workflow. Available step types:\n- `prompt_call`: Call an LLM with a prompt template\n- `retrieval`: Search a knowledge base\n- `regex_replace`: Reshape text via ordered regex find/replace rules\n- `gate`: Evaluate conditions, stop or continue child execution\n- `retry`: Re-execute from a target ancestor step (for quality-control loops; pair with a `gate` step for conditional retrying. Fields: `target_step_id` (ancestor step ID), `max_retries` (1\u201310))\n- `evaluate_step`: Score a selected previous step output and emit JSON with `score`, `passed`, and `pass_threshold` (fields: `target_step_id`, `evaluation_prompt`, `pass_threshold`, optional `evaluation_tier`, optional `expectation_config`)\n- `extract_data`: Progressively read and analyze large input\n- `extract_content`: Extract structured data (JSON, HTML, XML)\n- `add_chat_turn` / `load_chat_history`: Record a turn or load running history from a conversation memory bank\n- `add_memory` / `search_memory` / `load_memory`: Write, semantic-search, or load entries on a general memory bank\n- `send_email`: Send email with step output\n- `webhook_call`: POST data to an external URL\n- `write_aws_s3_object`: Write output to S3\n- `call_agent`: Invoke another agent\n- `write_metadata`: Write a value to content metadata (for filtering/gates; content-triggered agents only. Fields: `metadata_key`, `content`)\n- `write_content_attachment`: Write a file-backed attachment to content (optionally indexed for retrieval; content-triggered agents only. Fields: `attachment_key`, `content`, `content_type`, `indexed`)\n- `load_content_attachment`: Load a previously written attachment (content-triggered agents only. Fields: `attachment_key`)\n- `load_content`: Load the full text body of a source document (typically used with content-triggered agents; can also load by explicit `content_version_id`. Fields: `content_version_id` optional)\n- `streaming_result`: Stream LLM tokens in real-time via SSE (must be a direct child of `prompt_call`; requires `dynamic_input` or `template_input` trigger; `priority: true` enables real-time streaming). To stream **and** return a schema-validated payload, add a sibling branch `extract_content` (`expected_format: \"json\"` + `json_schema`) \u2192 `display_result` under the same `prompt_call` \u2014 a `display_result` takes precedence over the stream regardless of which finishes first, so its validated output becomes the run's result while the tokens act as a progress channel\n- `display_result`: Show output to the user\n- `join`: Merge parallel branches\n- `merge`: Combine multiple inputs into a single templated output\n- `text`: Static text literal\n- `for_each`: Iterate a body over a list of items (body lives in `body[]`)\n- `if_else`: Conditional dispatch. Evaluates `conditions` (same shape as `gate`) and runs `then_steps` on match, otherwise the optional `else_steps`. The chosen branch's output flows to the if_else step's own `child_steps` (post-branch continuation chain). **`display_result` and `streaming_result` are not allowed inside `then_steps` / `else_steps`** \u2014 end each branch with a content-producing step (e.g. `text`, `prompt_call`) and place the single `display_result` in `child_steps`.\n- `switch`: Single-discriminator dispatch. Renders `discriminator` (default `{{input}}`) and routes to the first matching `cases[]` entry (equality by default; pass a list in `match` for `$in` semantics) or to `else_steps` when nothing matches. The chosen case's output flows to the switch step's own `child_steps`. **`display_result` and `streaming_result` are not allowed inside `cases[].steps` or `else_steps`** \u2014 end each case with a content-producing step and place the single `display_result` in `child_steps`.\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token. You can only access agents belonging to your account.", + "description": "Fetch the current agent definition from the main branch.\n\nThe response includes `change_id` which must be provided when updating the definition (optimistic locking).\n\nThe definition contains the agent's step workflow. Available step types:\n- `prompt_call`: Call an LLM with a prompt template\n- `retrieval`: Search a knowledge base\n- `regex_replace`: Reshape text via ordered regex find/replace rules\n- `repeat_until`: Run a body (`body[]`) again until its `conditions` match the iteration's verdict or `max_iterations` (1\u20131000, default 3) is reached. Fields: `conditions`, `match`, optional `verdict_template`, `output` (`last` or `all`), `fail_when_max_reached`\n- `evaluate_step`: Score a selected previous step output and emit JSON with `score`, `passed`, and `pass_threshold` (fields: `target_step_id`, `evaluation_prompt`, `pass_threshold`, optional `evaluation_tier`, optional `expectation_config`)\n- `extract_data`: Progressively read and analyze large input\n- `extract_content`: Extract structured data (JSON, HTML, XML)\n- `add_chat_turn` / `load_chat_history`: Record a turn or load running history from a conversation memory bank\n- `add_memory` / `search_memory` / `load_memory`: Write, semantic-search, or load entries on a general memory bank\n- `send_email`: Send email with step output\n- `webhook_call`: POST data to an external URL\n- `write_aws_s3_object`: Write output to S3\n- `call_agent`: Invoke another agent\n- `write_metadata`: Write a value to content metadata (for filtering/gates; content-triggered agents only. Fields: `metadata_key`, `content`)\n- `write_content_attachment`: Write a file-backed attachment to content (optionally indexed for retrieval; content-triggered agents only. Fields: `attachment_key`, `content`, `content_type`, `indexed`)\n- `load_content_attachment`: Load a previously written attachment (content-triggered agents only. Fields: `attachment_key`)\n- `load_content`: Load the full text body of a source document (typically used with content-triggered agents; can also load by explicit `content_version_id`. Fields: `content_version_id` optional)\n- `streaming_result`: Stream LLM tokens in real-time via SSE (must be a direct child of `prompt_call`; requires `dynamic_input` or `template_input` trigger; `priority: true` enables real-time streaming). An agent has at most one `streaming_result` or `display_result`; saving refuses a second\n- `display_result`: Show output to the user\n- `join`: Merge parallel branches\n- `merge`: Combine multiple inputs into a single templated output\n- `text`: Static text literal\n- `for_each`: Iterate a body over a list of items (body lives in `body[]`)\n- `if_else`: Conditional dispatch. Evaluates `conditions` and runs `then_steps` on match, otherwise the optional `else_steps`. The chosen branch's output flows to the if_else step's own `child_steps` (post-branch continuation chain). **`display_result` and `streaming_result` are not allowed inside `then_steps` / `else_steps`** \u2014 end each branch with a content-producing step (e.g. `text`, `prompt_call`) and place the single `display_result` in `child_steps`.\n- `switch`: Single-discriminator dispatch. Renders `discriminator` (default `{{input}}`) and routes to the first matching `cases[]` entry (equality by default; pass a list in `match` for `$in` semantics) or to `else_steps` when nothing matches. The chosen case's output flows to the switch step's own `child_steps`. **`display_result` and `streaming_result` are not allowed inside `cases[].steps` or `else_steps`** \u2014 end each case with a content-producing step and place the single `display_result` in `child_steps`.\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token. You can only access agents belonging to your account.", "operationId": "get_agent_definition_api_agents__agent_id__definition_get", "parameters": [ { @@ -16952,7 +17238,7 @@ ] }, "put": { - "description": "Update the agent's definition on the main branch.\n\nUses **optimistic locking**: provide `expected_change_id` from the last `GET /agents/{agent_id}/definition`. Returns `409 Conflict` if the definition was modified since your last read.\n\nThe definition contains the agent's step workflow. Step types include `prompt_call`, `retrieval`, `regex_replace`, `gate`, `retry`, `evaluate_step`, `extract_data`, `extract_content`, `add_chat_turn`, `load_chat_history`, `add_memory`, `search_memory`, `load_memory`, `streaming_result`, `send_email`, `webhook_call`, `write_aws_s3_object`, `call_agent`, `write_metadata`, `write_content_attachment`, `load_content_attachment`, `load_content`, `display_result`, `join`, `merge`, `text`, `for_each`, `if_else`, and `switch`. Non-composite step types (`display_result`, `join`, `retry`, `streaming_result`) cannot contain child steps.\n\n**Retry steps** re-execute from a target ancestor step for quality-control loops. Configure with `target_step_id` (ancestor step ID) and `max_retries` (1\u201310). Best practice: place a `gate` step before the retry to make retries conditional.\n\n**if_else** runs `then_steps` when its `conditions` (same shape as `gate`) match, otherwise its optional `else_steps`. Either branch's output flows to the if_else step's own `child_steps` (the post-branch continuation chain).\n\n**switch** dispatches on a `discriminator` template (default `{{input}}`) to the first matching case (equality by default; pass a list in `match` for `$in` semantics) or to `else_steps` when no case matches. Cases own their own `steps` subtrees; the chosen branch's output flows to the switch step's own `child_steps`.\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token. You can only update agents belonging to your account.", + "description": "Update the agent's definition on the main branch.\n\nUses **optimistic locking**: provide `expected_change_id` from the last `GET /agents/{agent_id}/definition`. Returns `409 Conflict` if the definition was modified since your last read.\n\nThe definition contains the agent's step workflow. Step types include `prompt_call`, `retrieval`, `regex_replace`, `evaluate_step`, `extract_data`, `extract_content`, `add_chat_turn`, `load_chat_history`, `add_memory`, `search_memory`, `load_memory`, `streaming_result`, `send_email`, `webhook_call`, `write_aws_s3_object`, `call_agent`, `write_metadata`, `write_content_attachment`, `load_content_attachment`, `load_content`, `display_result`, `join`, `merge`, `text`, `for_each`, `repeat_until`, `if_else`, and `switch`. Non-composite step types (`display_result`, `join`, `streaming_result`) cannot contain child steps. A definition holding a `gate` or `retry` step is rejected: use `if_else`, or `repeat_until` to run steps again until a condition holds.\n\n**repeat_until** runs its `body[]`, then tests its `conditions` against the iteration's verdict (`verdict_template`, else the iteration's value); it repeats until they match or `max_iterations` is reached.\n\n**if_else** runs `then_steps` when its `conditions` match, otherwise its optional `else_steps`. Either branch's output flows to the if_else step's own `child_steps` (the post-branch continuation chain).\n\n**switch** dispatches on a `discriminator` template (default `{{input}}`) to the first matching case (equality by default; pass a list in `match` for `$in` semantics) or to `else_steps` when no case matches. Cases own their own `steps` subtrees; the chosen branch's output flows to the switch step's own `child_steps`.\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token. You can only update agents belonging to your account.", "operationId": "update_agent_definition_api_agents__agent_id__definition_put", "parameters": [ { @@ -17255,7 +17541,7 @@ ] }, "post": { - "description": "Create new step evaluation settings for an agent.\n\nThe evaluation mode, retry settings, and sample frequency are inherited\nfrom the agent and stored on the criteria row for historical reference.", + "description": "Create new step evaluation settings for an agent.\n\nFrom Seclai-Version 2026-11-04, `step_id` must name a `display_result` or\n`streaming_result` step, the run's published result; another step returns 400.\nThe evaluation mode and sample frequency are the agent's.", "operationId": "create_evaluation_criteria_api_agents__agent_id__evaluation_criteria_post", "parameters": [ { @@ -17727,7 +18013,7 @@ }, "/agents/{agent_id}/export": { "get": { - "description": "Export an agent definition as a portable JSON snapshot.\n\nThe response contains the full definition, trigger configuration with schedules, alert configs, evaluation criteria, agent-scoped governance policies, and a resolved dependency manifest that maps every referenced external entity UUID to its human-readable name.\n\nResponse shape:\n- `export_version`: schema version (currently `\"5\"`)\n- `exported_at`: ISO-8601 timestamp\n- `agent`: name, description, schema_version, definition, timestamps\n- `trigger`: trigger type, input template, schedules\n- `alert_configs`: alert type, thresholds, recipients\n- `evaluation_criteria`: evaluation settings per step\n- `governance_policies`: agent-scoped governance policies\n- `dependencies`: knowledge_bases, memory_banks, source_connections, agents, users\n\nQuery params:\n- `download` (default true): when true, sets `Content-Disposition: attachment` so clients treat the response as a file download.\n\nAuth & scoping:\n- Requires `X-API-Key`. You can only export agents belonging to your account.", + "description": "Export an agent definition as a portable JSON snapshot.\n\nThe response contains the full definition, trigger configuration with schedules, alert configs, evaluation criteria, agent-scoped governance policies, and a resolved dependency manifest that maps every referenced external entity UUID to its human-readable name.\n\nResponse shape:\n- `export_version`: schema version (currently `\"6\"`)\n- `exported_at`: ISO-8601 timestamp\n- `agent`: name, description, schema_version, definition, timestamps\n- `trigger`: trigger type, input template, schedules\n- `alert_configs`: alert type, thresholds, recipients\n- `evaluation_criteria`: evaluation settings per step\n- `governance_policies`: agent-scoped governance policies\n- `dependencies`: knowledge_bases, memory_banks, source_connections, agents, users\n\nQuery params:\n- `download` (default true): when true, sets `Content-Disposition: attachment` so clients treat the response as a file download.\n\nAuth & scoping:\n- Requires `X-API-Key`. You can only export agents belonging to your account.", "operationId": "export_agent_api_agents__agent_id__export_get", "parameters": [ { @@ -17992,7 +18278,7 @@ ] }, "post": { - "description": "Start an agent run.\n\nAn *agent* is an automated workflow that can monitor content from your sources, process it with AI, and trigger actions. This endpoint creates a new run and returns a `run_id` you can poll to retrieve status and output.\n\nWhen to use:\n- Use this endpoint for request/response style integrations where polling is acceptable.\n- Use `POST /agents/{agent_id}/runs/stream` if you need real-time progress via SSE.\n\nKey fields:\n- `input`: text input for agents with a `dynamic_input` trigger.\n- `input_upload_id` / `input_upload_ids`: reference one or more files previously uploaded via `POST /agents/{agent_id}/upload-input`. Send them **with** `input` to pair prompt text with the files (the text leads, each file follows under its heading); only the two upload fields are mutually exclusive with each other.\n- `priority`: set true for latency-sensitive, user-facing work. For agents with a `streaming_result` step, set `priority=true` to enable real-time token streaming; otherwise the run still proceeds, but without live token streaming.\n- `metadata`: a JSON object that becomes available to agent steps for string substitution.\n\nAfter starting:\n- Poll `GET /agents/runs/{run_id}` until `status` is `completed` or `failed`.\n- Use `include_step_outputs=true` to include per-step outputs, timing, and credits.\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token. All resources are scoped to the caller's account.", + "description": "Start an agent run.\n\nAn *agent* is an automated workflow that can monitor content from your sources, process it with AI, and trigger actions. This endpoint creates a new run and returns a `run_id` you can poll to retrieve status and output.\n\nWhen to use:\n- Use this endpoint for request/response style integrations where polling is acceptable.\n- Use `POST /agents/{agent_id}/runs/stream` if you need real-time progress via SSE.\n\nKey fields:\n- `input`: text input for agents with a `dynamic_input` trigger.\n- `input_upload_id` / `input_upload_ids`: reference one or more files previously uploaded via `POST /agents/{agent_id}/upload-input`. Send them **with** `input` to pair prompt text with the files (the text leads, each file follows under its heading); only the two upload fields are mutually exclusive with each other.\n- `priority`: set true for latency-sensitive, user-facing work. For agents with a `streaming_result` step, set `priority=true` to enable real-time token streaming; otherwise the run still proceeds, but without live token streaming.\n- `metadata`: a JSON object for string substitution. Each key must be one the trigger declares (`GET /agents/{agent_id}/triggers/{trigger_id}/metadata-keys`); a run that sends another custom key, or lacks a required one, is refused with HTTP 400.\n\nAfter starting:\n- Poll `GET /agents/runs/{run_id}` until `result_reported_at` is set (the run's answer is in `output`) or `status` is `failed`; poll on until `status` is `completed` or `failed` if you need to know that every step finished.\n- Use `include_step_outputs=true` to include per-step outputs, timing, and credits.\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token. All resources are scoped to the caller's account.", "operationId": "run_agent_api_agents__agent_id__runs_post", "parameters": [ { @@ -18079,7 +18365,7 @@ }, "/agents/{agent_id}/runs/stream": { "post": { - "description": "Start a **priority** agent run and stream run events using Server-Sent Events (SSE).\n\nThis is the best option for interactive UIs where you want progress updates as the run executes.\n\nHow it works:\n- The first `init` event contains an `AgentRunResponse` snapshot, including the `run_id`.\n- Subsequent events are forwarded from the run event stream (status changes, step events, etc).\n- If the agent contains a `streaming_result` step, `stream_token` events deliver individual LLM tokens (with a `token` field) and a `stream_end` event signals completion.\n- With `include_reasoning=true`, `stream_reasoning` events (with a `text` field) carry the model's reasoning while it thinks, when the `streaming_result` step's author enabled `show_reasoning`. Reasoning is never part of `output`.\n- The final `done` event contains the terminal snapshot (including `output` and `credits` when available).\n\nInput options (for `dynamic_input` triggers):\n- `input`: text input passed directly.\n- `input_upload_id` / `input_upload_ids`: reference one or more files uploaded via `POST /agents/{agent_id}/upload-input`. Combine either with `input` to send prompt text alongside the files; only the two upload fields are mutually exclusive with each other.\n\nClient guidance:\n- Keep the connection open and handle keepalive comments.\n- On `timeout` or `error`, the payload includes `run_id` so clients can resume by polling `GET /agents/runs/{run_id}`.\n- `stream_token` events carry the model's raw output. When the agent pairs `streaming_result` with a sibling `extract_content`/`display_result` branch, that branch's `display_result` takes precedence over the stream, so the `done` snapshot's `output` is the validated payload and the tokens are a progress channel \u2014 render tokens live, but read the result from `done`. Check `done.status` first: the streamed text is already the run's output when the stream ends, so a run that FAILED its validation step still carries that raw text in `output`.\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token. All resources are scoped to the caller's account.", + "description": "Start a **priority** agent run and stream run events using Server-Sent Events (SSE).\n\nThis is the best option for interactive UIs where you want progress updates as the run executes.\n\nHow it works:\n- The first `init` event contains an `AgentRunResponse` snapshot, including the `run_id`.\n- Subsequent events are forwarded from the run event stream (status changes, step events, etc).\n- If the agent contains a `streaming_result` step, `stream_token` events deliver individual LLM tokens (with a `token` field) and a `stream_end` event signals completion.\n- With `include_reasoning=true`, `stream_reasoning` events (with a `text` field) carry the model's reasoning while it thinks, when the `streaming_result` step's author enabled `show_reasoning`. Reasoning is never part of `output`.\n- A `result` event contains the snapshot once the run has reported its result (`result_reported_at` is set and `output` is the answer).\n- The final `done` event contains the terminal snapshot (including `output` and `credits` when available).\n\nInput options (for `dynamic_input` triggers):\n- `input`: text input passed directly.\n- `input_upload_id` / `input_upload_ids`: reference one or more files uploaded via `POST /agents/{agent_id}/upload-input`. Combine either with `input` to send prompt text alongside the files; only the two upload fields are mutually exclusive with each other.\n\nClient guidance:\n- Keep the connection open and handle keepalive comments.\n- On `timeout` or `error`, the payload includes `run_id` so clients can resume by polling `GET /agents/runs/{run_id}`.\n- `stream_token` events carry the model's raw output: render them live, but take the answer from the `result` event. `done.status` says whether the whole run succeeded, which can still fail after its result.\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token. All resources are scoped to the caller's account.", "operationId": "run_streaming_agent_api_agents__agent_id__runs_stream_post", "parameters": [ { @@ -18121,7 +18407,7 @@ } } }, - "description": "Streams agent run events via Server-Sent Events (SSE); run is always created as priority.\n\nSSE events:\n- `event: init` \u2014 `data` is an `AgentRunResponse` snapshot (includes `run_id`).\n- `event: done` \u2014 `data` is the final `AgentRunResponse` snapshot (includes `output`, `credits`, etc).\n- Other events (e.g. `status`, step events) are forwarded from the run event stream.\n- On `timeout` / `error`, the payload includes `run_id` so clients can fetch status via `GET /agents/runs/{run_id}`." + "description": "Streams agent run events via Server-Sent Events (SSE); run is always created as priority.\n\nSSE events:\n- `event: init` \u2014 `data` is an `AgentRunResponse` snapshot (includes `run_id`).\n- `event: result` \u2014 `data` is an `AgentRunResponse` snapshot once the run reported success (see `result_reported_at`): its `output` is the run's answer. Sent before `done`; for an agent whose `report_success` is `on_result` it can arrive while later steps still run.\n- `event: done` \u2014 `data` is the final `AgentRunResponse` snapshot (includes `output`, `credits`, etc).\n- Other events (e.g. `status`, step events) are forwarded from the run event stream.\n- On `timeout` / `error`, the payload includes `run_id` so clients can fetch status via `GET /agents/runs/{run_id}`." }, "402": { "content": { @@ -18443,6 +18729,170 @@ ] } }, + "/agents/{agent_id}/triggers/{trigger_id}/metadata-keys": { + "get": { + "description": "A trigger declares the run metadata keys its agent's steps may reference, each `required` or optional. `system` and `source` keys are written by the platform and are never required; `custom` keys are sent by the caller. A run you start is refused with HTTP 400 when it lacks a required key or sends a custom key the trigger does not declare. `trigger_id` is the one `GET /agents/{agent_id}` returns.\n\nAuth & scoping: requires `X-API-Key` header or OAuth Bearer token; the trigger must belong to an agent in the key's account.", + "operationId": "get_metadata_keys_api_api_agents__agent_id__triggers__trigger_id__metadata_keys_get", + "parameters": [ + { + "in": "path", + "name": "agent_id", + "required": true, + "schema": { + "format": "uuid", + "title": "Agent Id", + "type": "string" + } + }, + { + "in": "path", + "name": "trigger_id", + "required": true, + "schema": { + "format": "uuid", + "title": "Trigger Id", + "type": "string" + } + }, + { + "$ref": "#/components/parameters/X-Account-Id" + }, + { + "$ref": "#/components/parameters/Seclai-Version" + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MetadataKeysResponse" + } + } + }, + "description": "Successful Response" + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + }, + "description": "Validation Error" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceUnavailableError" + } + } + }, + "description": "A dependency is unavailable. `database_unavailable` is temporary (for example routine maintenance) and carries a `Retry-After` header, after which the request can be retried unchanged. `vector_store_unavailable` means the vector store backing an embeddings operation is not configured; it carries no `Retry-After` because it does not clear without an operator.", + "headers": { + "Retry-After": { + "description": "Seconds to wait before retrying. Sent only with `database_unavailable`.", + "schema": { + "type": "integer" + } + } + } + } + }, + "summary": "Get the metadata keys a trigger declares", + "tags": [ + "agents" + ] + }, + "put": { + "description": "A trigger declares the run metadata keys its agent's steps may reference, each `required` or optional. `system` and `source` keys are written by the platform and are never required; `custom` keys are sent by the caller. A run you start is refused with HTTP 400 when it lacks a required key or sends a custom key the trigger does not declare. `trigger_id` is the one `GET /agents/{agent_id}` returns.\n\nAuth & scoping: requires `X-API-Key` header or OAuth Bearer token; the trigger must belong to an agent in the key's account.\n\nRejected with HTTP 400 when the agent references a key no trigger of its branch then declares.", + "operationId": "set_metadata_keys_api_api_agents__agent_id__triggers__trigger_id__metadata_keys_put", + "parameters": [ + { + "in": "path", + "name": "agent_id", + "required": true, + "schema": { + "format": "uuid", + "title": "Agent Id", + "type": "string" + } + }, + { + "in": "path", + "name": "trigger_id", + "required": true, + "schema": { + "format": "uuid", + "title": "Trigger Id", + "type": "string" + } + }, + { + "$ref": "#/components/parameters/X-Account-Id" + }, + { + "$ref": "#/components/parameters/Seclai-Version" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SetMetadataKeysRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MetadataKeysResponse" + } + } + }, + "description": "Successful Response" + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + }, + "description": "Validation Error" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceUnavailableError" + } + } + }, + "description": "A dependency is unavailable. `database_unavailable` is temporary (for example routine maintenance) and carries a `Retry-After` header, after which the request can be retried unchanged. `vector_store_unavailable` means the vector store backing an embeddings operation is not configured; it carries no `Retry-After` because it does not clear without an operator.", + "headers": { + "Retry-After": { + "description": "Seconds to wait before retrying. Sent only with `database_unavailable`.", + "schema": { + "type": "integer" + } + } + } + } + }, + "summary": "Declare the metadata keys a trigger accepts", + "tags": [ + "agents" + ] + } + }, "/agents/{agent_id}/triggers/{trigger_id}/slack-config": { "put": { "description": "Set the Slack connection, form, channels, visibility and conversation settings of an agent's SLACK_COMMAND trigger, which people run from Slack with `/seclai` or the message shortcut. Omitted fields are left unchanged.\n\nAuth & scoping: requires `X-API-Key` header or OAuth Bearer token; the trigger must belong to an agent in the key's account.", @@ -22982,6 +23432,73 @@ ] } }, + "/knowledge_bases/{knowledge_base_id}/metadata-key-stats": { + "get": { + "description": "How often each item-metadata key appears on the knowledge base's content items, for declaring a content trigger's metadata keys. An item is counted once, at its latest version; the total includes items with no metadata. Only keys a content run carries are listed: a null value counts as absent, and reserved keys and the keys the platform sets after the item's own are left out. Each window counts the items whose latest version was created or linked in it.\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token. You can only access knowledge bases belonging to your account.", + "operationId": "get_knowledge_base_metadata_key_stats_api_knowledge_bases__knowledge_base_id__metadata_key_stats_get", + "parameters": [ + { + "in": "path", + "name": "knowledge_base_id", + "required": true, + "schema": { + "title": "Knowledge Base Id", + "type": "string" + } + }, + { + "$ref": "#/components/parameters/X-Account-Id" + }, + { + "$ref": "#/components/parameters/Seclai-Version" + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/KnowledgeBaseMetadataKeyStatsResponse" + } + } + }, + "description": "Successful Response" + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + }, + "description": "Validation Error" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceUnavailableError" + } + } + }, + "description": "A dependency is unavailable. `database_unavailable` is temporary (for example routine maintenance) and carries a `Retry-After` header, after which the request can be retried unchanged. `vector_store_unavailable` means the vector store backing an embeddings operation is not configured; it carries no `Retry-After` because it does not clear without an operator.", + "headers": { + "Retry-After": { + "description": "Seconds to wait before retrying. Sent only with `database_unavailable`.", + "schema": { + "type": "integer" + } + } + } + } + }, + "summary": "Get Knowledge Base Metadata Key Stats", + "tags": [ + "knowledge_bases" + ] + } + }, "/me": { "get": { "description": "Returns the authenticated user's personal account ID and a list of organisations they belong to. Each organisation entry includes the organisation's own id, display name, and account_id. Useful for CLI tooling that needs to let the user pick an org context.", @@ -28897,8 +29414,10 @@ "2026-10-18", "2026-10-19", "2026-10-21", - "2026-10-28" + "2026-10-28", + "2026-11-02", + "2026-11-04" ], - "latest": "2026-10-28" + "latest": "2026-11-04" } } diff --git a/scripts/specfix.py b/scripts/specfix.py new file mode 100644 index 0000000..218f0f6 --- /dev/null +++ b/scripts/specfix.py @@ -0,0 +1,88 @@ +"""Prepare the bundled OpenAPI spec for openapi-python-client. + +Reads ``openapi/seclai.openapi.json`` and writes a copy for ``make generate`` to +read, so the bundled spec itself stays identical to the other SDKs' copies. + +The copy adds back request properties the spec removed but released models +already exposed (``RETAINED_REQUEST_FIELDS``), so the generated model keeps the +attribute and existing callers keep working. Each is described as ignored by +the API. Remove an entry at the next major version. + +Exits non-zero when an entry is stale: its schema, or the schema's +``properties``, is missing, or the spec already declares the property again. +A stale entry must be removed or updated rather than silently skipped. Every +entry is checked first, so on an error none is applied and nothing is written. +""" + +from __future__ import annotations + +import json +import sys +from pathlib import Path +from typing import Any + +# (schema, property, definition). Mirrors `retainedRequestFields` in +# seclai-go's cmd/specfix. +RETAINED_REQUEST_FIELDS: list[tuple[str, str, dict[str, Any]]] = [ + ( + # Released in 1.9.0; the API ignores it since version 2026-11-04. + "SetSlackTriggerConfigApiRequest", + "input", + { + "anyOf": [{"type": "string"}, {"type": "null"}], + "deprecated": True, + "description": ( + "Deprecated: the trigger's former input template. The API " + "ignores it; set `alias` to choose the name people type after " + "`/seclai`." + ), + "title": "Input", + }, + ), +] + + +def retain_removed_request_fields(spec: dict[str, Any]) -> list[str]: + """Add each retained field to its schema; return the errors found. + + Every entry is checked before any is applied, so on an error the spec is + left unchanged. + """ + errors: list[str] = [] + schemas = spec.get("components", {}).get("schemas", {}) + for schema_name, prop, _ in RETAINED_REQUEST_FIELDS: + schema = schemas.get(schema_name) + if not isinstance(schema, dict): + errors.append(f"schema {schema_name!r} not found") + elif not isinstance(schema.get("properties"), dict): + errors.append(f"schema {schema_name!r} has no properties") + elif prop in schema["properties"]: + errors.append( + f"stale entry `{schema_name}.{prop}` in the retained-fields " + "list: the spec declares it again; remove the entry" + ) + if errors: + return errors + for schema_name, prop, definition in RETAINED_REQUEST_FIELDS: + schemas[schema_name]["properties"][prop] = dict(definition) + return errors + + +def main() -> int: + if len(sys.argv) != 3: + print("Usage: python scripts/specfix.py ", file=sys.stderr) + return 2 + src, dst = Path(sys.argv[1]), Path(sys.argv[2]) + spec = json.loads(src.read_text(encoding="utf-8")) + errors = retain_removed_request_fields(spec) + if errors: + for err in errors: + print(f"specfix: {err}", file=sys.stderr) + return 1 + dst.parent.mkdir(parents=True, exist_ok=True) + dst.write_text(json.dumps(spec, indent=2) + "\n", encoding="utf-8") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/seclai/__init__.py b/seclai/__init__.py index 3aab514..0aab9e5 100644 --- a/seclai/__init__.py +++ b/seclai/__init__.py @@ -24,8 +24,11 @@ - :data:`DEFAULT_API_VERSION` / :data:`LATEST_API_VERSION` — the baseline and newest known version - :func:`unwrap_items` — read a version-gated list response in either shape +- :class:`Unset` / :data:`UNSET` — the marker for a response field the API + omitted, e.g. ``isinstance(result.warnings, Unset)`` """ +from ._generated.types import UNSET, Unset from .auth import ( DEFAULT_SSO_CLIENT_ID, DEFAULT_SSO_DOMAIN, @@ -66,4 +69,6 @@ "ApiVersion", "DEFAULT_API_VERSION", "LATEST_API_VERSION", + "UNSET", + "Unset", ] diff --git a/seclai/_generated/api/agent_evaluations/create_evaluation_criteria_api_agents_agent_id_evaluation_criteria_post.py b/seclai/_generated/api/agent_evaluations/create_evaluation_criteria_api_agents_agent_id_evaluation_criteria_post.py index 1295105..70144a9 100644 --- a/seclai/_generated/api/agent_evaluations/create_evaluation_criteria_api_agents_agent_id_evaluation_criteria_post.py +++ b/seclai/_generated/api/agent_evaluations/create_evaluation_criteria_api_agents_agent_id_evaluation_criteria_post.py @@ -94,8 +94,9 @@ def sync_detailed( Create new step evaluation settings for an agent. - The evaluation mode, retry settings, and sample frequency are inherited - from the agent and stored on the criteria row for historical reference. + From Seclai-Version 2026-11-04, `step_id` must name a `display_result` or + `streaming_result` step, the run's published result; another step returns 400. + The evaluation mode and sample frequency are the agent's. Args: agent_id (str): @@ -103,7 +104,8 @@ def sync_detailed( seclai_version (str | Unset): body (CreateEvaluationCriteriaRequest): Request body for creating an evaluation criteria. - The evaluation mode, retry settings, and sample frequency are set at the + step_id names the display_result or streaming_result step to score. The + evaluation mode and sample frequency are set at the agent level, not per-criteria. Raises: @@ -140,8 +142,9 @@ def sync( Create new step evaluation settings for an agent. - The evaluation mode, retry settings, and sample frequency are inherited - from the agent and stored on the criteria row for historical reference. + From Seclai-Version 2026-11-04, `step_id` must name a `display_result` or + `streaming_result` step, the run's published result; another step returns 400. + The evaluation mode and sample frequency are the agent's. Args: agent_id (str): @@ -149,7 +152,8 @@ def sync( seclai_version (str | Unset): body (CreateEvaluationCriteriaRequest): Request body for creating an evaluation criteria. - The evaluation mode, retry settings, and sample frequency are set at the + step_id names the display_result or streaming_result step to score. The + evaluation mode and sample frequency are set at the agent level, not per-criteria. Raises: @@ -183,8 +187,9 @@ async def asyncio_detailed( Create new step evaluation settings for an agent. - The evaluation mode, retry settings, and sample frequency are inherited - from the agent and stored on the criteria row for historical reference. + From Seclai-Version 2026-11-04, `step_id` must name a `display_result` or + `streaming_result` step, the run's published result; another step returns 400. + The evaluation mode and sample frequency are the agent's. Args: agent_id (str): @@ -192,7 +197,8 @@ async def asyncio_detailed( seclai_version (str | Unset): body (CreateEvaluationCriteriaRequest): Request body for creating an evaluation criteria. - The evaluation mode, retry settings, and sample frequency are set at the + step_id names the display_result or streaming_result step to score. The + evaluation mode and sample frequency are set at the agent level, not per-criteria. Raises: @@ -227,8 +233,9 @@ async def asyncio( Create new step evaluation settings for an agent. - The evaluation mode, retry settings, and sample frequency are inherited - from the agent and stored on the criteria row for historical reference. + From Seclai-Version 2026-11-04, `step_id` must name a `display_result` or + `streaming_result` step, the run's published result; another step returns 400. + The evaluation mode and sample frequency are the agent's. Args: agent_id (str): @@ -236,7 +243,8 @@ async def asyncio( seclai_version (str | Unset): body (CreateEvaluationCriteriaRequest): Request body for creating an evaluation criteria. - The evaluation mode, retry settings, and sample frequency are set at the + step_id names the display_result or streaming_result step to score. The + evaluation mode and sample frequency are set at the agent level, not per-criteria. Raises: diff --git a/seclai/_generated/api/agent_evaluations/create_evaluation_result_api_agents_evaluation_criteria_criteria_id_results_post.py b/seclai/_generated/api/agent_evaluations/create_evaluation_result_api_agents_evaluation_criteria_criteria_id_results_post.py index ccbe549..ead2b9b 100644 --- a/seclai/_generated/api/agent_evaluations/create_evaluation_result_api_agents_evaluation_criteria_criteria_id_results_post.py +++ b/seclai/_generated/api/agent_evaluations/create_evaluation_result_api_agents_evaluation_criteria_criteria_id_results_post.py @@ -92,7 +92,8 @@ def sync_detailed( Use this endpoint to push results from external test harnesses, CI/CD pipelines, or custom evaluation logic. Each result is linked to an - agent run and optionally a specific step run. + agent run and optionally a specific step run. From Seclai-Version 2026-11-04 + `retry_triggered: true` returns 400: evaluations never retry a step. Args: criteria_id (str): @@ -136,7 +137,8 @@ def sync( Use this endpoint to push results from external test harnesses, CI/CD pipelines, or custom evaluation logic. Each result is linked to an - agent run and optionally a specific step run. + agent run and optionally a specific step run. From Seclai-Version 2026-11-04 + `retry_triggered: true` returns 400: evaluations never retry a step. Args: criteria_id (str): @@ -175,7 +177,8 @@ async def asyncio_detailed( Use this endpoint to push results from external test harnesses, CI/CD pipelines, or custom evaluation logic. Each result is linked to an - agent run and optionally a specific step run. + agent run and optionally a specific step run. From Seclai-Version 2026-11-04 + `retry_triggered: true` returns 400: evaluations never retry a step. Args: criteria_id (str): @@ -217,7 +220,8 @@ async def asyncio( Use this endpoint to push results from external test harnesses, CI/CD pipelines, or custom evaluation logic. Each result is linked to an - agent run and optionally a specific step run. + agent run and optionally a specific step run. From Seclai-Version 2026-11-04 + `retry_triggered: true` returns 400: evaluations never retry a step. Args: criteria_id (str): diff --git a/seclai/_generated/api/agent_evaluations/get_non_manual_evaluation_summary_api_agents_evaluation_results_non_manual_summary_get.py b/seclai/_generated/api/agent_evaluations/get_non_manual_evaluation_summary_api_agents_evaluation_results_non_manual_summary_get.py index b26f2ea..775793a 100644 --- a/seclai/_generated/api/agent_evaluations/get_non_manual_evaluation_summary_api_agents_evaluation_results_non_manual_summary_get.py +++ b/seclai/_generated/api/agent_evaluations/get_non_manual_evaluation_summary_api_agents_evaluation_results_non_manual_summary_get.py @@ -125,8 +125,7 @@ def sync_detailed( Get an evaluation summary for API key clients. - Returns aggregated pass/fail/flagged counts and pass rates for each evaluation mode (eval_and_retry, - sample_and_flag). + Returns aggregated pass/fail/flagged counts and pass rates for each automatic evaluation mode. With ``2026-10-21`` or later, ``error`` results (the evaluator returned no verdict) are left out of ``failed``, and the rates are over passed and @@ -190,8 +189,7 @@ def sync( Get an evaluation summary for API key clients. - Returns aggregated pass/fail/flagged counts and pass rates for each evaluation mode (eval_and_retry, - sample_and_flag). + Returns aggregated pass/fail/flagged counts and pass rates for each automatic evaluation mode. With ``2026-10-21`` or later, ``error`` results (the evaluator returned no verdict) are left out of ``failed``, and the rates are over passed and @@ -247,8 +245,7 @@ async def asyncio_detailed( Get an evaluation summary for API key clients. - Returns aggregated pass/fail/flagged counts and pass rates for each evaluation mode (eval_and_retry, - sample_and_flag). + Returns aggregated pass/fail/flagged counts and pass rates for each automatic evaluation mode. With ``2026-10-21`` or later, ``error`` results (the evaluator returned no verdict) are left out of ``failed``, and the rates are over passed and @@ -310,8 +307,7 @@ async def asyncio( Get an evaluation summary for API key clients. - Returns aggregated pass/fail/flagged counts and pass rates for each evaluation mode (eval_and_retry, - sample_and_flag). + Returns aggregated pass/fail/flagged counts and pass rates for each automatic evaluation mode. With ``2026-10-21`` or later, ``error`` results (the evaluator returned no verdict) are left out of ``failed``, and the rates are over passed and diff --git a/seclai/_generated/api/agent_evaluations/update_evaluation_criteria_api_agents_evaluation_criteria_criteria_id_patch.py b/seclai/_generated/api/agent_evaluations/update_evaluation_criteria_api_agents_evaluation_criteria_criteria_id_patch.py index 4b4c456..8b976f7 100644 --- a/seclai/_generated/api/agent_evaluations/update_evaluation_criteria_api_agents_evaluation_criteria_criteria_id_patch.py +++ b/seclai/_generated/api/agent_evaluations/update_evaluation_criteria_api_agents_evaluation_criteria_criteria_id_patch.py @@ -96,7 +96,8 @@ def sync_detailed( Accepts a partial update – only the fields included in the request body are modified. Use this to toggle enabled/disabled, change the - evaluation prompt, adjust retries, or rename the criteria. + evaluation prompt, or rename the criteria. From Seclai-Version 2026-11-04 a + changed `step_id` must name a `display_result` or `streaming_result` step. Args: criteria_id (str): @@ -104,7 +105,7 @@ def sync_detailed( seclai_version (str | Unset): body (UpdateEvaluationCriteriaRequest): Request body for updating an evaluation criteria. - Retry settings and sample frequency are set at the agent level. + The evaluation mode and sample frequency are set at the agent level. Raises: errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True. @@ -142,7 +143,8 @@ def sync( Accepts a partial update – only the fields included in the request body are modified. Use this to toggle enabled/disabled, change the - evaluation prompt, adjust retries, or rename the criteria. + evaluation prompt, or rename the criteria. From Seclai-Version 2026-11-04 a + changed `step_id` must name a `display_result` or `streaming_result` step. Args: criteria_id (str): @@ -150,7 +152,7 @@ def sync( seclai_version (str | Unset): body (UpdateEvaluationCriteriaRequest): Request body for updating an evaluation criteria. - Retry settings and sample frequency are set at the agent level. + The evaluation mode and sample frequency are set at the agent level. Raises: errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True. @@ -185,7 +187,8 @@ async def asyncio_detailed( Accepts a partial update – only the fields included in the request body are modified. Use this to toggle enabled/disabled, change the - evaluation prompt, adjust retries, or rename the criteria. + evaluation prompt, or rename the criteria. From Seclai-Version 2026-11-04 a + changed `step_id` must name a `display_result` or `streaming_result` step. Args: criteria_id (str): @@ -193,7 +196,7 @@ async def asyncio_detailed( seclai_version (str | Unset): body (UpdateEvaluationCriteriaRequest): Request body for updating an evaluation criteria. - Retry settings and sample frequency are set at the agent level. + The evaluation mode and sample frequency are set at the agent level. Raises: errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True. @@ -229,7 +232,8 @@ async def asyncio( Accepts a partial update – only the fields included in the request body are modified. Use this to toggle enabled/disabled, change the - evaluation prompt, adjust retries, or rename the criteria. + evaluation prompt, or rename the criteria. From Seclai-Version 2026-11-04 a + changed `step_id` must name a `display_result` or `streaming_result` step. Args: criteria_id (str): @@ -237,7 +241,7 @@ async def asyncio( seclai_version (str | Unset): body (UpdateEvaluationCriteriaRequest): Request body for updating an evaluation criteria. - Retry settings and sample frequency are set at the agent level. + The evaluation mode and sample frequency are set at the agent level. Raises: errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True. diff --git a/seclai/_generated/api/agents/export_agent_api_agents_agent_id_export_get.py b/seclai/_generated/api/agents/export_agent_api_agents_agent_id_export_get.py index 546fbf9..cb20b2d 100644 --- a/seclai/_generated/api/agents/export_agent_api_agents_agent_id_export_get.py +++ b/seclai/_generated/api/agents/export_agent_api_agents_agent_id_export_get.py @@ -97,7 +97,7 @@ def sync_detailed( every referenced external entity UUID to its human-readable name. Response shape: - - `export_version`: schema version (currently `\"5\"`) + - `export_version`: schema version (currently `\"6\"`) - `exported_at`: ISO-8601 timestamp - `agent`: name, description, schema_version, definition, timestamps - `trigger`: trigger type, input template, schedules @@ -158,7 +158,7 @@ def sync( every referenced external entity UUID to its human-readable name. Response shape: - - `export_version`: schema version (currently `\"5\"`) + - `export_version`: schema version (currently `\"6\"`) - `exported_at`: ISO-8601 timestamp - `agent`: name, description, schema_version, definition, timestamps - `trigger`: trigger type, input template, schedules @@ -214,7 +214,7 @@ async def asyncio_detailed( every referenced external entity UUID to its human-readable name. Response shape: - - `export_version`: schema version (currently `\"5\"`) + - `export_version`: schema version (currently `\"6\"`) - `exported_at`: ISO-8601 timestamp - `agent`: name, description, schema_version, definition, timestamps - `trigger`: trigger type, input template, schedules @@ -273,7 +273,7 @@ async def asyncio( every referenced external entity UUID to its human-readable name. Response shape: - - `export_version`: schema version (currently `\"5\"`) + - `export_version`: schema version (currently `\"6\"`) - `exported_at`: ISO-8601 timestamp - `agent`: name, description, schema_version, definition, timestamps - `trigger`: trigger type, input template, schedules diff --git a/seclai/_generated/api/agents/get_agent_definition_api_agents_agent_id_definition_get.py b/seclai/_generated/api/agents/get_agent_definition_api_agents_agent_id_definition_get.py index 6eba31f..3af7746 100644 --- a/seclai/_generated/api/agents/get_agent_definition_api_agents_agent_id_definition_get.py +++ b/seclai/_generated/api/agents/get_agent_definition_api_agents_agent_id_definition_get.py @@ -79,7 +79,7 @@ def sync_detailed( x_account_id: UUID | Unset = UNSET, seclai_version: str | Unset = UNSET, ) -> Response[AgentDefinitionResponse | HTTPValidationError | ServiceUnavailableError]: - r"""Get agent definition + """Get agent definition Fetch the current agent definition from the main branch. @@ -90,9 +90,9 @@ def sync_detailed( - `prompt_call`: Call an LLM with a prompt template - `retrieval`: Search a knowledge base - `regex_replace`: Reshape text via ordered regex find/replace rules - - `gate`: Evaluate conditions, stop or continue child execution - - `retry`: Re-execute from a target ancestor step (for quality-control loops; pair with a `gate` - step for conditional retrying. Fields: `target_step_id` (ancestor step ID), `max_retries` (1–10)) + - `repeat_until`: Run a body (`body[]`) again until its `conditions` match the iteration's verdict + or `max_iterations` (1–1000, default 3) is reached. Fields: `conditions`, `match`, optional + `verdict_template`, `output` (`last` or `all`), `fail_when_max_reached` - `evaluate_step`: Score a selected previous step output and emit JSON with `score`, `passed`, and `pass_threshold` (fields: `target_step_id`, `evaluation_prompt`, `pass_threshold`, optional `evaluation_tier`, optional `expectation_config`) @@ -118,21 +118,18 @@ def sync_detailed( optional) - `streaming_result`: Stream LLM tokens in real-time via SSE (must be a direct child of `prompt_call`; requires `dynamic_input` or `template_input` trigger; `priority: true` enables real- - time streaming). To stream **and** return a schema-validated payload, add a sibling branch - `extract_content` (`expected_format: \"json\"` + `json_schema`) → `display_result` under the same - `prompt_call` — a `display_result` takes precedence over the stream regardless of which finishes - first, so its validated output becomes the run's result while the tokens act as a progress channel + time streaming). An agent has at most one `streaming_result` or `display_result`; saving refuses a + second - `display_result`: Show output to the user - `join`: Merge parallel branches - `merge`: Combine multiple inputs into a single templated output - `text`: Static text literal - `for_each`: Iterate a body over a list of items (body lives in `body[]`) - - `if_else`: Conditional dispatch. Evaluates `conditions` (same shape as `gate`) and runs - `then_steps` on match, otherwise the optional `else_steps`. The chosen branch's output flows to the - if_else step's own `child_steps` (post-branch continuation chain). **`display_result` and - `streaming_result` are not allowed inside `then_steps` / `else_steps`** — end each branch with a - content-producing step (e.g. `text`, `prompt_call`) and place the single `display_result` in - `child_steps`. + - `if_else`: Conditional dispatch. Evaluates `conditions` and runs `then_steps` on match, otherwise + the optional `else_steps`. The chosen branch's output flows to the if_else step's own `child_steps` + (post-branch continuation chain). **`display_result` and `streaming_result` are not allowed inside + `then_steps` / `else_steps`** — end each branch with a content-producing step (e.g. `text`, + `prompt_call`) and place the single `display_result` in `child_steps`. - `switch`: Single-discriminator dispatch. Renders `discriminator` (default `{{input}}`) and routes to the first matching `cases[]` entry (equality by default; pass a list in `match` for `$in` semantics) or to `else_steps` when nothing matches. The chosen case's output flows to the switch @@ -177,7 +174,7 @@ def sync( x_account_id: UUID | Unset = UNSET, seclai_version: str | Unset = UNSET, ) -> AgentDefinitionResponse | HTTPValidationError | ServiceUnavailableError | None: - r"""Get agent definition + """Get agent definition Fetch the current agent definition from the main branch. @@ -188,9 +185,9 @@ def sync( - `prompt_call`: Call an LLM with a prompt template - `retrieval`: Search a knowledge base - `regex_replace`: Reshape text via ordered regex find/replace rules - - `gate`: Evaluate conditions, stop or continue child execution - - `retry`: Re-execute from a target ancestor step (for quality-control loops; pair with a `gate` - step for conditional retrying. Fields: `target_step_id` (ancestor step ID), `max_retries` (1–10)) + - `repeat_until`: Run a body (`body[]`) again until its `conditions` match the iteration's verdict + or `max_iterations` (1–1000, default 3) is reached. Fields: `conditions`, `match`, optional + `verdict_template`, `output` (`last` or `all`), `fail_when_max_reached` - `evaluate_step`: Score a selected previous step output and emit JSON with `score`, `passed`, and `pass_threshold` (fields: `target_step_id`, `evaluation_prompt`, `pass_threshold`, optional `evaluation_tier`, optional `expectation_config`) @@ -216,21 +213,18 @@ def sync( optional) - `streaming_result`: Stream LLM tokens in real-time via SSE (must be a direct child of `prompt_call`; requires `dynamic_input` or `template_input` trigger; `priority: true` enables real- - time streaming). To stream **and** return a schema-validated payload, add a sibling branch - `extract_content` (`expected_format: \"json\"` + `json_schema`) → `display_result` under the same - `prompt_call` — a `display_result` takes precedence over the stream regardless of which finishes - first, so its validated output becomes the run's result while the tokens act as a progress channel + time streaming). An agent has at most one `streaming_result` or `display_result`; saving refuses a + second - `display_result`: Show output to the user - `join`: Merge parallel branches - `merge`: Combine multiple inputs into a single templated output - `text`: Static text literal - `for_each`: Iterate a body over a list of items (body lives in `body[]`) - - `if_else`: Conditional dispatch. Evaluates `conditions` (same shape as `gate`) and runs - `then_steps` on match, otherwise the optional `else_steps`. The chosen branch's output flows to the - if_else step's own `child_steps` (post-branch continuation chain). **`display_result` and - `streaming_result` are not allowed inside `then_steps` / `else_steps`** — end each branch with a - content-producing step (e.g. `text`, `prompt_call`) and place the single `display_result` in - `child_steps`. + - `if_else`: Conditional dispatch. Evaluates `conditions` and runs `then_steps` on match, otherwise + the optional `else_steps`. The chosen branch's output flows to the if_else step's own `child_steps` + (post-branch continuation chain). **`display_result` and `streaming_result` are not allowed inside + `then_steps` / `else_steps`** — end each branch with a content-producing step (e.g. `text`, + `prompt_call`) and place the single `display_result` in `child_steps`. - `switch`: Single-discriminator dispatch. Renders `discriminator` (default `{{input}}`) and routes to the first matching `cases[]` entry (equality by default; pass a list in `match` for `$in` semantics) or to `else_steps` when nothing matches. The chosen case's output flows to the switch @@ -270,7 +264,7 @@ async def asyncio_detailed( x_account_id: UUID | Unset = UNSET, seclai_version: str | Unset = UNSET, ) -> Response[AgentDefinitionResponse | HTTPValidationError | ServiceUnavailableError]: - r"""Get agent definition + """Get agent definition Fetch the current agent definition from the main branch. @@ -281,9 +275,9 @@ async def asyncio_detailed( - `prompt_call`: Call an LLM with a prompt template - `retrieval`: Search a knowledge base - `regex_replace`: Reshape text via ordered regex find/replace rules - - `gate`: Evaluate conditions, stop or continue child execution - - `retry`: Re-execute from a target ancestor step (for quality-control loops; pair with a `gate` - step for conditional retrying. Fields: `target_step_id` (ancestor step ID), `max_retries` (1–10)) + - `repeat_until`: Run a body (`body[]`) again until its `conditions` match the iteration's verdict + or `max_iterations` (1–1000, default 3) is reached. Fields: `conditions`, `match`, optional + `verdict_template`, `output` (`last` or `all`), `fail_when_max_reached` - `evaluate_step`: Score a selected previous step output and emit JSON with `score`, `passed`, and `pass_threshold` (fields: `target_step_id`, `evaluation_prompt`, `pass_threshold`, optional `evaluation_tier`, optional `expectation_config`) @@ -309,21 +303,18 @@ async def asyncio_detailed( optional) - `streaming_result`: Stream LLM tokens in real-time via SSE (must be a direct child of `prompt_call`; requires `dynamic_input` or `template_input` trigger; `priority: true` enables real- - time streaming). To stream **and** return a schema-validated payload, add a sibling branch - `extract_content` (`expected_format: \"json\"` + `json_schema`) → `display_result` under the same - `prompt_call` — a `display_result` takes precedence over the stream regardless of which finishes - first, so its validated output becomes the run's result while the tokens act as a progress channel + time streaming). An agent has at most one `streaming_result` or `display_result`; saving refuses a + second - `display_result`: Show output to the user - `join`: Merge parallel branches - `merge`: Combine multiple inputs into a single templated output - `text`: Static text literal - `for_each`: Iterate a body over a list of items (body lives in `body[]`) - - `if_else`: Conditional dispatch. Evaluates `conditions` (same shape as `gate`) and runs - `then_steps` on match, otherwise the optional `else_steps`. The chosen branch's output flows to the - if_else step's own `child_steps` (post-branch continuation chain). **`display_result` and - `streaming_result` are not allowed inside `then_steps` / `else_steps`** — end each branch with a - content-producing step (e.g. `text`, `prompt_call`) and place the single `display_result` in - `child_steps`. + - `if_else`: Conditional dispatch. Evaluates `conditions` and runs `then_steps` on match, otherwise + the optional `else_steps`. The chosen branch's output flows to the if_else step's own `child_steps` + (post-branch continuation chain). **`display_result` and `streaming_result` are not allowed inside + `then_steps` / `else_steps`** — end each branch with a content-producing step (e.g. `text`, + `prompt_call`) and place the single `display_result` in `child_steps`. - `switch`: Single-discriminator dispatch. Renders `discriminator` (default `{{input}}`) and routes to the first matching `cases[]` entry (equality by default; pass a list in `match` for `$in` semantics) or to `else_steps` when nothing matches. The chosen case's output flows to the switch @@ -366,7 +357,7 @@ async def asyncio( x_account_id: UUID | Unset = UNSET, seclai_version: str | Unset = UNSET, ) -> AgentDefinitionResponse | HTTPValidationError | ServiceUnavailableError | None: - r"""Get agent definition + """Get agent definition Fetch the current agent definition from the main branch. @@ -377,9 +368,9 @@ async def asyncio( - `prompt_call`: Call an LLM with a prompt template - `retrieval`: Search a knowledge base - `regex_replace`: Reshape text via ordered regex find/replace rules - - `gate`: Evaluate conditions, stop or continue child execution - - `retry`: Re-execute from a target ancestor step (for quality-control loops; pair with a `gate` - step for conditional retrying. Fields: `target_step_id` (ancestor step ID), `max_retries` (1–10)) + - `repeat_until`: Run a body (`body[]`) again until its `conditions` match the iteration's verdict + or `max_iterations` (1–1000, default 3) is reached. Fields: `conditions`, `match`, optional + `verdict_template`, `output` (`last` or `all`), `fail_when_max_reached` - `evaluate_step`: Score a selected previous step output and emit JSON with `score`, `passed`, and `pass_threshold` (fields: `target_step_id`, `evaluation_prompt`, `pass_threshold`, optional `evaluation_tier`, optional `expectation_config`) @@ -405,21 +396,18 @@ async def asyncio( optional) - `streaming_result`: Stream LLM tokens in real-time via SSE (must be a direct child of `prompt_call`; requires `dynamic_input` or `template_input` trigger; `priority: true` enables real- - time streaming). To stream **and** return a schema-validated payload, add a sibling branch - `extract_content` (`expected_format: \"json\"` + `json_schema`) → `display_result` under the same - `prompt_call` — a `display_result` takes precedence over the stream regardless of which finishes - first, so its validated output becomes the run's result while the tokens act as a progress channel + time streaming). An agent has at most one `streaming_result` or `display_result`; saving refuses a + second - `display_result`: Show output to the user - `join`: Merge parallel branches - `merge`: Combine multiple inputs into a single templated output - `text`: Static text literal - `for_each`: Iterate a body over a list of items (body lives in `body[]`) - - `if_else`: Conditional dispatch. Evaluates `conditions` (same shape as `gate`) and runs - `then_steps` on match, otherwise the optional `else_steps`. The chosen branch's output flows to the - if_else step's own `child_steps` (post-branch continuation chain). **`display_result` and - `streaming_result` are not allowed inside `then_steps` / `else_steps`** — end each branch with a - content-producing step (e.g. `text`, `prompt_call`) and place the single `display_result` in - `child_steps`. + - `if_else`: Conditional dispatch. Evaluates `conditions` and runs `then_steps` on match, otherwise + the optional `else_steps`. The chosen branch's output flows to the if_else step's own `child_steps` + (post-branch continuation chain). **`display_result` and `streaming_result` are not allowed inside + `then_steps` / `else_steps`** — end each branch with a content-producing step (e.g. `text`, + `prompt_call`) and place the single `display_result` in `child_steps`. - `switch`: Single-discriminator dispatch. Renders `discriminator` (default `{{input}}`) and routes to the first matching `cases[]` entry (equality by default; pass a list in `match` for `$in` semantics) or to `else_steps` when nothing matches. The chosen case's output flows to the switch diff --git a/seclai/_generated/api/agents/get_metadata_keys_api_api_agents_agent_id_triggers_trigger_id_metadata_keys_get.py b/seclai/_generated/api/agents/get_metadata_keys_api_api_agents_agent_id_triggers_trigger_id_metadata_keys_get.py new file mode 100644 index 0000000..d553732 --- /dev/null +++ b/seclai/_generated/api/agents/get_metadata_keys_api_api_agents_agent_id_triggers_trigger_id_metadata_keys_get.py @@ -0,0 +1,252 @@ +from http import HTTPStatus +from typing import Any +from urllib.parse import quote +from uuid import UUID + +import httpx + +from ... import errors +from ...client import AuthenticatedClient, Client +from ...models.http_validation_error import HTTPValidationError +from ...models.metadata_keys_response import MetadataKeysResponse +from ...models.service_unavailable_error import ServiceUnavailableError +from ...types import UNSET, Response, Unset + + +def _get_kwargs( + agent_id: UUID, + trigger_id: UUID, + *, + x_account_id: UUID | Unset = UNSET, + seclai_version: str | Unset = UNSET, +) -> dict[str, Any]: + headers: dict[str, Any] = {} + if not isinstance(x_account_id, Unset): + headers["X-Account-Id"] = x_account_id + + if not isinstance(seclai_version, Unset): + headers["Seclai-Version"] = seclai_version + + _kwargs: dict[str, Any] = { + "method": "get", + "url": "/agents/{agent_id}/triggers/{trigger_id}/metadata-keys".format( + agent_id=quote(str(agent_id), safe=""), + trigger_id=quote(str(trigger_id), safe=""), + ), + } + + _kwargs["headers"] = headers + return _kwargs + + +def _parse_response( + *, client: AuthenticatedClient | Client, response: httpx.Response +) -> HTTPValidationError | MetadataKeysResponse | ServiceUnavailableError | None: + if response.status_code == 200: + response_200 = MetadataKeysResponse.from_dict(response.json()) + + return response_200 + + if response.status_code == 422: + response_422 = HTTPValidationError.from_dict(response.json()) + + return response_422 + + if response.status_code == 503: + response_503 = ServiceUnavailableError.from_dict(response.json()) + + return response_503 + + if client.raise_on_unexpected_status: + raise errors.UnexpectedStatus(response.status_code, response.content) + else: + return None + + +def _build_response( + *, client: AuthenticatedClient | Client, response: httpx.Response +) -> Response[HTTPValidationError | MetadataKeysResponse | ServiceUnavailableError]: + return Response( + status_code=HTTPStatus(response.status_code), + content=response.content, + headers=response.headers, + parsed=_parse_response(client=client, response=response), + ) + + +def sync_detailed( + agent_id: UUID, + trigger_id: UUID, + *, + client: AuthenticatedClient | Client, + x_account_id: UUID | Unset = UNSET, + seclai_version: str | Unset = UNSET, +) -> Response[HTTPValidationError | MetadataKeysResponse | ServiceUnavailableError]: + """Get the metadata keys a trigger declares + + A trigger declares the run metadata keys its agent's steps may reference, each `required` or + optional. `system` and `source` keys are written by the platform and are never required; `custom` + keys are sent by the caller. A run you start is refused with HTTP 400 when it lacks a required key + or sends a custom key the trigger does not declare. `trigger_id` is the one `GET /agents/{agent_id}` + returns. + + Auth & scoping: requires `X-API-Key` header or OAuth Bearer token; the trigger must belong to an + agent in the key's account. + + Args: + agent_id (UUID): + trigger_id (UUID): + x_account_id (UUID | Unset): + seclai_version (str | Unset): + + Raises: + errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True. + httpx.TimeoutException: If the request takes longer than Client.timeout. + + Returns: + Response[HTTPValidationError | MetadataKeysResponse | ServiceUnavailableError] + """ + + kwargs = _get_kwargs( + agent_id=agent_id, + trigger_id=trigger_id, + x_account_id=x_account_id, + seclai_version=seclai_version, + ) + + response = client.get_httpx_client().request( + **kwargs, + ) + + return _build_response(client=client, response=response) + + +def sync( + agent_id: UUID, + trigger_id: UUID, + *, + client: AuthenticatedClient | Client, + x_account_id: UUID | Unset = UNSET, + seclai_version: str | Unset = UNSET, +) -> HTTPValidationError | MetadataKeysResponse | ServiceUnavailableError | None: + """Get the metadata keys a trigger declares + + A trigger declares the run metadata keys its agent's steps may reference, each `required` or + optional. `system` and `source` keys are written by the platform and are never required; `custom` + keys are sent by the caller. A run you start is refused with HTTP 400 when it lacks a required key + or sends a custom key the trigger does not declare. `trigger_id` is the one `GET /agents/{agent_id}` + returns. + + Auth & scoping: requires `X-API-Key` header or OAuth Bearer token; the trigger must belong to an + agent in the key's account. + + Args: + agent_id (UUID): + trigger_id (UUID): + x_account_id (UUID | Unset): + seclai_version (str | Unset): + + Raises: + errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True. + httpx.TimeoutException: If the request takes longer than Client.timeout. + + Returns: + HTTPValidationError | MetadataKeysResponse | ServiceUnavailableError + """ + + return sync_detailed( + agent_id=agent_id, + trigger_id=trigger_id, + client=client, + x_account_id=x_account_id, + seclai_version=seclai_version, + ).parsed + + +async def asyncio_detailed( + agent_id: UUID, + trigger_id: UUID, + *, + client: AuthenticatedClient | Client, + x_account_id: UUID | Unset = UNSET, + seclai_version: str | Unset = UNSET, +) -> Response[HTTPValidationError | MetadataKeysResponse | ServiceUnavailableError]: + """Get the metadata keys a trigger declares + + A trigger declares the run metadata keys its agent's steps may reference, each `required` or + optional. `system` and `source` keys are written by the platform and are never required; `custom` + keys are sent by the caller. A run you start is refused with HTTP 400 when it lacks a required key + or sends a custom key the trigger does not declare. `trigger_id` is the one `GET /agents/{agent_id}` + returns. + + Auth & scoping: requires `X-API-Key` header or OAuth Bearer token; the trigger must belong to an + agent in the key's account. + + Args: + agent_id (UUID): + trigger_id (UUID): + x_account_id (UUID | Unset): + seclai_version (str | Unset): + + Raises: + errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True. + httpx.TimeoutException: If the request takes longer than Client.timeout. + + Returns: + Response[HTTPValidationError | MetadataKeysResponse | ServiceUnavailableError] + """ + + kwargs = _get_kwargs( + agent_id=agent_id, + trigger_id=trigger_id, + x_account_id=x_account_id, + seclai_version=seclai_version, + ) + + response = await client.get_async_httpx_client().request(**kwargs) + + return _build_response(client=client, response=response) + + +async def asyncio( + agent_id: UUID, + trigger_id: UUID, + *, + client: AuthenticatedClient | Client, + x_account_id: UUID | Unset = UNSET, + seclai_version: str | Unset = UNSET, +) -> HTTPValidationError | MetadataKeysResponse | ServiceUnavailableError | None: + """Get the metadata keys a trigger declares + + A trigger declares the run metadata keys its agent's steps may reference, each `required` or + optional. `system` and `source` keys are written by the platform and are never required; `custom` + keys are sent by the caller. A run you start is refused with HTTP 400 when it lacks a required key + or sends a custom key the trigger does not declare. `trigger_id` is the one `GET /agents/{agent_id}` + returns. + + Auth & scoping: requires `X-API-Key` header or OAuth Bearer token; the trigger must belong to an + agent in the key's account. + + Args: + agent_id (UUID): + trigger_id (UUID): + x_account_id (UUID | Unset): + seclai_version (str | Unset): + + Raises: + errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True. + httpx.TimeoutException: If the request takes longer than Client.timeout. + + Returns: + HTTPValidationError | MetadataKeysResponse | ServiceUnavailableError + """ + + return ( + await asyncio_detailed( + agent_id=agent_id, + trigger_id=trigger_id, + client=client, + x_account_id=x_account_id, + seclai_version=seclai_version, + ) + ).parsed diff --git a/seclai/_generated/api/agents/run_agent_api_agents_agent_id_runs_post.py b/seclai/_generated/api/agents/run_agent_api_agents_agent_id_runs_post.py index 035caac..5f14051 100644 --- a/seclai/_generated/api/agents/run_agent_api_agents_agent_id_runs_post.py +++ b/seclai/_generated/api/agents/run_agent_api_agents_agent_id_runs_post.py @@ -129,10 +129,14 @@ def sync_detailed( - `priority`: set true for latency-sensitive, user-facing work. For agents with a `streaming_result` step, set `priority=true` to enable real-time token streaming; otherwise the run still proceeds, but without live token streaming. - - `metadata`: a JSON object that becomes available to agent steps for string substitution. + - `metadata`: a JSON object for string substitution. Each key must be one the trigger declares (`GET + /agents/{agent_id}/triggers/{trigger_id}/metadata-keys`); a run that sends another custom key, or + lacks a required one, is refused with HTTP 400. After starting: - - Poll `GET /agents/runs/{run_id}` until `status` is `completed` or `failed`. + - Poll `GET /agents/runs/{run_id}` until `result_reported_at` is set (the run's answer is in + `output`) or `status` is `failed`; poll on until `status` is `completed` or `failed` if you need to + know that every step finished. - Use `include_step_outputs=true` to include per-step outputs, timing, and credits. Auth & scoping: @@ -202,10 +206,14 @@ def sync( - `priority`: set true for latency-sensitive, user-facing work. For agents with a `streaming_result` step, set `priority=true` to enable real-time token streaming; otherwise the run still proceeds, but without live token streaming. - - `metadata`: a JSON object that becomes available to agent steps for string substitution. + - `metadata`: a JSON object for string substitution. Each key must be one the trigger declares (`GET + /agents/{agent_id}/triggers/{trigger_id}/metadata-keys`); a run that sends another custom key, or + lacks a required one, is refused with HTTP 400. After starting: - - Poll `GET /agents/runs/{run_id}` until `status` is `completed` or `failed`. + - Poll `GET /agents/runs/{run_id}` until `result_reported_at` is set (the run's answer is in + `output`) or `status` is `failed`; poll on until `status` is `completed` or `failed` if you need to + know that every step finished. - Use `include_step_outputs=true` to include per-step outputs, timing, and credits. Auth & scoping: @@ -269,10 +277,14 @@ async def asyncio_detailed( - `priority`: set true for latency-sensitive, user-facing work. For agents with a `streaming_result` step, set `priority=true` to enable real-time token streaming; otherwise the run still proceeds, but without live token streaming. - - `metadata`: a JSON object that becomes available to agent steps for string substitution. + - `metadata`: a JSON object for string substitution. Each key must be one the trigger declares (`GET + /agents/{agent_id}/triggers/{trigger_id}/metadata-keys`); a run that sends another custom key, or + lacks a required one, is refused with HTTP 400. After starting: - - Poll `GET /agents/runs/{run_id}` until `status` is `completed` or `failed`. + - Poll `GET /agents/runs/{run_id}` until `result_reported_at` is set (the run's answer is in + `output`) or `status` is `failed`; poll on until `status` is `completed` or `failed` if you need to + know that every step finished. - Use `include_step_outputs=true` to include per-step outputs, timing, and credits. Auth & scoping: @@ -340,10 +352,14 @@ async def asyncio( - `priority`: set true for latency-sensitive, user-facing work. For agents with a `streaming_result` step, set `priority=true` to enable real-time token streaming; otherwise the run still proceeds, but without live token streaming. - - `metadata`: a JSON object that becomes available to agent steps for string substitution. + - `metadata`: a JSON object for string substitution. Each key must be one the trigger declares (`GET + /agents/{agent_id}/triggers/{trigger_id}/metadata-keys`); a run that sends another custom key, or + lacks a required one, is refused with HTTP 400. After starting: - - Poll `GET /agents/runs/{run_id}` until `status` is `completed` or `failed`. + - Poll `GET /agents/runs/{run_id}` until `result_reported_at` is set (the run's answer is in + `output`) or `status` is `failed`; poll on until `status` is `completed` or `failed` if you need to + know that every step finished. - Use `include_step_outputs=true` to include per-step outputs, timing, and credits. Auth & scoping: diff --git a/seclai/_generated/api/agents/run_streaming_agent_api_agents_agent_id_runs_stream_post.py b/seclai/_generated/api/agents/run_streaming_agent_api_agents_agent_id_runs_stream_post.py index 4935f05..06e8be7 100644 --- a/seclai/_generated/api/agents/run_streaming_agent_api_agents_agent_id_runs_stream_post.py +++ b/seclai/_generated/api/agents/run_streaming_agent_api_agents_agent_id_runs_stream_post.py @@ -114,6 +114,8 @@ def sync_detailed( - With `include_reasoning=true`, `stream_reasoning` events (with a `text` field) carry the model's reasoning while it thinks, when the `streaming_result` step's author enabled `show_reasoning`. Reasoning is never part of `output`. + - A `result` event contains the snapshot once the run has reported its result (`result_reported_at` + is set and `output` is the answer). - The final `done` event contains the terminal snapshot (including `output` and `credits` when available). @@ -127,12 +129,9 @@ def sync_detailed( - Keep the connection open and handle keepalive comments. - On `timeout` or `error`, the payload includes `run_id` so clients can resume by polling `GET /agents/runs/{run_id}`. - - `stream_token` events carry the model's raw output. When the agent pairs `streaming_result` with a - sibling `extract_content`/`display_result` branch, that branch's `display_result` takes precedence - over the stream, so the `done` snapshot's `output` is the validated payload and the tokens are a - progress channel — render tokens live, but read the result from `done`. Check `done.status` first: - the streamed text is already the run's output when the stream ends, so a run that FAILED its - validation step still carries that raw text in `output`. + - `stream_token` events carry the model's raw output: render them live, but take the answer from the + `result` event. `done.status` says whether the whole run succeeded, which can still fail after its + result. Auth & scoping: - Requires `X-API-Key` header or OAuth Bearer token. All resources are scoped to the caller's @@ -194,6 +193,8 @@ def sync( - With `include_reasoning=true`, `stream_reasoning` events (with a `text` field) carry the model's reasoning while it thinks, when the `streaming_result` step's author enabled `show_reasoning`. Reasoning is never part of `output`. + - A `result` event contains the snapshot once the run has reported its result (`result_reported_at` + is set and `output` is the answer). - The final `done` event contains the terminal snapshot (including `output` and `credits` when available). @@ -207,12 +208,9 @@ def sync( - Keep the connection open and handle keepalive comments. - On `timeout` or `error`, the payload includes `run_id` so clients can resume by polling `GET /agents/runs/{run_id}`. - - `stream_token` events carry the model's raw output. When the agent pairs `streaming_result` with a - sibling `extract_content`/`display_result` branch, that branch's `display_result` takes precedence - over the stream, so the `done` snapshot's `output` is the validated payload and the tokens are a - progress channel — render tokens live, but read the result from `done`. Check `done.status` first: - the streamed text is already the run's output when the stream ends, so a run that FAILED its - validation step still carries that raw text in `output`. + - `stream_token` events carry the model's raw output: render them live, but take the answer from the + `result` event. `done.status` says whether the whole run succeeded, which can still fail after its + result. Auth & scoping: - Requires `X-API-Key` header or OAuth Bearer token. All resources are scoped to the caller's @@ -265,6 +263,8 @@ async def asyncio_detailed( - With `include_reasoning=true`, `stream_reasoning` events (with a `text` field) carry the model's reasoning while it thinks, when the `streaming_result` step's author enabled `show_reasoning`. Reasoning is never part of `output`. + - A `result` event contains the snapshot once the run has reported its result (`result_reported_at` + is set and `output` is the answer). - The final `done` event contains the terminal snapshot (including `output` and `credits` when available). @@ -278,12 +278,9 @@ async def asyncio_detailed( - Keep the connection open and handle keepalive comments. - On `timeout` or `error`, the payload includes `run_id` so clients can resume by polling `GET /agents/runs/{run_id}`. - - `stream_token` events carry the model's raw output. When the agent pairs `streaming_result` with a - sibling `extract_content`/`display_result` branch, that branch's `display_result` takes precedence - over the stream, so the `done` snapshot's `output` is the validated payload and the tokens are a - progress channel — render tokens live, but read the result from `done`. Check `done.status` first: - the streamed text is already the run's output when the stream ends, so a run that FAILED its - validation step still carries that raw text in `output`. + - `stream_token` events carry the model's raw output: render them live, but take the answer from the + `result` event. `done.status` says whether the whole run succeeded, which can still fail after its + result. Auth & scoping: - Requires `X-API-Key` header or OAuth Bearer token. All resources are scoped to the caller's @@ -343,6 +340,8 @@ async def asyncio( - With `include_reasoning=true`, `stream_reasoning` events (with a `text` field) carry the model's reasoning while it thinks, when the `streaming_result` step's author enabled `show_reasoning`. Reasoning is never part of `output`. + - A `result` event contains the snapshot once the run has reported its result (`result_reported_at` + is set and `output` is the answer). - The final `done` event contains the terminal snapshot (including `output` and `credits` when available). @@ -356,12 +355,9 @@ async def asyncio( - Keep the connection open and handle keepalive comments. - On `timeout` or `error`, the payload includes `run_id` so clients can resume by polling `GET /agents/runs/{run_id}`. - - `stream_token` events carry the model's raw output. When the agent pairs `streaming_result` with a - sibling `extract_content`/`display_result` branch, that branch's `display_result` takes precedence - over the stream, so the `done` snapshot's `output` is the validated payload and the tokens are a - progress channel — render tokens live, but read the result from `done`. Check `done.status` first: - the streamed text is already the run's output when the stream ends, so a run that FAILED its - validation step still carries that raw text in `output`. + - `stream_token` events carry the model's raw output: render them live, but take the answer from the + `result` event. `done.status` says whether the whole run succeeded, which can still fail after its + result. Auth & scoping: - Requires `X-API-Key` header or OAuth Bearer token. All resources are scoped to the caller's diff --git a/seclai/_generated/api/agents/set_metadata_keys_api_api_agents_agent_id_triggers_trigger_id_metadata_keys_put.py b/seclai/_generated/api/agents/set_metadata_keys_api_api_agents_agent_id_triggers_trigger_id_metadata_keys_put.py new file mode 100644 index 0000000..7145221 --- /dev/null +++ b/seclai/_generated/api/agents/set_metadata_keys_api_api_agents_agent_id_triggers_trigger_id_metadata_keys_put.py @@ -0,0 +1,278 @@ +from http import HTTPStatus +from typing import Any +from urllib.parse import quote +from uuid import UUID + +import httpx + +from ... import errors +from ...client import AuthenticatedClient, Client +from ...models.http_validation_error import HTTPValidationError +from ...models.metadata_keys_response import MetadataKeysResponse +from ...models.service_unavailable_error import ServiceUnavailableError +from ...models.set_metadata_keys_request import SetMetadataKeysRequest +from ...types import UNSET, Response, Unset + + +def _get_kwargs( + agent_id: UUID, + trigger_id: UUID, + *, + body: SetMetadataKeysRequest, + x_account_id: UUID | Unset = UNSET, + seclai_version: str | Unset = UNSET, +) -> dict[str, Any]: + headers: dict[str, Any] = {} + if not isinstance(x_account_id, Unset): + headers["X-Account-Id"] = x_account_id + + if not isinstance(seclai_version, Unset): + headers["Seclai-Version"] = seclai_version + + _kwargs: dict[str, Any] = { + "method": "put", + "url": "/agents/{agent_id}/triggers/{trigger_id}/metadata-keys".format( + agent_id=quote(str(agent_id), safe=""), + trigger_id=quote(str(trigger_id), safe=""), + ), + } + + _kwargs["json"] = body.to_dict() + + headers["Content-Type"] = "application/json" + + _kwargs["headers"] = headers + return _kwargs + + +def _parse_response( + *, client: AuthenticatedClient | Client, response: httpx.Response +) -> HTTPValidationError | MetadataKeysResponse | ServiceUnavailableError | None: + if response.status_code == 200: + response_200 = MetadataKeysResponse.from_dict(response.json()) + + return response_200 + + if response.status_code == 422: + response_422 = HTTPValidationError.from_dict(response.json()) + + return response_422 + + if response.status_code == 503: + response_503 = ServiceUnavailableError.from_dict(response.json()) + + return response_503 + + if client.raise_on_unexpected_status: + raise errors.UnexpectedStatus(response.status_code, response.content) + else: + return None + + +def _build_response( + *, client: AuthenticatedClient | Client, response: httpx.Response +) -> Response[HTTPValidationError | MetadataKeysResponse | ServiceUnavailableError]: + return Response( + status_code=HTTPStatus(response.status_code), + content=response.content, + headers=response.headers, + parsed=_parse_response(client=client, response=response), + ) + + +def sync_detailed( + agent_id: UUID, + trigger_id: UUID, + *, + client: AuthenticatedClient | Client, + body: SetMetadataKeysRequest, + x_account_id: UUID | Unset = UNSET, + seclai_version: str | Unset = UNSET, +) -> Response[HTTPValidationError | MetadataKeysResponse | ServiceUnavailableError]: + """Declare the metadata keys a trigger accepts + + A trigger declares the run metadata keys its agent's steps may reference, each `required` or + optional. `system` and `source` keys are written by the platform and are never required; `custom` + keys are sent by the caller. A run you start is refused with HTTP 400 when it lacks a required key + or sends a custom key the trigger does not declare. `trigger_id` is the one `GET /agents/{agent_id}` + returns. + + Auth & scoping: requires `X-API-Key` header or OAuth Bearer token; the trigger must belong to an + agent in the key's account. + + Rejected with HTTP 400 when the agent references a key no trigger of its branch then declares. + + Args: + agent_id (UUID): + trigger_id (UUID): + x_account_id (UUID | Unset): + seclai_version (str | Unset): + body (SetMetadataKeysRequest): + + Raises: + errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True. + httpx.TimeoutException: If the request takes longer than Client.timeout. + + Returns: + Response[HTTPValidationError | MetadataKeysResponse | ServiceUnavailableError] + """ + + kwargs = _get_kwargs( + agent_id=agent_id, + trigger_id=trigger_id, + body=body, + x_account_id=x_account_id, + seclai_version=seclai_version, + ) + + response = client.get_httpx_client().request( + **kwargs, + ) + + return _build_response(client=client, response=response) + + +def sync( + agent_id: UUID, + trigger_id: UUID, + *, + client: AuthenticatedClient | Client, + body: SetMetadataKeysRequest, + x_account_id: UUID | Unset = UNSET, + seclai_version: str | Unset = UNSET, +) -> HTTPValidationError | MetadataKeysResponse | ServiceUnavailableError | None: + """Declare the metadata keys a trigger accepts + + A trigger declares the run metadata keys its agent's steps may reference, each `required` or + optional. `system` and `source` keys are written by the platform and are never required; `custom` + keys are sent by the caller. A run you start is refused with HTTP 400 when it lacks a required key + or sends a custom key the trigger does not declare. `trigger_id` is the one `GET /agents/{agent_id}` + returns. + + Auth & scoping: requires `X-API-Key` header or OAuth Bearer token; the trigger must belong to an + agent in the key's account. + + Rejected with HTTP 400 when the agent references a key no trigger of its branch then declares. + + Args: + agent_id (UUID): + trigger_id (UUID): + x_account_id (UUID | Unset): + seclai_version (str | Unset): + body (SetMetadataKeysRequest): + + Raises: + errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True. + httpx.TimeoutException: If the request takes longer than Client.timeout. + + Returns: + HTTPValidationError | MetadataKeysResponse | ServiceUnavailableError + """ + + return sync_detailed( + agent_id=agent_id, + trigger_id=trigger_id, + client=client, + body=body, + x_account_id=x_account_id, + seclai_version=seclai_version, + ).parsed + + +async def asyncio_detailed( + agent_id: UUID, + trigger_id: UUID, + *, + client: AuthenticatedClient | Client, + body: SetMetadataKeysRequest, + x_account_id: UUID | Unset = UNSET, + seclai_version: str | Unset = UNSET, +) -> Response[HTTPValidationError | MetadataKeysResponse | ServiceUnavailableError]: + """Declare the metadata keys a trigger accepts + + A trigger declares the run metadata keys its agent's steps may reference, each `required` or + optional. `system` and `source` keys are written by the platform and are never required; `custom` + keys are sent by the caller. A run you start is refused with HTTP 400 when it lacks a required key + or sends a custom key the trigger does not declare. `trigger_id` is the one `GET /agents/{agent_id}` + returns. + + Auth & scoping: requires `X-API-Key` header or OAuth Bearer token; the trigger must belong to an + agent in the key's account. + + Rejected with HTTP 400 when the agent references a key no trigger of its branch then declares. + + Args: + agent_id (UUID): + trigger_id (UUID): + x_account_id (UUID | Unset): + seclai_version (str | Unset): + body (SetMetadataKeysRequest): + + Raises: + errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True. + httpx.TimeoutException: If the request takes longer than Client.timeout. + + Returns: + Response[HTTPValidationError | MetadataKeysResponse | ServiceUnavailableError] + """ + + kwargs = _get_kwargs( + agent_id=agent_id, + trigger_id=trigger_id, + body=body, + x_account_id=x_account_id, + seclai_version=seclai_version, + ) + + response = await client.get_async_httpx_client().request(**kwargs) + + return _build_response(client=client, response=response) + + +async def asyncio( + agent_id: UUID, + trigger_id: UUID, + *, + client: AuthenticatedClient | Client, + body: SetMetadataKeysRequest, + x_account_id: UUID | Unset = UNSET, + seclai_version: str | Unset = UNSET, +) -> HTTPValidationError | MetadataKeysResponse | ServiceUnavailableError | None: + """Declare the metadata keys a trigger accepts + + A trigger declares the run metadata keys its agent's steps may reference, each `required` or + optional. `system` and `source` keys are written by the platform and are never required; `custom` + keys are sent by the caller. A run you start is refused with HTTP 400 when it lacks a required key + or sends a custom key the trigger does not declare. `trigger_id` is the one `GET /agents/{agent_id}` + returns. + + Auth & scoping: requires `X-API-Key` header or OAuth Bearer token; the trigger must belong to an + agent in the key's account. + + Rejected with HTTP 400 when the agent references a key no trigger of its branch then declares. + + Args: + agent_id (UUID): + trigger_id (UUID): + x_account_id (UUID | Unset): + seclai_version (str | Unset): + body (SetMetadataKeysRequest): + + Raises: + errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True. + httpx.TimeoutException: If the request takes longer than Client.timeout. + + Returns: + HTTPValidationError | MetadataKeysResponse | ServiceUnavailableError + """ + + return ( + await asyncio_detailed( + agent_id=agent_id, + trigger_id=trigger_id, + client=client, + body=body, + x_account_id=x_account_id, + seclai_version=seclai_version, + ) + ).parsed diff --git a/seclai/_generated/api/agents/update_agent_api_agents_agent_id_put.py b/seclai/_generated/api/agents/update_agent_api_agents_agent_id_put.py index e11068c..cb7394d 100644 --- a/seclai/_generated/api/agents/update_agent_api_agents_agent_id_put.py +++ b/seclai/_generated/api/agents/update_agent_api_agents_agent_id_put.py @@ -101,14 +101,15 @@ def sync_detailed( Update an agent's name, description, evaluation settings, model lifecycle settings and run limits. - Evaluation settings: `evaluation_mode` ('output_expectation', 'eval_and_retry', 'sample_and_flag'), - `default_evaluation_tier` ('fast', 'balanced', 'thorough'), `max_retries`, `retry_on_failure`, - `sampling_config`. + Evaluation settings: `evaluation_mode` ('output_expectation', 'sample_and_flag'; see the field), + `default_evaluation_tier` ('fast', 'balanced', 'thorough'), `sampling_config`. `max_retries` and + `retry_on_failure` are accepted and have no effect. Model lifecycle settings: `prompt_model_auto_upgrade_strategy` ('none', 'early_adopter', 'middle_of_road', 'cautious_adopter'), `prompt_model_auto_rollback_enabled`, - `prompt_model_auto_rollback_triggers` (list of 'agent_eval_fail', 'governance_flag', - 'governance_block', 'agent_run_failed'). + `prompt_model_auto_rollback_triggers` (list of 'governance_flag', 'governance_block', + 'agent_run_failed'; 'agent_eval_fail' never fires, and in the list keeps a run with a failed + evaluation from being a rollback target). Run limits (each must be greater than 0; pass the paired `set_: true` with the value omitted to remove one): `max_credits_per_run`, `max_credits_per_period`, `max_runs_per_hour`, @@ -174,14 +175,15 @@ def sync( Update an agent's name, description, evaluation settings, model lifecycle settings and run limits. - Evaluation settings: `evaluation_mode` ('output_expectation', 'eval_and_retry', 'sample_and_flag'), - `default_evaluation_tier` ('fast', 'balanced', 'thorough'), `max_retries`, `retry_on_failure`, - `sampling_config`. + Evaluation settings: `evaluation_mode` ('output_expectation', 'sample_and_flag'; see the field), + `default_evaluation_tier` ('fast', 'balanced', 'thorough'), `sampling_config`. `max_retries` and + `retry_on_failure` are accepted and have no effect. Model lifecycle settings: `prompt_model_auto_upgrade_strategy` ('none', 'early_adopter', 'middle_of_road', 'cautious_adopter'), `prompt_model_auto_rollback_enabled`, - `prompt_model_auto_rollback_triggers` (list of 'agent_eval_fail', 'governance_flag', - 'governance_block', 'agent_run_failed'). + `prompt_model_auto_rollback_triggers` (list of 'governance_flag', 'governance_block', + 'agent_run_failed'; 'agent_eval_fail' never fires, and in the list keeps a run with a failed + evaluation from being a rollback target). Run limits (each must be greater than 0; pass the paired `set_: true` with the value omitted to remove one): `max_credits_per_run`, `max_credits_per_period`, `max_runs_per_hour`, @@ -239,14 +241,15 @@ async def asyncio_detailed( Update an agent's name, description, evaluation settings, model lifecycle settings and run limits. - Evaluation settings: `evaluation_mode` ('output_expectation', 'eval_and_retry', 'sample_and_flag'), - `default_evaluation_tier` ('fast', 'balanced', 'thorough'), `max_retries`, `retry_on_failure`, - `sampling_config`. + Evaluation settings: `evaluation_mode` ('output_expectation', 'sample_and_flag'; see the field), + `default_evaluation_tier` ('fast', 'balanced', 'thorough'), `sampling_config`. `max_retries` and + `retry_on_failure` are accepted and have no effect. Model lifecycle settings: `prompt_model_auto_upgrade_strategy` ('none', 'early_adopter', 'middle_of_road', 'cautious_adopter'), `prompt_model_auto_rollback_enabled`, - `prompt_model_auto_rollback_triggers` (list of 'agent_eval_fail', 'governance_flag', - 'governance_block', 'agent_run_failed'). + `prompt_model_auto_rollback_triggers` (list of 'governance_flag', 'governance_block', + 'agent_run_failed'; 'agent_eval_fail' never fires, and in the list keeps a run with a failed + evaluation from being a rollback target). Run limits (each must be greater than 0; pass the paired `set_: true` with the value omitted to remove one): `max_credits_per_run`, `max_credits_per_period`, `max_runs_per_hour`, @@ -310,14 +313,15 @@ async def asyncio( Update an agent's name, description, evaluation settings, model lifecycle settings and run limits. - Evaluation settings: `evaluation_mode` ('output_expectation', 'eval_and_retry', 'sample_and_flag'), - `default_evaluation_tier` ('fast', 'balanced', 'thorough'), `max_retries`, `retry_on_failure`, - `sampling_config`. + Evaluation settings: `evaluation_mode` ('output_expectation', 'sample_and_flag'; see the field), + `default_evaluation_tier` ('fast', 'balanced', 'thorough'), `sampling_config`. `max_retries` and + `retry_on_failure` are accepted and have no effect. Model lifecycle settings: `prompt_model_auto_upgrade_strategy` ('none', 'early_adopter', 'middle_of_road', 'cautious_adopter'), `prompt_model_auto_rollback_enabled`, - `prompt_model_auto_rollback_triggers` (list of 'agent_eval_fail', 'governance_flag', - 'governance_block', 'agent_run_failed'). + `prompt_model_auto_rollback_triggers` (list of 'governance_flag', 'governance_block', + 'agent_run_failed'; 'agent_eval_fail' never fires, and in the list keeps a run with a failed + evaluation from being a rollback target). Run limits (each must be greater than 0; pass the paired `set_: true` with the value omitted to remove one): `max_credits_per_run`, `max_credits_per_period`, `max_runs_per_hour`, diff --git a/seclai/_generated/api/agents/update_agent_definition_api_agents_agent_id_definition_put.py b/seclai/_generated/api/agents/update_agent_definition_api_agents_agent_id_definition_put.py index 460f9d6..b2b1c4c 100644 --- a/seclai/_generated/api/agents/update_agent_definition_api_agents_agent_id_definition_put.py +++ b/seclai/_generated/api/agents/update_agent_definition_api_agents_agent_id_definition_put.py @@ -95,20 +95,21 @@ def sync_detailed( last read. The definition contains the agent's step workflow. Step types include `prompt_call`, `retrieval`, - `regex_replace`, `gate`, `retry`, `evaluate_step`, `extract_data`, `extract_content`, - `add_chat_turn`, `load_chat_history`, `add_memory`, `search_memory`, `load_memory`, - `streaming_result`, `send_email`, `webhook_call`, `write_aws_s3_object`, `call_agent`, - `write_metadata`, `write_content_attachment`, `load_content_attachment`, `load_content`, - `display_result`, `join`, `merge`, `text`, `for_each`, `if_else`, and `switch`. Non-composite step - types (`display_result`, `join`, `retry`, `streaming_result`) cannot contain child steps. - - **Retry steps** re-execute from a target ancestor step for quality-control loops. Configure with - `target_step_id` (ancestor step ID) and `max_retries` (1–10). Best practice: place a `gate` step - before the retry to make retries conditional. - - **if_else** runs `then_steps` when its `conditions` (same shape as `gate`) match, otherwise its - optional `else_steps`. Either branch's output flows to the if_else step's own `child_steps` (the - post-branch continuation chain). + `regex_replace`, `evaluate_step`, `extract_data`, `extract_content`, `add_chat_turn`, + `load_chat_history`, `add_memory`, `search_memory`, `load_memory`, `streaming_result`, `send_email`, + `webhook_call`, `write_aws_s3_object`, `call_agent`, `write_metadata`, `write_content_attachment`, + `load_content_attachment`, `load_content`, `display_result`, `join`, `merge`, `text`, `for_each`, + `repeat_until`, `if_else`, and `switch`. Non-composite step types (`display_result`, `join`, + `streaming_result`) cannot contain child steps. A definition holding a `gate` or `retry` step is + rejected: use `if_else`, or `repeat_until` to run steps again until a condition holds. + + **repeat_until** runs its `body[]`, then tests its `conditions` against the iteration's verdict + (`verdict_template`, else the iteration's value); it repeats until they match or `max_iterations` is + reached. + + **if_else** runs `then_steps` when its `conditions` match, otherwise its optional `else_steps`. + Either branch's output flows to the if_else step's own `child_steps` (the post-branch continuation + chain). **switch** dispatches on a `discriminator` template (default `{{input}}`) to the first matching case (equality by default; pass a list in `match` for `$in` semantics) or to `else_steps` when no case @@ -164,20 +165,21 @@ def sync( last read. The definition contains the agent's step workflow. Step types include `prompt_call`, `retrieval`, - `regex_replace`, `gate`, `retry`, `evaluate_step`, `extract_data`, `extract_content`, - `add_chat_turn`, `load_chat_history`, `add_memory`, `search_memory`, `load_memory`, - `streaming_result`, `send_email`, `webhook_call`, `write_aws_s3_object`, `call_agent`, - `write_metadata`, `write_content_attachment`, `load_content_attachment`, `load_content`, - `display_result`, `join`, `merge`, `text`, `for_each`, `if_else`, and `switch`. Non-composite step - types (`display_result`, `join`, `retry`, `streaming_result`) cannot contain child steps. - - **Retry steps** re-execute from a target ancestor step for quality-control loops. Configure with - `target_step_id` (ancestor step ID) and `max_retries` (1–10). Best practice: place a `gate` step - before the retry to make retries conditional. - - **if_else** runs `then_steps` when its `conditions` (same shape as `gate`) match, otherwise its - optional `else_steps`. Either branch's output flows to the if_else step's own `child_steps` (the - post-branch continuation chain). + `regex_replace`, `evaluate_step`, `extract_data`, `extract_content`, `add_chat_turn`, + `load_chat_history`, `add_memory`, `search_memory`, `load_memory`, `streaming_result`, `send_email`, + `webhook_call`, `write_aws_s3_object`, `call_agent`, `write_metadata`, `write_content_attachment`, + `load_content_attachment`, `load_content`, `display_result`, `join`, `merge`, `text`, `for_each`, + `repeat_until`, `if_else`, and `switch`. Non-composite step types (`display_result`, `join`, + `streaming_result`) cannot contain child steps. A definition holding a `gate` or `retry` step is + rejected: use `if_else`, or `repeat_until` to run steps again until a condition holds. + + **repeat_until** runs its `body[]`, then tests its `conditions` against the iteration's verdict + (`verdict_template`, else the iteration's value); it repeats until they match or `max_iterations` is + reached. + + **if_else** runs `then_steps` when its `conditions` match, otherwise its optional `else_steps`. + Either branch's output flows to the if_else step's own `child_steps` (the post-branch continuation + chain). **switch** dispatches on a `discriminator` template (default `{{input}}`) to the first matching case (equality by default; pass a list in `match` for `$in` semantics) or to `else_steps` when no case @@ -228,20 +230,21 @@ async def asyncio_detailed( last read. The definition contains the agent's step workflow. Step types include `prompt_call`, `retrieval`, - `regex_replace`, `gate`, `retry`, `evaluate_step`, `extract_data`, `extract_content`, - `add_chat_turn`, `load_chat_history`, `add_memory`, `search_memory`, `load_memory`, - `streaming_result`, `send_email`, `webhook_call`, `write_aws_s3_object`, `call_agent`, - `write_metadata`, `write_content_attachment`, `load_content_attachment`, `load_content`, - `display_result`, `join`, `merge`, `text`, `for_each`, `if_else`, and `switch`. Non-composite step - types (`display_result`, `join`, `retry`, `streaming_result`) cannot contain child steps. - - **Retry steps** re-execute from a target ancestor step for quality-control loops. Configure with - `target_step_id` (ancestor step ID) and `max_retries` (1–10). Best practice: place a `gate` step - before the retry to make retries conditional. - - **if_else** runs `then_steps` when its `conditions` (same shape as `gate`) match, otherwise its - optional `else_steps`. Either branch's output flows to the if_else step's own `child_steps` (the - post-branch continuation chain). + `regex_replace`, `evaluate_step`, `extract_data`, `extract_content`, `add_chat_turn`, + `load_chat_history`, `add_memory`, `search_memory`, `load_memory`, `streaming_result`, `send_email`, + `webhook_call`, `write_aws_s3_object`, `call_agent`, `write_metadata`, `write_content_attachment`, + `load_content_attachment`, `load_content`, `display_result`, `join`, `merge`, `text`, `for_each`, + `repeat_until`, `if_else`, and `switch`. Non-composite step types (`display_result`, `join`, + `streaming_result`) cannot contain child steps. A definition holding a `gate` or `retry` step is + rejected: use `if_else`, or `repeat_until` to run steps again until a condition holds. + + **repeat_until** runs its `body[]`, then tests its `conditions` against the iteration's verdict + (`verdict_template`, else the iteration's value); it repeats until they match or `max_iterations` is + reached. + + **if_else** runs `then_steps` when its `conditions` match, otherwise its optional `else_steps`. + Either branch's output flows to the if_else step's own `child_steps` (the post-branch continuation + chain). **switch** dispatches on a `discriminator` template (default `{{input}}`) to the first matching case (equality by default; pass a list in `match` for `$in` semantics) or to `else_steps` when no case @@ -295,20 +298,21 @@ async def asyncio( last read. The definition contains the agent's step workflow. Step types include `prompt_call`, `retrieval`, - `regex_replace`, `gate`, `retry`, `evaluate_step`, `extract_data`, `extract_content`, - `add_chat_turn`, `load_chat_history`, `add_memory`, `search_memory`, `load_memory`, - `streaming_result`, `send_email`, `webhook_call`, `write_aws_s3_object`, `call_agent`, - `write_metadata`, `write_content_attachment`, `load_content_attachment`, `load_content`, - `display_result`, `join`, `merge`, `text`, `for_each`, `if_else`, and `switch`. Non-composite step - types (`display_result`, `join`, `retry`, `streaming_result`) cannot contain child steps. - - **Retry steps** re-execute from a target ancestor step for quality-control loops. Configure with - `target_step_id` (ancestor step ID) and `max_retries` (1–10). Best practice: place a `gate` step - before the retry to make retries conditional. - - **if_else** runs `then_steps` when its `conditions` (same shape as `gate`) match, otherwise its - optional `else_steps`. Either branch's output flows to the if_else step's own `child_steps` (the - post-branch continuation chain). + `regex_replace`, `evaluate_step`, `extract_data`, `extract_content`, `add_chat_turn`, + `load_chat_history`, `add_memory`, `search_memory`, `load_memory`, `streaming_result`, `send_email`, + `webhook_call`, `write_aws_s3_object`, `call_agent`, `write_metadata`, `write_content_attachment`, + `load_content_attachment`, `load_content`, `display_result`, `join`, `merge`, `text`, `for_each`, + `repeat_until`, `if_else`, and `switch`. Non-composite step types (`display_result`, `join`, + `streaming_result`) cannot contain child steps. A definition holding a `gate` or `retry` step is + rejected: use `if_else`, or `repeat_until` to run steps again until a condition holds. + + **repeat_until** runs its `body[]`, then tests its `conditions` against the iteration's verdict + (`verdict_template`, else the iteration's value); it repeats until they match or `max_iterations` is + reached. + + **if_else** runs `then_steps` when its `conditions` match, otherwise its optional `else_steps`. + Either branch's output flows to the if_else step's own `child_steps` (the post-branch continuation + chain). **switch** dispatches on a `discriminator` template (default `{{input}}`) to the first matching case (equality by default; pass a list in `match` for `$in` semantics) or to `else_steps` when no case diff --git a/seclai/_generated/api/knowledge_bases/get_knowledge_base_metadata_key_stats_api_knowledge_bases_knowledge_base_id_metadata_key_stats_get.py b/seclai/_generated/api/knowledge_bases/get_knowledge_base_metadata_key_stats_api_knowledge_bases_knowledge_base_id_metadata_key_stats_get.py new file mode 100644 index 0000000..f6e8ef3 --- /dev/null +++ b/seclai/_generated/api/knowledge_bases/get_knowledge_base_metadata_key_stats_api_knowledge_bases_knowledge_base_id_metadata_key_stats_get.py @@ -0,0 +1,254 @@ +from http import HTTPStatus +from typing import Any +from urllib.parse import quote +from uuid import UUID + +import httpx + +from ... import errors +from ...client import AuthenticatedClient, Client +from ...models.http_validation_error import HTTPValidationError +from ...models.knowledge_base_metadata_key_stats import KnowledgeBaseMetadataKeyStats +from ...models.service_unavailable_error import ServiceUnavailableError +from ...types import UNSET, Response, Unset + + +def _get_kwargs( + knowledge_base_id: str, + *, + x_account_id: UUID | Unset = UNSET, + seclai_version: str | Unset = UNSET, +) -> dict[str, Any]: + headers: dict[str, Any] = {} + if not isinstance(x_account_id, Unset): + headers["X-Account-Id"] = x_account_id + + if not isinstance(seclai_version, Unset): + headers["Seclai-Version"] = seclai_version + + _kwargs: dict[str, Any] = { + "method": "get", + "url": "/knowledge_bases/{knowledge_base_id}/metadata-key-stats".format( + knowledge_base_id=quote(str(knowledge_base_id), safe=""), + ), + } + + _kwargs["headers"] = headers + return _kwargs + + +def _parse_response( + *, client: AuthenticatedClient | Client, response: httpx.Response +) -> ( + HTTPValidationError | KnowledgeBaseMetadataKeyStats | ServiceUnavailableError | None +): + if response.status_code == 200: + response_200 = KnowledgeBaseMetadataKeyStats.from_dict(response.json()) + + return response_200 + + if response.status_code == 422: + response_422 = HTTPValidationError.from_dict(response.json()) + + return response_422 + + if response.status_code == 503: + response_503 = ServiceUnavailableError.from_dict(response.json()) + + return response_503 + + if client.raise_on_unexpected_status: + raise errors.UnexpectedStatus(response.status_code, response.content) + else: + return None + + +def _build_response( + *, client: AuthenticatedClient | Client, response: httpx.Response +) -> Response[ + HTTPValidationError | KnowledgeBaseMetadataKeyStats | ServiceUnavailableError +]: + return Response( + status_code=HTTPStatus(response.status_code), + content=response.content, + headers=response.headers, + parsed=_parse_response(client=client, response=response), + ) + + +def sync_detailed( + knowledge_base_id: str, + *, + client: AuthenticatedClient | Client, + x_account_id: UUID | Unset = UNSET, + seclai_version: str | Unset = UNSET, +) -> Response[ + HTTPValidationError | KnowledgeBaseMetadataKeyStats | ServiceUnavailableError +]: + """Get Knowledge Base Metadata Key Stats + + How often each item-metadata key appears on the knowledge base's content items, for declaring a + content trigger's metadata keys. An item is counted once, at its latest version; the total includes + items with no metadata. Only keys a content run carries are listed: a null value counts as absent, + and reserved keys and the keys the platform sets after the item's own are left out. Each window + counts the items whose latest version was created or linked in it. + + Auth & scoping: + - Requires `X-API-Key` header or OAuth Bearer token. You can only access knowledge bases belonging + to your account. + + Args: + knowledge_base_id (str): + x_account_id (UUID | Unset): + seclai_version (str | Unset): + + Raises: + errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True. + httpx.TimeoutException: If the request takes longer than Client.timeout. + + Returns: + Response[HTTPValidationError | KnowledgeBaseMetadataKeyStats | ServiceUnavailableError] + """ + + kwargs = _get_kwargs( + knowledge_base_id=knowledge_base_id, + x_account_id=x_account_id, + seclai_version=seclai_version, + ) + + response = client.get_httpx_client().request( + **kwargs, + ) + + return _build_response(client=client, response=response) + + +def sync( + knowledge_base_id: str, + *, + client: AuthenticatedClient | Client, + x_account_id: UUID | Unset = UNSET, + seclai_version: str | Unset = UNSET, +) -> ( + HTTPValidationError | KnowledgeBaseMetadataKeyStats | ServiceUnavailableError | None +): + """Get Knowledge Base Metadata Key Stats + + How often each item-metadata key appears on the knowledge base's content items, for declaring a + content trigger's metadata keys. An item is counted once, at its latest version; the total includes + items with no metadata. Only keys a content run carries are listed: a null value counts as absent, + and reserved keys and the keys the platform sets after the item's own are left out. Each window + counts the items whose latest version was created or linked in it. + + Auth & scoping: + - Requires `X-API-Key` header or OAuth Bearer token. You can only access knowledge bases belonging + to your account. + + Args: + knowledge_base_id (str): + x_account_id (UUID | Unset): + seclai_version (str | Unset): + + Raises: + errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True. + httpx.TimeoutException: If the request takes longer than Client.timeout. + + Returns: + HTTPValidationError | KnowledgeBaseMetadataKeyStats | ServiceUnavailableError + """ + + return sync_detailed( + knowledge_base_id=knowledge_base_id, + client=client, + x_account_id=x_account_id, + seclai_version=seclai_version, + ).parsed + + +async def asyncio_detailed( + knowledge_base_id: str, + *, + client: AuthenticatedClient | Client, + x_account_id: UUID | Unset = UNSET, + seclai_version: str | Unset = UNSET, +) -> Response[ + HTTPValidationError | KnowledgeBaseMetadataKeyStats | ServiceUnavailableError +]: + """Get Knowledge Base Metadata Key Stats + + How often each item-metadata key appears on the knowledge base's content items, for declaring a + content trigger's metadata keys. An item is counted once, at its latest version; the total includes + items with no metadata. Only keys a content run carries are listed: a null value counts as absent, + and reserved keys and the keys the platform sets after the item's own are left out. Each window + counts the items whose latest version was created or linked in it. + + Auth & scoping: + - Requires `X-API-Key` header or OAuth Bearer token. You can only access knowledge bases belonging + to your account. + + Args: + knowledge_base_id (str): + x_account_id (UUID | Unset): + seclai_version (str | Unset): + + Raises: + errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True. + httpx.TimeoutException: If the request takes longer than Client.timeout. + + Returns: + Response[HTTPValidationError | KnowledgeBaseMetadataKeyStats | ServiceUnavailableError] + """ + + kwargs = _get_kwargs( + knowledge_base_id=knowledge_base_id, + x_account_id=x_account_id, + seclai_version=seclai_version, + ) + + response = await client.get_async_httpx_client().request(**kwargs) + + return _build_response(client=client, response=response) + + +async def asyncio( + knowledge_base_id: str, + *, + client: AuthenticatedClient | Client, + x_account_id: UUID | Unset = UNSET, + seclai_version: str | Unset = UNSET, +) -> ( + HTTPValidationError | KnowledgeBaseMetadataKeyStats | ServiceUnavailableError | None +): + """Get Knowledge Base Metadata Key Stats + + How often each item-metadata key appears on the knowledge base's content items, for declaring a + content trigger's metadata keys. An item is counted once, at its latest version; the total includes + items with no metadata. Only keys a content run carries are listed: a null value counts as absent, + and reserved keys and the keys the platform sets after the item's own are left out. Each window + counts the items whose latest version was created or linked in it. + + Auth & scoping: + - Requires `X-API-Key` header or OAuth Bearer token. You can only access knowledge bases belonging + to your account. + + Args: + knowledge_base_id (str): + x_account_id (UUID | Unset): + seclai_version (str | Unset): + + Raises: + errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True. + httpx.TimeoutException: If the request takes longer than Client.timeout. + + Returns: + HTTPValidationError | KnowledgeBaseMetadataKeyStats | ServiceUnavailableError + """ + + return ( + await asyncio_detailed( + knowledge_base_id=knowledge_base_id, + client=client, + x_account_id=x_account_id, + seclai_version=seclai_version, + ) + ).parsed diff --git a/seclai/_generated/models/__init__.py b/seclai/_generated/models/__init__.py index 4deabc5..d06159b 100644 --- a/seclai/_generated/models/__init__.py +++ b/seclai/_generated/models/__init__.py @@ -156,6 +156,7 @@ from .create_memory_bank_body import CreateMemoryBankBody from .create_solution_request import CreateSolutionRequest from .create_source_body import CreateSourceBody +from .declarable_metadata_key import DeclarableMetadataKey from .dmarc_failing_source_response import DmarcFailingSourceResponse from .dmarc_summary_response import DmarcSummaryResponse from .dmarc_summary_response_dispositions import DmarcSummaryResponseDispositions @@ -274,6 +275,7 @@ from .insufficient_credits_response import InsufficientCreditsResponse from .knowledge_base import KnowledgeBase from .knowledge_base_list_response_model import KnowledgeBaseListResponseModel +from .knowledge_base_metadata_key_stats import KnowledgeBaseMetadataKeyStats from .link_resources_request import LinkResourcesRequest from .mark_ai_suggestion_request import MarkAiSuggestionRequest from .mark_conversation_turn_request import MarkConversationTurnRequest @@ -292,6 +294,13 @@ ) from .memory_bank_last_conversation_response import MemoryBankLastConversationResponse from .memory_bank_list_response_model import MemoryBankListResponseModel +from .metadata_key_count_response import MetadataKeyCountResponse +from .metadata_key_declaration import MetadataKeyDeclaration +from .metadata_key_window_response import MetadataKeyWindowResponse +from .metadata_key_window_response_window import MetadataKeyWindowResponseWindow +from .metadata_keys_response import MetadataKeysResponse +from .metadata_origin import MetadataOrigin +from .metadata_value_count_response import MetadataValueCountResponse from .modality_rate_response import ModalityRateResponse from .model_alert_list_response import ModelAlertListResponse from .model_alert_response import ModelAlertResponse @@ -351,6 +360,7 @@ from .set_accepted_attachments_request import SetAcceptedAttachmentsRequest from .set_auto_block_mode_request import SetAutoBlockModeRequest from .set_email_trigger_config_request import SetEmailTriggerConfigRequest +from .set_metadata_keys_request import SetMetadataKeysRequest from .set_slack_trigger_config_api_request import SetSlackTriggerConfigApiRequest from .set_slack_trigger_config_api_request_form_type_0_item import ( SetSlackTriggerConfigApiRequestFormType0Item, @@ -541,6 +551,7 @@ "CreateMemoryBankBody", "CreateSolutionRequest", "CreateSourceBody", + "DeclarableMetadataKey", "DmarcFailingSourceResponse", "DmarcSummaryResponse", "DmarcSummaryResponseDispositions", @@ -621,6 +632,7 @@ "InsufficientCreditsResponse", "KnowledgeBase", "KnowledgeBaseListResponseModel", + "KnowledgeBaseMetadataKeyStats", "LinkResourcesRequest", "MarkAiSuggestionRequest", "MarkConversationTurnRequest", @@ -635,6 +647,13 @@ "MemoryBankLastConversationResponse", "MemoryBankListResponseModel", "MeResponse", + "MetadataKeyCountResponse", + "MetadataKeyDeclaration", + "MetadataKeysResponse", + "MetadataKeyWindowResponse", + "MetadataKeyWindowResponseWindow", + "MetadataOrigin", + "MetadataValueCountResponse", "ModalityRateResponse", "ModelAlertListResponse", "ModelAlertResponse", @@ -678,6 +697,7 @@ "SetAcceptedAttachmentsRequest", "SetAutoBlockModeRequest", "SetEmailTriggerConfigRequest", + "SetMetadataKeysRequest", "SetSlackTriggerConfigApiRequest", "SetSlackTriggerConfigApiRequestFormType0Item", "SkippedAttachmentReason", diff --git a/seclai/_generated/models/agent_definition_response.py b/seclai/_generated/models/agent_definition_response.py index e49f7e0..dcc3b3a 100644 --- a/seclai/_generated/models/agent_definition_response.py +++ b/seclai/_generated/models/agent_definition_response.py @@ -26,10 +26,10 @@ class AgentDefinitionResponse: Attributes: change_id (str): Current change ID (use as expected_change_id when updating). definition (AgentDefinitionResponseDefinition): The agent definition containing name, description, tags, and - step workflow tree. Step types include prompt_call, retrieval, regex_replace, gate, retry, evaluate_step, - extract_data, extract_content, add_chat_turn, load_chat_history, add_memory, search_memory, load_memory, - streaming_result, send_email, webhook_call, call_agent, write_metadata, write_content_attachment, - load_content_attachment, load_content, display_result, merge, for_each, if_else, switch, and others. + step workflow tree. Step types include prompt_call, retrieval, regex_replace, evaluate_step, extract_data, + extract_content, add_chat_turn, load_chat_history, add_memory, search_memory, load_memory, streaming_result, + send_email, webhook_call, call_agent, write_metadata, write_content_attachment, load_content_attachment, + load_content, display_result, merge, for_each, if_else, switch, and others. schema_version (str): Agent schema version. warnings (list[AgentDefinitionResponseWarningsType0Item] | None | Unset): Validation warnings, if any. """ diff --git a/seclai/_generated/models/agent_definition_response_definition.py b/seclai/_generated/models/agent_definition_response_definition.py index 3689015..cd6241b 100644 --- a/seclai/_generated/models/agent_definition_response_definition.py +++ b/seclai/_generated/models/agent_definition_response_definition.py @@ -12,10 +12,10 @@ @_attrs_define class AgentDefinitionResponseDefinition: """The agent definition containing name, description, tags, and step workflow tree. Step types include prompt_call, - retrieval, regex_replace, gate, retry, evaluate_step, extract_data, extract_content, add_chat_turn, - load_chat_history, add_memory, search_memory, load_memory, streaming_result, send_email, webhook_call, call_agent, - write_metadata, write_content_attachment, load_content_attachment, load_content, display_result, merge, for_each, - if_else, switch, and others. + retrieval, regex_replace, evaluate_step, extract_data, extract_content, add_chat_turn, load_chat_history, + add_memory, search_memory, load_memory, streaming_result, send_email, webhook_call, call_agent, write_metadata, + write_content_attachment, load_content_attachment, load_content, display_result, merge, for_each, if_else, switch, + and others. """ diff --git a/seclai/_generated/models/agent_export_response.py b/seclai/_generated/models/agent_export_response.py index 12e1d25..d0e5f8c 100644 --- a/seclai/_generated/models/agent_export_response.py +++ b/seclai/_generated/models/agent_export_response.py @@ -40,7 +40,7 @@ class AgentExportResponse: prompt_model_auto_upgrade_strategy, prompt_model_auto_rollback_enabled, prompt_model_auto_rollback_triggers, max_credits_per_run, max_credits_per_period, max_runs_per_hour, max_runs_per_day, max_runs_total, created_at, updated_at. - export_version (str): Schema version of the export format (currently "5"). + export_version (str): Schema version of the export format (currently "6"). exported_at (str): ISO-8601 timestamp of when the export was generated. software_version (str): Application version that produced this export. alert_configs (list[AgentExportResponseAlertConfigsType0Item] | None | Unset): Alert configurations. diff --git a/seclai/_generated/models/agent_run_request.py b/seclai/_generated/models/agent_run_request.py index 8ca3910..09daec8 100644 --- a/seclai/_generated/models/agent_run_request.py +++ b/seclai/_generated/models/agent_run_request.py @@ -41,8 +41,9 @@ class AgentRunRequest: Mutually exclusive with ``input_upload_id`` (two spellings of the same batch), but may be combined with ``input`` — the prompt text leads and the per-file sections follow, so "a photo plus a sentence about it" needs no synthetic text upload. Max 20 uploads per run. - metadata (AgentRunRequestMetadataType0 | None | Unset): Metadata to make available for string substitution - expressions in agent tasks. + metadata (AgentRunRequestMetadataType0 | None | Unset): Metadata for string substitution in agent tasks. Each + key must be one the agent's trigger declares (or sets); a run that sends another custom key, or lacks a required + one, is refused with HTTP 400. priority (bool | Unset): If true, the agent run will be treated as priority execution. Default: False. replay_of_run_id (None | Unset | UUID): Re-run this agent reusing a prior run's uploaded input files. The files are re-resolved server-side from the source run (which must belong to this account and agent) — you do not re- diff --git a/seclai/_generated/models/agent_run_response.py b/seclai/_generated/models/agent_run_response.py index 7842585..8d88eca 100644 --- a/seclai/_generated/models/agent_run_response.py +++ b/seclai/_generated/models/agent_run_response.py @@ -44,11 +44,11 @@ class AgentRunResponse: BLOCK verdict during this run. Deduplicated by policy id. flagged_policies (list[GovernancePolicyRefResponse] | Unset): Governance policies that produced at least one FLAG verdict during this run. Deduplicated by policy id. - governance_input_status (None | str | Unset): Result of the governance input evaluation: safe, blocked, skipped, - or timed_out. + governance_input_status (None | str | Unset): Result of the governance input evaluation: pending, safe, blocked, + skipped, timed_out, or error. governance_input_wait_ms (int | None | Unset): Milliseconds spent waiting for governance input evaluation. - hitl_wait_ms (int | None | Unset): Cumulative milliseconds the run was parked waiting for a human decision on a - human_in_the_loop step. Subtracted from active duration in run-detail and duration-stats responses. + hitl_wait_ms (int | None | Unset): Sum over the run's human_in_the_loop steps of each one's wait for a decision, + in milliseconds. Waits that overlap are each counted in full, so the sum can exceed the run's duration. input_scan_status (None | str | Unset): Result of the prompt injection scan: safe, unsafe, skipped, timed_out, or error. output_content_type (None | str | Unset): MIME type of `output` — mirrors the terminal step's @@ -56,6 +56,12 @@ class AgentRunResponse: Below `Seclai-Version: 2026-09-30` an output that has files reads `application/vnd.seclai.manifest+json` (see `output`); the same files are in `attachments` on every version, each with a `download_url`. Null on runs that produced no terminal output or that pre-date this column. + result_reported_at (datetime.datetime | None | Unset): When the run reported success: for an agent whose + `report_success` is `on_result`, once its result step published, or once its run started if it has no result + step; else when the run completed. From then on `output` is the run's answer and never changes; stop polling + here if you only need the answer. `status` still follows every step, so a run can report success and later + fail. Null until the run reports, for a run that failed before reporting, and for runs that ended before this + field existed. scan_wait_ms (int | None | Unset): Milliseconds spent waiting for prompt injection scan. steps (list[AgentRunStepResponse] | None | Unset): Step outputs and per-step timing/credits. Only included when requested. @@ -65,9 +71,8 @@ class AgentRunResponse: `error` may be null as well, so a failed tool call can report its status without a message. Branch on this rather than on a null `output`: a run that genuinely produced nothing looks identical. Status, timing and credits remain accurate. - wait_ms (int | None | Unset): Cumulative milliseconds the run was parked on standard-mode wait steps. - Subtracted from active duration in run-detail and duration-stats responses, exactly like hitl_wait_ms. Priority - waits block inline and are not counted here. + wait_ms (int | None | Unset): Sum over the run's standard-mode wait steps of each one's wait, in milliseconds. + Waits that overlap are each counted in full. Priority waits block inline and are not counted here. """ attempts: list[AgentRunAttemptResponse] @@ -86,6 +91,7 @@ class AgentRunResponse: hitl_wait_ms: int | None | Unset = UNSET input_scan_status: None | str | Unset = UNSET output_content_type: None | str | Unset = UNSET + result_reported_at: datetime.datetime | None | Unset = UNSET scan_wait_ms: int | None | Unset = UNSET steps: list[AgentRunStepResponse] | None | Unset = UNSET trace_purged_at: datetime.datetime | None | Unset = UNSET @@ -166,6 +172,14 @@ def to_dict(self) -> dict[str, Any]: else: output_content_type = self.output_content_type + result_reported_at: None | str | Unset + if isinstance(self.result_reported_at, Unset): + result_reported_at = UNSET + elif isinstance(self.result_reported_at, datetime.datetime): + result_reported_at = self.result_reported_at.isoformat() + else: + result_reported_at = self.result_reported_at + scan_wait_ms: int | None | Unset if isinstance(self.scan_wait_ms, Unset): scan_wait_ms = UNSET @@ -228,6 +242,8 @@ def to_dict(self) -> dict[str, Any]: field_dict["input_scan_status"] = input_scan_status if output_content_type is not UNSET: field_dict["output_content_type"] = output_content_type + if result_reported_at is not UNSET: + field_dict["result_reported_at"] = result_reported_at if scan_wait_ms is not UNSET: field_dict["scan_wait_ms"] = scan_wait_ms if steps is not UNSET: @@ -365,6 +381,25 @@ def _parse_output_content_type(data: object) -> None | str | Unset: d.pop("output_content_type", UNSET) ) + def _parse_result_reported_at(data: object) -> datetime.datetime | None | Unset: + if data is None: + return data + if isinstance(data, Unset): + return data + try: + if not isinstance(data, str): + raise TypeError() + result_reported_at_type_0 = isoparse(data) + + return result_reported_at_type_0 + except (TypeError, ValueError, AttributeError, KeyError): + pass + return cast(datetime.datetime | None | Unset, data) + + result_reported_at = _parse_result_reported_at( + d.pop("result_reported_at", UNSET) + ) + def _parse_scan_wait_ms(data: object) -> int | None | Unset: if data is None: return data @@ -441,6 +476,7 @@ def _parse_wait_ms(data: object) -> int | None | Unset: hitl_wait_ms=hitl_wait_ms, input_scan_status=input_scan_status, output_content_type=output_content_type, + result_reported_at=result_reported_at, scan_wait_ms=scan_wait_ms, steps=steps, trace_purged_at=trace_purged_at, diff --git a/seclai/_generated/models/agent_run_stream_request.py b/seclai/_generated/models/agent_run_stream_request.py index 2178bec..bbebfa5 100644 --- a/seclai/_generated/models/agent_run_stream_request.py +++ b/seclai/_generated/models/agent_run_stream_request.py @@ -33,8 +33,9 @@ class AgentRunStreamRequest: input_upload_ids (list[UUID] | None | Unset): IDs of multiple previously uploaded files. See the non-streaming endpoint for full semantics, including fitting the trigger's ``accepted_attachments`` (else HTTP 400) and combining the batch with ``input`` prompt text. Max 20. - metadata (AgentRunStreamRequestMetadataType0 | None | Unset): Metadata to make available for string substitution - expressions in agent tasks. + metadata (AgentRunStreamRequestMetadataType0 | None | Unset): Metadata for string substitution in agent tasks. + Each key must be one the agent's trigger declares (or sets); a run that sends another custom key, or lacks a + required one, is refused with HTTP 400. replay_of_run_id (None | Unset | UUID): Re-run reusing a prior run's uploaded input files (re-resolved server- side from the source run, which must belong to this account and agent). A fresh upload batch takes precedence. Files the trigger's ``accepted_attachments`` no longer accepts are left out. diff --git a/seclai/_generated/models/agent_summary_response.py b/seclai/_generated/models/agent_summary_response.py index 2d86b9b..822d255 100644 --- a/seclai/_generated/models/agent_summary_response.py +++ b/seclai/_generated/models/agent_summary_response.py @@ -36,24 +36,24 @@ class AgentSummaryResponse: disabled (bool | Unset): Whether the agent is paused (disabled). Default: False. disabled_at (None | str | Unset): ISO 8601 timestamp the agent was paused. disabled_reason (None | str | Unset): Why the agent is paused: 'manual' or 'email_overload'. - evaluation_mode (str | Unset): Evaluation mode: output_expectation, eval_and_retry, or sample_and_flag. Default: - 'eval_and_retry'. + evaluation_mode (str | Unset): Evaluation mode: output_expectation or sample_and_flag. Default: + 'sample_and_flag'. import_warnings (list[ImportSkipResponse] | None | Unset): One entry per item dropped or substituted during import. Present only on endpoints that accept agent_definition; null on non-import calls; [] when the import had no skips. max_credits_per_period (float | None | Unset): Credit limit per billing period; null when none. max_credits_per_run (float | None | Unset): Credit limit per run; null when none. - max_retries (int | Unset): Max retries for eval_and_retry mode. Default: 3. + max_retries (int | Unset): Deprecated: has no effect. Default: 3. max_runs_per_day (int | None | Unset): Runs per day limit; null when none. max_runs_per_hour (int | None | Unset): Runs per hour limit; null when none. max_runs_total (int | None | Unset): Limit on runs in total; null when none. prompt_model_auto_rollback_enabled (bool | Unset): Whether automatic rollback is enabled for upgraded models. Default: False. prompt_model_auto_rollback_triggers (list[str] | None | Unset): Failure signals that trigger rollback. Defaults - to agent_eval_fail, governance_block, agent_run_failed when null. + to governance_block, agent_run_failed when null. prompt_model_auto_upgrade_strategy (str | Unset): Auto-upgrade strategy: none, early_adopter, middle_of_road, cautious_adopter. Default: 'none'. - retry_on_failure (bool | Unset): Whether to retry on evaluation failure. Default: True. + retry_on_failure (bool | Unset): Deprecated: has no effect. Default: True. sampling_config (AgentSummaryResponseSamplingConfigType0 | None | Unset): Sampling configuration for sample_and_flag mode. solution_id (None | str | Unset): On a create from an `agent_template` that created resources: the solution @@ -73,7 +73,7 @@ class AgentSummaryResponse: disabled: bool | Unset = False disabled_at: None | str | Unset = UNSET disabled_reason: None | str | Unset = UNSET - evaluation_mode: str | Unset = "eval_and_retry" + evaluation_mode: str | Unset = "sample_and_flag" import_warnings: list[ImportSkipResponse] | None | Unset = UNSET max_credits_per_period: float | None | Unset = UNSET max_credits_per_run: float | None | Unset = UNSET diff --git a/seclai/_generated/models/create_evaluation_criteria_request.py b/seclai/_generated/models/create_evaluation_criteria_request.py index 110106f..17d668f 100644 --- a/seclai/_generated/models/create_evaluation_criteria_request.py +++ b/seclai/_generated/models/create_evaluation_criteria_request.py @@ -22,7 +22,8 @@ class CreateEvaluationCriteriaRequest: """Request body for creating an evaluation criteria. - The evaluation mode, retry settings, and sample frequency are set at the + step_id names the display_result or streaming_result step to score. The + evaluation mode and sample frequency are set at the agent level, not per-criteria. Attributes: diff --git a/seclai/_generated/models/create_evaluation_result_request.py b/seclai/_generated/models/create_evaluation_result_request.py index 549c9ff..5e62778 100644 --- a/seclai/_generated/models/create_evaluation_result_request.py +++ b/seclai/_generated/models/create_evaluation_result_request.py @@ -29,8 +29,8 @@ class CreateEvaluationResultRequest: agent_step_run_id (None | Unset | UUID): details (CreateEvaluationResultRequestDetailsType0 | None | Unset): flagged (bool | Unset): Default: False. - retry_count (int | Unset): Default: 0. - retry_triggered (bool | Unset): Default: False. + retry_count (int | Unset): Deprecated: has no effect on any count. Default: 0. + retry_triggered (bool | Unset): Retired; true returns 400 from Seclai-Version 2026-11-04. Default: False. score (float | None | Unset): """ diff --git a/seclai/_generated/models/declarable_metadata_key.py b/seclai/_generated/models/declarable_metadata_key.py new file mode 100644 index 0000000..142be7c --- /dev/null +++ b/seclai/_generated/models/declarable_metadata_key.py @@ -0,0 +1,79 @@ +from __future__ import annotations + +from collections.abc import Mapping +from typing import Any, TypeVar + +from attrs import define as _attrs_define +from attrs import field as _attrs_field + +from ..models.metadata_origin import MetadataOrigin + +T = TypeVar("T", bound="DeclarableMetadataKey") + + +@_attrs_define +class DeclarableMetadataKey: + """ + Attributes: + always_present (bool): Whether every run carries this key. + key (str): + origin (MetadataOrigin): Who writes a run metadata key (docs/architecture/run-metadata.md, Q2). + """ + + always_present: bool + key: str + origin: MetadataOrigin + additional_properties: dict[str, Any] = _attrs_field(init=False, factory=dict) + + def to_dict(self) -> dict[str, Any]: + always_present = self.always_present + + key = self.key + + origin = self.origin.value + + field_dict: dict[str, Any] = {} + field_dict.update(self.additional_properties) + field_dict.update( + { + "always_present": always_present, + "key": key, + "origin": origin, + } + ) + + return field_dict + + @classmethod + def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T: + d = dict(src_dict) + always_present = d.pop("always_present") + + key = d.pop("key") + + origin = MetadataOrigin(d.pop("origin")) + + declarable_metadata_key = cls( + always_present=always_present, + key=key, + origin=origin, + ) + + declarable_metadata_key.additional_properties = d + return declarable_metadata_key + + @property + def additional_keys(self) -> list[str]: + return list(self.additional_properties.keys()) + + def __getitem__(self, key: str) -> Any: + return self.additional_properties[key] + + def __setitem__(self, key: str, value: Any) -> None: + self.additional_properties[key] = value + + def __delitem__(self, key: str) -> None: + del self.additional_properties[key] + + def __contains__(self, key: str) -> bool: + return key in self.additional_properties diff --git a/seclai/_generated/models/evaluation_criteria_response.py b/seclai/_generated/models/evaluation_criteria_response.py index ca56eee..7c4d52d 100644 --- a/seclai/_generated/models/evaluation_criteria_response.py +++ b/seclai/_generated/models/evaluation_criteria_response.py @@ -29,16 +29,16 @@ class EvaluationCriteriaResponse: created_at (str): description (None | str): enabled (bool): - evaluation_mode (str): Runtime behavior mode. output_expectation (manual validation), eval_and_retry (every run - + retry), sample_and_flag (sampled monitoring). + evaluation_mode (str): Runtime behavior mode. output_expectation (manual validation), sample_and_flag (sampled + monitoring). evaluation_prompt (None | str): evaluation_tier (None | str): expectation_config (EvaluationCriteriaResponseExpectationConfigType0 | None): id (UUID): - max_retries (int): + max_retries (int): Deprecated: has no effect. pass_threshold (float): Score cutoff for pass/fail, inclusive (0.0 to 1.0). result_summary (EvaluationCriteriaResponseResultSummary): - retry_on_failure (bool): + retry_on_failure (bool): Deprecated: has no effect. step_id (None | str): updated_at (str): """ diff --git a/seclai/_generated/models/evaluation_result_response.py b/seclai/_generated/models/evaluation_result_response.py index fc9e029..6e9c411 100644 --- a/seclai/_generated/models/evaluation_result_response.py +++ b/seclai/_generated/models/evaluation_result_response.py @@ -30,8 +30,8 @@ class EvaluationResultResponse: evaluated_at (str): flagged (bool): True when the result was flagged for human review. id (UUID): - retry_count (int): - retry_triggered (bool): + retry_count (int): Deprecated. + retry_triggered (bool): Deprecated. status (str): Outcome status: pending, passed, failed, skipped, or error. details (EvaluationResultResponseDetailsType0 | None | Unset): Evaluation details including explanation and raw LLM response. diff --git a/seclai/_generated/models/evaluation_result_with_criteria_response.py b/seclai/_generated/models/evaluation_result_with_criteria_response.py index 0f3ce13..ec5f44a 100644 --- a/seclai/_generated/models/evaluation_result_with_criteria_response.py +++ b/seclai/_generated/models/evaluation_result_with_criteria_response.py @@ -31,8 +31,8 @@ class EvaluationResultWithCriteriaResponse: evaluated_at (str): flagged (bool): True when the result was flagged for human review. id (UUID): - retry_count (int): - retry_triggered (bool): + retry_count (int): Deprecated. + retry_triggered (bool): Deprecated. status (str): Outcome status: pending, passed, failed, skipped, or error. step_id (None | str): details (EvaluationResultWithCriteriaResponseDetailsType0 | None | Unset): Evaluation details including diff --git a/seclai/_generated/models/generate_step_config_request.py b/seclai/_generated/models/generate_step_config_request.py index fed5801..023c886 100644 --- a/seclai/_generated/models/generate_step_config_request.py +++ b/seclai/_generated/models/generate_step_config_request.py @@ -24,7 +24,7 @@ class GenerateStepConfigRequest: """ Attributes: - step_type (str): The step type to generate config for (e.g. 'regex_replace', 'gate', 'text', 'prompt_call', + step_type (str): The step type to generate config for (e.g. 'regex_replace', 'if_else', 'text', 'prompt_call', 'retrieval'). user_input (str): Natural language description of what the step should do. agent_steps (list[GenerateStepConfigRequestAgentStepsType0Item] | None | Unset): Current agent step hierarchy diff --git a/seclai/_generated/models/knowledge_base_metadata_key_stats.py b/seclai/_generated/models/knowledge_base_metadata_key_stats.py new file mode 100644 index 0000000..7470ac6 --- /dev/null +++ b/seclai/_generated/models/knowledge_base_metadata_key_stats.py @@ -0,0 +1,83 @@ +from __future__ import annotations + +from collections.abc import Mapping +from typing import TYPE_CHECKING, Any, TypeVar + +from attrs import define as _attrs_define +from attrs import field as _attrs_field + +if TYPE_CHECKING: + from ..models.metadata_key_window_response import MetadataKeyWindowResponse + + +T = TypeVar("T", bound="KnowledgeBaseMetadataKeyStats") + + +@_attrs_define +class KnowledgeBaseMetadataKeyStats: + """ + Attributes: + knowledge_base_id (str): + windows (list[MetadataKeyWindowResponse]): + """ + + knowledge_base_id: str + windows: list[MetadataKeyWindowResponse] + additional_properties: dict[str, Any] = _attrs_field(init=False, factory=dict) + + def to_dict(self) -> dict[str, Any]: + knowledge_base_id = self.knowledge_base_id + + windows = [] + for windows_item_data in self.windows: + windows_item = windows_item_data.to_dict() + windows.append(windows_item) + + field_dict: dict[str, Any] = {} + field_dict.update(self.additional_properties) + field_dict.update( + { + "knowledge_base_id": knowledge_base_id, + "windows": windows, + } + ) + + return field_dict + + @classmethod + def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T: + from ..models.metadata_key_window_response import MetadataKeyWindowResponse + + d = dict(src_dict) + knowledge_base_id = d.pop("knowledge_base_id") + + windows = [] + _windows = d.pop("windows") + for windows_item_data in _windows: + windows_item = MetadataKeyWindowResponse.from_dict(windows_item_data) + + windows.append(windows_item) + + knowledge_base_metadata_key_stats = cls( + knowledge_base_id=knowledge_base_id, + windows=windows, + ) + + knowledge_base_metadata_key_stats.additional_properties = d + return knowledge_base_metadata_key_stats + + @property + def additional_keys(self) -> list[str]: + return list(self.additional_properties.keys()) + + def __getitem__(self, key: str) -> Any: + return self.additional_properties[key] + + def __setitem__(self, key: str, value: Any) -> None: + self.additional_properties[key] = value + + def __delitem__(self, key: str) -> None: + del self.additional_properties[key] + + def __contains__(self, key: str) -> bool: + return key in self.additional_properties diff --git a/seclai/_generated/models/metadata_key_count_response.py b/seclai/_generated/models/metadata_key_count_response.py new file mode 100644 index 0000000..d780819 --- /dev/null +++ b/seclai/_generated/models/metadata_key_count_response.py @@ -0,0 +1,99 @@ +from __future__ import annotations + +from collections.abc import Mapping +from typing import TYPE_CHECKING, Any, TypeVar + +from attrs import define as _attrs_define +from attrs import field as _attrs_field + +if TYPE_CHECKING: + from ..models.metadata_value_count_response import MetadataValueCountResponse + + +T = TypeVar("T", bound="MetadataKeyCountResponse") + + +@_attrs_define +class MetadataKeyCountResponse: + """ + Attributes: + distinct_values (int): How many different values it takes. + items (int): Items in the window carrying the key. + key (str): The item-metadata key. + top_values (list[MetadataValueCountResponse]): Its 5 most frequent values, most frequent first. + """ + + distinct_values: int + items: int + key: str + top_values: list[MetadataValueCountResponse] + additional_properties: dict[str, Any] = _attrs_field(init=False, factory=dict) + + def to_dict(self) -> dict[str, Any]: + distinct_values = self.distinct_values + + items = self.items + + key = self.key + + top_values = [] + for top_values_item_data in self.top_values: + top_values_item = top_values_item_data.to_dict() + top_values.append(top_values_item) + + field_dict: dict[str, Any] = {} + field_dict.update(self.additional_properties) + field_dict.update( + { + "distinct_values": distinct_values, + "items": items, + "key": key, + "top_values": top_values, + } + ) + + return field_dict + + @classmethod + def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T: + from ..models.metadata_value_count_response import MetadataValueCountResponse + + d = dict(src_dict) + distinct_values = d.pop("distinct_values") + + items = d.pop("items") + + key = d.pop("key") + + top_values = [] + _top_values = d.pop("top_values") + for top_values_item_data in _top_values: + top_values_item = MetadataValueCountResponse.from_dict(top_values_item_data) + + top_values.append(top_values_item) + + metadata_key_count_response = cls( + distinct_values=distinct_values, + items=items, + key=key, + top_values=top_values, + ) + + metadata_key_count_response.additional_properties = d + return metadata_key_count_response + + @property + def additional_keys(self) -> list[str]: + return list(self.additional_properties.keys()) + + def __getitem__(self, key: str) -> Any: + return self.additional_properties[key] + + def __setitem__(self, key: str, value: Any) -> None: + self.additional_properties[key] = value + + def __delitem__(self, key: str) -> None: + del self.additional_properties[key] + + def __contains__(self, key: str) -> bool: + return key in self.additional_properties diff --git a/seclai/_generated/models/metadata_key_declaration.py b/seclai/_generated/models/metadata_key_declaration.py new file mode 100644 index 0000000..7556aa1 --- /dev/null +++ b/seclai/_generated/models/metadata_key_declaration.py @@ -0,0 +1,63 @@ +from __future__ import annotations + +from collections.abc import Mapping +from typing import Any, TypeVar + +from attrs import define as _attrs_define + +from ..models.metadata_origin import MetadataOrigin +from ..types import UNSET, Unset + +T = TypeVar("T", bound="MetadataKeyDeclaration") + + +@_attrs_define +class MetadataKeyDeclaration: + """ + Attributes: + key (str): Steps reference the key as ``{{metadata.}}``. + origin (MetadataOrigin): Who writes a run metadata key (docs/architecture/run-metadata.md, Q2). + required (bool | Unset): A caller-started run without this key is refused. Only a ``custom`` key can be + required. Default: False. + """ + + key: str + origin: MetadataOrigin + required: bool | Unset = False + + def to_dict(self) -> dict[str, Any]: + key = self.key + + origin = self.origin.value + + required = self.required + + field_dict: dict[str, Any] = {} + + field_dict.update( + { + "key": key, + "origin": origin, + } + ) + if required is not UNSET: + field_dict["required"] = required + + return field_dict + + @classmethod + def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T: + d = dict(src_dict) + key = d.pop("key") + + origin = MetadataOrigin(d.pop("origin")) + + required = d.pop("required", UNSET) + + metadata_key_declaration = cls( + key=key, + origin=origin, + required=required, + ) + + return metadata_key_declaration diff --git a/seclai/_generated/models/metadata_key_window_response.py b/seclai/_generated/models/metadata_key_window_response.py new file mode 100644 index 0000000..9bab95f --- /dev/null +++ b/seclai/_generated/models/metadata_key_window_response.py @@ -0,0 +1,120 @@ +from __future__ import annotations + +import datetime +from collections.abc import Mapping +from typing import TYPE_CHECKING, Any, TypeVar, cast + +from attrs import define as _attrs_define +from attrs import field as _attrs_field +from dateutil.parser import isoparse + +from ..models.metadata_key_window_response_window import MetadataKeyWindowResponseWindow + +if TYPE_CHECKING: + from ..models.metadata_key_count_response import MetadataKeyCountResponse + + +T = TypeVar("T", bound="MetadataKeyWindowResponse") + + +@_attrs_define +class MetadataKeyWindowResponse: + """ + Attributes: + keys (list[MetadataKeyCountResponse]): Keys seen in the window, most frequent first. + since (datetime.datetime | None): The window's start; null for all time. + total_items (int): Items in the window. + window (MetadataKeyWindowResponseWindow): + """ + + keys: list[MetadataKeyCountResponse] + since: datetime.datetime | None + total_items: int + window: MetadataKeyWindowResponseWindow + additional_properties: dict[str, Any] = _attrs_field(init=False, factory=dict) + + def to_dict(self) -> dict[str, Any]: + keys = [] + for keys_item_data in self.keys: + keys_item = keys_item_data.to_dict() + keys.append(keys_item) + + since: None | str + if isinstance(self.since, datetime.datetime): + since = self.since.isoformat() + else: + since = self.since + + total_items = self.total_items + + window = self.window.value + + field_dict: dict[str, Any] = {} + field_dict.update(self.additional_properties) + field_dict.update( + { + "keys": keys, + "since": since, + "total_items": total_items, + "window": window, + } + ) + + return field_dict + + @classmethod + def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T: + from ..models.metadata_key_count_response import MetadataKeyCountResponse + + d = dict(src_dict) + keys = [] + _keys = d.pop("keys") + for keys_item_data in _keys: + keys_item = MetadataKeyCountResponse.from_dict(keys_item_data) + + keys.append(keys_item) + + def _parse_since(data: object) -> datetime.datetime | None: + if data is None: + return data + try: + if not isinstance(data, str): + raise TypeError() + since_type_0 = isoparse(data) + + return since_type_0 + except (TypeError, ValueError, AttributeError, KeyError): + pass + return cast(datetime.datetime | None, data) + + since = _parse_since(d.pop("since")) + + total_items = d.pop("total_items") + + window = MetadataKeyWindowResponseWindow(d.pop("window")) + + metadata_key_window_response = cls( + keys=keys, + since=since, + total_items=total_items, + window=window, + ) + + metadata_key_window_response.additional_properties = d + return metadata_key_window_response + + @property + def additional_keys(self) -> list[str]: + return list(self.additional_properties.keys()) + + def __getitem__(self, key: str) -> Any: + return self.additional_properties[key] + + def __setitem__(self, key: str, value: Any) -> None: + self.additional_properties[key] = value + + def __delitem__(self, key: str) -> None: + del self.additional_properties[key] + + def __contains__(self, key: str) -> bool: + return key in self.additional_properties diff --git a/seclai/_generated/models/metadata_key_window_response_window.py b/seclai/_generated/models/metadata_key_window_response_window.py new file mode 100644 index 0000000..5b9ce84 --- /dev/null +++ b/seclai/_generated/models/metadata_key_window_response_window.py @@ -0,0 +1,10 @@ +from enum import Enum + + +class MetadataKeyWindowResponseWindow(str, Enum): + ALL_TIME = "all_time" + LAST_30_DAYS = "last_30_days" + LAST_7_DAYS = "last_7_days" + + def __str__(self) -> str: + return str(self.value) diff --git a/seclai/_generated/models/metadata_keys_response.py b/seclai/_generated/models/metadata_keys_response.py new file mode 100644 index 0000000..d2024e2 --- /dev/null +++ b/seclai/_generated/models/metadata_keys_response.py @@ -0,0 +1,137 @@ +from __future__ import annotations + +from collections.abc import Mapping +from typing import TYPE_CHECKING, Any, TypeVar, cast +from uuid import UUID + +from attrs import define as _attrs_define +from attrs import field as _attrs_field + +from ..types import UNSET, Unset + +if TYPE_CHECKING: + from ..models.declarable_metadata_key import DeclarableMetadataKey + from ..models.metadata_key_declaration import MetadataKeyDeclaration + + +T = TypeVar("T", bound="MetadataKeysResponse") + + +@_attrs_define +class MetadataKeysResponse: + """ + Attributes: + accepts_any_source_key (bool): True for content triggers, which may declare any item-metadata key. + agent_id (UUID): + declarable_keys (list[DeclarableMetadataKey]): The system and source keys this trigger's type can declare. + metadata_keys (list[MetadataKeyDeclaration]): The keys the agent's steps may reference. Static trigger metadata + and Slack form fields are declared custom keys too, and are not repeated here. + trigger_id (UUID): + warnings (list[str] | Unset): Set by a PUT that changes the declaration: agents whose `call_agent` mapping no + longer fits it. Always empty on GET. + """ + + accepts_any_source_key: bool + agent_id: UUID + declarable_keys: list[DeclarableMetadataKey] + metadata_keys: list[MetadataKeyDeclaration] + trigger_id: UUID + warnings: list[str] | Unset = UNSET + additional_properties: dict[str, Any] = _attrs_field(init=False, factory=dict) + + def to_dict(self) -> dict[str, Any]: + accepts_any_source_key = self.accepts_any_source_key + + agent_id = str(self.agent_id) + + declarable_keys = [] + for declarable_keys_item_data in self.declarable_keys: + declarable_keys_item = declarable_keys_item_data.to_dict() + declarable_keys.append(declarable_keys_item) + + metadata_keys = [] + for metadata_keys_item_data in self.metadata_keys: + metadata_keys_item = metadata_keys_item_data.to_dict() + metadata_keys.append(metadata_keys_item) + + trigger_id = str(self.trigger_id) + + warnings: list[str] | Unset = UNSET + if not isinstance(self.warnings, Unset): + warnings = self.warnings + + field_dict: dict[str, Any] = {} + field_dict.update(self.additional_properties) + field_dict.update( + { + "accepts_any_source_key": accepts_any_source_key, + "agent_id": agent_id, + "declarable_keys": declarable_keys, + "metadata_keys": metadata_keys, + "trigger_id": trigger_id, + } + ) + if warnings is not UNSET: + field_dict["warnings"] = warnings + + return field_dict + + @classmethod + def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T: + from ..models.declarable_metadata_key import DeclarableMetadataKey + from ..models.metadata_key_declaration import MetadataKeyDeclaration + + d = dict(src_dict) + accepts_any_source_key = d.pop("accepts_any_source_key") + + agent_id = UUID(d.pop("agent_id")) + + declarable_keys = [] + _declarable_keys = d.pop("declarable_keys") + for declarable_keys_item_data in _declarable_keys: + declarable_keys_item = DeclarableMetadataKey.from_dict( + declarable_keys_item_data + ) + + declarable_keys.append(declarable_keys_item) + + metadata_keys = [] + _metadata_keys = d.pop("metadata_keys") + for metadata_keys_item_data in _metadata_keys: + metadata_keys_item = MetadataKeyDeclaration.from_dict( + metadata_keys_item_data + ) + + metadata_keys.append(metadata_keys_item) + + trigger_id = UUID(d.pop("trigger_id")) + + warnings = cast(list[str], d.pop("warnings", UNSET)) + + metadata_keys_response = cls( + accepts_any_source_key=accepts_any_source_key, + agent_id=agent_id, + declarable_keys=declarable_keys, + metadata_keys=metadata_keys, + trigger_id=trigger_id, + warnings=warnings, + ) + + metadata_keys_response.additional_properties = d + return metadata_keys_response + + @property + def additional_keys(self) -> list[str]: + return list(self.additional_properties.keys()) + + def __getitem__(self, key: str) -> Any: + return self.additional_properties[key] + + def __setitem__(self, key: str, value: Any) -> None: + self.additional_properties[key] = value + + def __delitem__(self, key: str) -> None: + del self.additional_properties[key] + + def __contains__(self, key: str) -> bool: + return key in self.additional_properties diff --git a/seclai/_generated/models/metadata_origin.py b/seclai/_generated/models/metadata_origin.py new file mode 100644 index 0000000..77faa11 --- /dev/null +++ b/seclai/_generated/models/metadata_origin.py @@ -0,0 +1,10 @@ +from enum import Enum + + +class MetadataOrigin(str, Enum): + CUSTOM = "custom" + SOURCE = "source" + SYSTEM = "system" + + def __str__(self) -> str: + return str(self.value) diff --git a/seclai/_generated/models/metadata_value_count_response.py b/seclai/_generated/models/metadata_value_count_response.py new file mode 100644 index 0000000..78c1cd0 --- /dev/null +++ b/seclai/_generated/models/metadata_value_count_response.py @@ -0,0 +1,69 @@ +from __future__ import annotations + +from collections.abc import Mapping +from typing import Any, TypeVar + +from attrs import define as _attrs_define +from attrs import field as _attrs_field + +T = TypeVar("T", bound="MetadataValueCountResponse") + + +@_attrs_define +class MetadataValueCountResponse: + """ + Attributes: + items (int): Items carrying this value. + value (str): The value as text, cut to 100 characters; an object is shown as {…} and a list as […]. + """ + + items: int + value: str + additional_properties: dict[str, Any] = _attrs_field(init=False, factory=dict) + + def to_dict(self) -> dict[str, Any]: + items = self.items + + value = self.value + + field_dict: dict[str, Any] = {} + field_dict.update(self.additional_properties) + field_dict.update( + { + "items": items, + "value": value, + } + ) + + return field_dict + + @classmethod + def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T: + d = dict(src_dict) + items = d.pop("items") + + value = d.pop("value") + + metadata_value_count_response = cls( + items=items, + value=value, + ) + + metadata_value_count_response.additional_properties = d + return metadata_value_count_response + + @property + def additional_keys(self) -> list[str]: + return list(self.additional_properties.keys()) + + def __getitem__(self, key: str) -> Any: + return self.additional_properties[key] + + def __setitem__(self, key: str, value: Any) -> None: + self.additional_properties[key] = value + + def __delitem__(self, key: str) -> None: + del self.additional_properties[key] + + def __contains__(self, key: str) -> bool: + return key in self.additional_properties diff --git a/seclai/_generated/models/set_metadata_keys_request.py b/seclai/_generated/models/set_metadata_keys_request.py new file mode 100644 index 0000000..d8e58be --- /dev/null +++ b/seclai/_generated/models/set_metadata_keys_request.py @@ -0,0 +1,77 @@ +from __future__ import annotations + +from collections.abc import Mapping +from typing import TYPE_CHECKING, Any, TypeVar + +from attrs import define as _attrs_define +from attrs import field as _attrs_field + +if TYPE_CHECKING: + from ..models.metadata_key_declaration import MetadataKeyDeclaration + + +T = TypeVar("T", bound="SetMetadataKeysRequest") + + +@_attrs_define +class SetMetadataKeysRequest: + """ + Attributes: + metadata_keys (list[MetadataKeyDeclaration]): The whole declaration; replaces the trigger's current one. + """ + + metadata_keys: list[MetadataKeyDeclaration] + additional_properties: dict[str, Any] = _attrs_field(init=False, factory=dict) + + def to_dict(self) -> dict[str, Any]: + metadata_keys = [] + for metadata_keys_item_data in self.metadata_keys: + metadata_keys_item = metadata_keys_item_data.to_dict() + metadata_keys.append(metadata_keys_item) + + field_dict: dict[str, Any] = {} + field_dict.update(self.additional_properties) + field_dict.update( + { + "metadata_keys": metadata_keys, + } + ) + + return field_dict + + @classmethod + def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T: + from ..models.metadata_key_declaration import MetadataKeyDeclaration + + d = dict(src_dict) + metadata_keys = [] + _metadata_keys = d.pop("metadata_keys") + for metadata_keys_item_data in _metadata_keys: + metadata_keys_item = MetadataKeyDeclaration.from_dict( + metadata_keys_item_data + ) + + metadata_keys.append(metadata_keys_item) + + set_metadata_keys_request = cls( + metadata_keys=metadata_keys, + ) + + set_metadata_keys_request.additional_properties = d + return set_metadata_keys_request + + @property + def additional_keys(self) -> list[str]: + return list(self.additional_properties.keys()) + + def __getitem__(self, key: str) -> Any: + return self.additional_properties[key] + + def __setitem__(self, key: str, value: Any) -> None: + self.additional_properties[key] = value + + def __delitem__(self, key: str) -> None: + del self.additional_properties[key] + + def __contains__(self, key: str) -> bool: + return key in self.additional_properties diff --git a/seclai/_generated/models/set_slack_trigger_config_api_request.py b/seclai/_generated/models/set_slack_trigger_config_api_request.py index f44603c..53aea0a 100644 --- a/seclai/_generated/models/set_slack_trigger_config_api_request.py +++ b/seclai/_generated/models/set_slack_trigger_config_api_request.py @@ -27,14 +27,16 @@ class SetSlackTriggerConfigApiRequest: Attributes: activation (None | SlackTriggerActivation | Unset): `everywhere` in scope, or `channel_opt_in`. + alias (None | str | Unset): The name people type after `/seclai` to run this agent: lowercase letters, digits + and hyphens, starting with a letter, unique in the Slack workspace. Generated from the agent's name when not set + or empty. allow_dms (bool | None | Unset): Runnable in the app's own DMs. channel_ids (list[str] | None | Unset): form (list[SetSlackTriggerConfigApiRequestFormType0Item] | None | Unset): Form fields `{key, label, type, required, hint, choices, max_length}`. `type`: short_text, long_text, number, single_choice, multi_choice, - yes_no, date, slack_user or slack_channel. Each value reaches the run as `{{metadata.}}`. + yes_no, date, slack_user or slack_channel. Each value reaches the run as `{{metadata.}}`, not in the run's + input, which is the text after `/seclai ` or the message the shortcut was used on, and its files. include_invoker_email (bool | None | Unset): - input_ (None | str | Unset): The trigger's input template. Each `{{metadata.}}` in it must be a form field - key or a platform key; it is checked together with `form`. max_turns (int | None | Unset): mcp_client_id (None | Unset | UUID): The account's connected Slack (Bot) MCP client. notify_failure_after_answer (bool | None | Unset): @@ -43,14 +45,16 @@ class SetSlackTriggerConfigApiRequest: turns_anyone (bool | None | Unset): turns_enabled (bool | None | Unset): visibility (None | SlackReplyVisibility | Unset): `channel`, or `private` (replies in the person's DM). + input_ (None | str | Unset): Deprecated: the trigger's former input template. The API ignores it; set `alias` to + choose the name people type after `/seclai`. """ activation: None | SlackTriggerActivation | Unset = UNSET + alias: None | str | Unset = UNSET allow_dms: bool | None | Unset = UNSET channel_ids: list[str] | None | Unset = UNSET form: list[SetSlackTriggerConfigApiRequestFormType0Item] | None | Unset = UNSET include_invoker_email: bool | None | Unset = UNSET - input_: None | str | Unset = UNSET max_turns: int | None | Unset = UNSET mcp_client_id: None | Unset | UUID = UNSET notify_failure_after_answer: bool | None | Unset = UNSET @@ -59,6 +63,7 @@ class SetSlackTriggerConfigApiRequest: turns_anyone: bool | None | Unset = UNSET turns_enabled: bool | None | Unset = UNSET visibility: None | SlackReplyVisibility | Unset = UNSET + input_: None | str | Unset = UNSET additional_properties: dict[str, Any] = _attrs_field(init=False, factory=dict) def to_dict(self) -> dict[str, Any]: @@ -70,6 +75,12 @@ def to_dict(self) -> dict[str, Any]: else: activation = self.activation + alias: None | str | Unset + if isinstance(self.alias, Unset): + alias = UNSET + else: + alias = self.alias + allow_dms: bool | None | Unset if isinstance(self.allow_dms, Unset): allow_dms = UNSET @@ -103,12 +114,6 @@ def to_dict(self) -> dict[str, Any]: else: include_invoker_email = self.include_invoker_email - input_: None | str | Unset - if isinstance(self.input_, Unset): - input_ = UNSET - else: - input_ = self.input_ - max_turns: int | None | Unset if isinstance(self.max_turns, Unset): max_turns = UNSET @@ -163,11 +168,19 @@ def to_dict(self) -> dict[str, Any]: else: visibility = self.visibility + input_: None | str | Unset + if isinstance(self.input_, Unset): + input_ = UNSET + else: + input_ = self.input_ + field_dict: dict[str, Any] = {} field_dict.update(self.additional_properties) field_dict.update({}) if activation is not UNSET: field_dict["activation"] = activation + if alias is not UNSET: + field_dict["alias"] = alias if allow_dms is not UNSET: field_dict["allow_dms"] = allow_dms if channel_ids is not UNSET: @@ -176,8 +189,6 @@ def to_dict(self) -> dict[str, Any]: field_dict["form"] = form if include_invoker_email is not UNSET: field_dict["include_invoker_email"] = include_invoker_email - if input_ is not UNSET: - field_dict["input"] = input_ if max_turns is not UNSET: field_dict["max_turns"] = max_turns if mcp_client_id is not UNSET: @@ -194,6 +205,8 @@ def to_dict(self) -> dict[str, Any]: field_dict["turns_enabled"] = turns_enabled if visibility is not UNSET: field_dict["visibility"] = visibility + if input_ is not UNSET: + field_dict["input"] = input_ return field_dict @@ -222,6 +235,15 @@ def _parse_activation(data: object) -> None | SlackTriggerActivation | Unset: activation = _parse_activation(d.pop("activation", UNSET)) + def _parse_alias(data: object) -> None | str | Unset: + if data is None: + return data + if isinstance(data, Unset): + return data + return cast(None | str | Unset, data) + + alias = _parse_alias(d.pop("alias", UNSET)) + def _parse_allow_dms(data: object) -> bool | None | Unset: if data is None: return data @@ -289,15 +311,6 @@ def _parse_include_invoker_email(data: object) -> bool | None | Unset: d.pop("include_invoker_email", UNSET) ) - def _parse_input_(data: object) -> None | str | Unset: - if data is None: - return data - if isinstance(data, Unset): - return data - return cast(None | str | Unset, data) - - input_ = _parse_input_(d.pop("input", UNSET)) - def _parse_max_turns(data: object) -> int | None | Unset: if data is None: return data @@ -398,13 +411,22 @@ def _parse_visibility(data: object) -> None | SlackReplyVisibility | Unset: visibility = _parse_visibility(d.pop("visibility", UNSET)) + def _parse_input_(data: object) -> None | str | Unset: + if data is None: + return data + if isinstance(data, Unset): + return data + return cast(None | str | Unset, data) + + input_ = _parse_input_(d.pop("input", UNSET)) + set_slack_trigger_config_api_request = cls( activation=activation, + alias=alias, allow_dms=allow_dms, channel_ids=channel_ids, form=form, include_invoker_email=include_invoker_email, - input_=input_, max_turns=max_turns, mcp_client_id=mcp_client_id, notify_failure_after_answer=notify_failure_after_answer, @@ -413,6 +435,7 @@ def _parse_visibility(data: object) -> None | SlackReplyVisibility | Unset: turns_anyone=turns_anyone, turns_enabled=turns_enabled, visibility=visibility, + input_=input_, ) set_slack_trigger_config_api_request.additional_properties = d diff --git a/seclai/_generated/models/slack_trigger_config_api_response.py b/seclai/_generated/models/slack_trigger_config_api_response.py index 20e5704..26512f8 100644 --- a/seclai/_generated/models/slack_trigger_config_api_response.py +++ b/seclai/_generated/models/slack_trigger_config_api_response.py @@ -7,6 +7,8 @@ from attrs import define as _attrs_define from attrs import field as _attrs_field +from ..types import UNSET, Unset + if TYPE_CHECKING: from ..models.slack_trigger_config_api_response_form_item import ( SlackTriggerConfigApiResponseFormItem, @@ -37,6 +39,7 @@ class SlackTriggerConfigApiResponse: turns_anyone (bool): turns_enabled (bool): visibility (str): + alias (None | str | Unset): The name people type after `/seclai` to run this agent. """ activation: str @@ -56,6 +59,7 @@ class SlackTriggerConfigApiResponse: turns_anyone: bool turns_enabled: bool visibility: str + alias: None | str | Unset = UNSET additional_properties: dict[str, Any] = _attrs_field(init=False, factory=dict) def to_dict(self) -> dict[str, Any]: @@ -102,6 +106,12 @@ def to_dict(self) -> dict[str, Any]: visibility = self.visibility + alias: None | str | Unset + if isinstance(self.alias, Unset): + alias = UNSET + else: + alias = self.alias + field_dict: dict[str, Any] = {} field_dict.update(self.additional_properties) field_dict.update( @@ -125,6 +135,8 @@ def to_dict(self) -> dict[str, Any]: "visibility": visibility, } ) + if alias is not UNSET: + field_dict["alias"] = alias return field_dict @@ -197,6 +209,15 @@ def _parse_slack_team_id(data: object) -> None | str: visibility = d.pop("visibility") + def _parse_alias(data: object) -> None | str | Unset: + if data is None: + return data + if isinstance(data, Unset): + return data + return cast(None | str | Unset, data) + + alias = _parse_alias(d.pop("alias", UNSET)) + slack_trigger_config_api_response = cls( activation=activation, agent_id=agent_id, @@ -215,6 +236,7 @@ def _parse_slack_team_id(data: object) -> None | str: turns_anyone=turns_anyone, turns_enabled=turns_enabled, visibility=visibility, + alias=alias, ) slack_trigger_config_api_response.additional_properties = d diff --git a/seclai/_generated/models/update_agent_request.py b/seclai/_generated/models/update_agent_request.py index 573a23c..fec5365 100644 --- a/seclai/_generated/models/update_agent_request.py +++ b/seclai/_generated/models/update_agent_request.py @@ -39,13 +39,13 @@ class UpdateAgentRequest: description (None | str | Unset): New description for the agent. entity_remap (None | Unset | UpdateAgentRequestEntityRemapType0): Optional UUID-substitution map applied to the imported workflow before save (same shape as on POST /agents). - evaluation_mode (None | str | Unset): Evaluation mode: 'output_expectation', 'eval_and_retry', or - 'sample_and_flag'. + evaluation_mode (None | str | Unset): Evaluation mode: 'output_expectation' or 'sample_and_flag'. From Seclai- + Version 2026-11-04 'eval_and_retry' returns 400; earlier versions store it as 'sample_and_flag'. max_credits_per_period (float | None | Unset): Credit limit per billing period of the paying account: once reached, runs stop at their next step and new runs are refused. max_credits_per_run (float | None | Unset): Credit limit per run: a run that reaches it is stopped before its next step. - max_retries (int | None | Unset): Max retries for eval_and_retry mode (1-10). + max_retries (int | None | Unset): Deprecated: accepted and has no effect. max_runs_per_day (int | None | Unset): Runs per day; at most the plan's run quota. max_runs_per_hour (int | None | Unset): Runs per hour; at most the plan's run quota. max_runs_total (int | None | Unset): Runs in total; once reached, new runs are refused. @@ -53,10 +53,11 @@ class UpdateAgentRequest: prompt_model_auto_rollback_enabled (bool | None | Unset): Enable or disable automatic rollback for upgraded models. prompt_model_auto_rollback_triggers (list[str] | None | Unset): Failure signals that trigger rollback: - agent_eval_fail, governance_flag, governance_block, agent_run_failed. + governance_flag, governance_block, agent_run_failed. agent_eval_fail is accepted and never fires; in the list, a + run with a failed evaluation is never picked as the rollback target. prompt_model_auto_upgrade_strategy (None | PromptModelAutoUpgradeStrategy | Unset): Auto-upgrade strategy: none, early_adopter, middle_of_road, cautious_adopter. - retry_on_failure (bool | None | Unset): Whether to retry on evaluation failure. + retry_on_failure (bool | None | Unset): Deprecated: accepted and has no effect. sampling_config (None | Unset | UpdateAgentRequestSamplingConfigType0): Sampling configuration for sample_and_flag mode. Format: {combinator: 'and'|'or', rules: [...]}. set_default_evaluation_tier (bool | Unset): When true and default_evaluation_tier is omitted, clears the tier to diff --git a/seclai/_generated/models/update_evaluation_criteria_request.py b/seclai/_generated/models/update_evaluation_criteria_request.py index fa2f1c7..a9a4b6c 100644 --- a/seclai/_generated/models/update_evaluation_criteria_request.py +++ b/seclai/_generated/models/update_evaluation_criteria_request.py @@ -22,7 +22,7 @@ class UpdateEvaluationCriteriaRequest: """Request body for updating an evaluation criteria. - Retry settings and sample frequency are set at the agent level. + The evaluation mode and sample frequency are set at the agent level. Attributes: description (None | str | Unset): diff --git a/seclai/seclai.py b/seclai/seclai.py index e2535ff..823afef 100644 --- a/seclai/seclai.py +++ b/seclai/seclai.py @@ -42,7 +42,14 @@ import mimetypes import os import time -from collections.abc import AsyncGenerator, Awaitable, Callable, Generator, Mapping +from collections.abc import ( + AsyncGenerator, + Awaitable, + Callable, + Generator, + Mapping, + Sequence, +) from dataclasses import dataclass from http import HTTPStatus from io import BytesIO @@ -62,6 +69,7 @@ import httpx from seclai._generated.client import Client as GeneratedClient +from seclai._generated.models.accepted_attachment_slot import AcceptedAttachmentSlot from seclai._generated.models.accepted_attachments_response import ( AcceptedAttachmentsResponse, ) @@ -83,6 +91,11 @@ ) from seclai._generated.models.file_upload_response import FileUploadResponse from seclai._generated.models.http_validation_error import HTTPValidationError +from seclai._generated.models.knowledge_base_metadata_key_stats import ( + KnowledgeBaseMetadataKeyStats, +) +from seclai._generated.models.metadata_key_declaration import MetadataKeyDeclaration +from seclai._generated.models.metadata_keys_response import MetadataKeysResponse from seclai._generated.models.source_list_response import SourceListResponse from seclai._generated.types import UNSET, Unset from seclai._generated.types import Response as OpenAPIResponse @@ -418,16 +431,31 @@ def __init__( class SeclaiStreamingError(SeclaiError): """Raised when an error event is received during a streaming agent run. + ``run_streaming_agent_and_wait`` also raises it when the run did not + finish: on its timeout, and with ``raise_on_incomplete`` when the stream + ends or is cut before the ``done`` event. ``run`` then holds the latest + snapshot. + Attributes: message: Human-readable error message from the stream. run_id: Agent run identifier, if available. + run: The latest run snapshot received before the stream stopped: the + ``result`` one if it arrived (its ``output`` is the answer), else + the ``init`` one, else ``None``. """ - def __init__(self, message: str, *, run_id: str | None = None) -> None: - """Initialize with stream error message and optional run ID.""" + def __init__( + self, + message: str, + *, + run_id: str | None = None, + run: AgentRunResponse | None = None, + ) -> None: + """Initialize with stream error message, optional run ID and snapshot.""" super().__init__(message) self.message = message self.run_id = run_id + self.run = run def _guess_mime_type(file_name: str | None) -> str | None: @@ -1208,30 +1236,61 @@ def run_streaming_agent_and_wait( *, timeout: float | None = None, headers: Mapping[str, str] | None = None, + return_on_result: bool = False, + raise_on_incomplete: bool = False, ) -> AgentRunResponse: """Run an agent via SSE streaming and block until completion. - This uses POST /agents/{agent_id}/runs/stream and consumes Server-Sent Events (SSE). - The method returns when an `event: done` message is received. Every event - but `init` and `done` is discarded, so `include_reasoning` is removed - from the body before it is sent: reasoning events would only add - traffic and count against `timeout`. Use `run_streaming_agent` to - receive `stream_reasoning` events. + This uses POST /agents/{agent_id}/runs/stream and consumes Server-Sent + Events (SSE). The method returns the run from the ``done`` event, or, + with ``return_on_result``, the snapshot from the ``result`` event. + + By default, when the stream ends before ``done`` it returns the latest + snapshot, which may be a run that has not finished: check ``status`` + and ``result_reported_at``. A connection cut mid-stream raises the + ``httpx`` error. Pass ``raise_on_incomplete=True`` (recommended; the + default in the next major version) to raise + :class:`SeclaiStreamingError` instead, with the latest snapshot in + ``run`` (the ``result`` one if it arrived, so its ``output`` is the + answer). On ``timeout`` it raises :class:`SeclaiStreamingError` with + ``run`` either way. + + Every event but ``init``, ``result`` and ``done`` is discarded, so + ``include_reasoning`` is removed from the body before it is sent: + reasoning events would only add traffic and count against + ``timeout``. Use ``run_streaming_agent`` to receive + ``stream_reasoning`` events. Args: agent_id: Agent identifier. body: Streaming agent run request payload. - timeout: Max time (seconds) to wait for the final result (client-side). Defaults to this - client's configured timeout. + timeout: Max time (seconds) to wait for the final result + (client-side). Defaults to this client's configured timeout. headers: Optional extra headers for this request. + return_on_result: Return the ``result`` snapshot as soon as it + arrives, without waiting for ``done``. That run may still be + in progress: its ``status`` may not be terminal and it can + still fail, so check ``result_reported_at``, not ``status``. + raise_on_incomplete: Raise :class:`SeclaiStreamingError` when the + stream ends or is cut before ``done``, rather than returning + the latest snapshot or letting the ``httpx`` error through. + Becomes the default in the next major version. Returns: - The final agent run payload from the `done` event. + The run from the ``done`` event, or with ``return_on_result`` the + ``result`` snapshot. Without ``raise_on_incomplete``, the latest + snapshot when the stream ends before ``done``. Raises: SeclaiAPIValidationError: If the API returns a validation error. SeclaiAPIStatusError: If the API returns a non-success status code. - SeclaiError: If the stream ends early or times out. + SeclaiStreamingError: If ``timeout`` passes before the run + finished, or the stream ends with no snapshot; with + ``raise_on_incomplete``, also if the stream ends or is cut + before ``done``. ``run`` holds the latest snapshot, or + ``None`` if none arrived. + httpx.TransportError: Without ``raise_on_incomplete``, if the + connection is cut mid-stream. """ import json as _json import time as _time @@ -1246,8 +1305,42 @@ def run_streaming_agent_and_wait( _setdefault_header(merged_headers, "accept", "text/event-stream") timeout_seconds = self._options.timeout if timeout is None else timeout + timed_out = f"Timed out after {timeout_seconds}s waiting for streaming agent run to complete" start = _time.monotonic() + current_event: str | None = None + data_lines: list[str] = [] + last_seen: AgentRunResponse | None = None + result_seen: AgentRunResponse | None = None + + def dispatch() -> AgentRunResponse | None: + """Handle the buffered event; return the run to return, if any.""" + nonlocal current_event, data_lines, last_seen, result_seen + if current_event is None and not data_lines: + return None + data = "\n".join(data_lines) + evt = current_event + current_event = None + data_lines = [] + if not data: + return None + if evt not in {"init", "result", "done"}: + return None + try: + parsed_dict = cast(dict[str, Any], _json.loads(data)) + parsed = AgentRunResponse.from_dict(parsed_dict) + except Exception: + return None + last_seen = parsed + if evt == "result": + result_seen = parsed + if return_on_result: + return parsed + if evt == "done": + return parsed + return None + ending: str | None = None # None: the stream ended + cause: httpx.TransportError | None = None try: with self._client.stream( "POST", @@ -1259,63 +1352,54 @@ def run_streaming_agent_and_wait( # Lazy body inside `stream()`; read it so the error carries # its text and a 422 its field-level detail. _raise_for_unread_status(response) - - current_event: str | None = None - data_lines: list[str] = [] - last_seen: AgentRunResponse | None = None - - def dispatch() -> AgentRunResponse | None: - nonlocal current_event, data_lines, last_seen - if current_event is None and not data_lines: - return None - data = "\n".join(data_lines) - evt = current_event - current_event = None - data_lines = [] - if not data: - return None - if evt not in {"init", "done"}: - return None - try: - parsed_dict = cast(dict[str, Any], _json.loads(data)) - parsed = AgentRunResponse.from_dict(parsed_dict) - last_seen = parsed - if evt == "done": - return parsed - except Exception: - return None - return None - - for line in response.iter_lines(): - if _time.monotonic() - start > timeout_seconds: - raise SeclaiError( - f"Timed out after {timeout_seconds}s waiting for streaming agent run to complete." - ) - - if line == "": - done = dispatch() - if done is not None: - return done - continue - if line.startswith(":"): - continue - if line.startswith("event:"): - current_event = line[len("event:") :].strip() or None - continue - if line.startswith("data:"): - data_lines.append(line[len("data:") :].lstrip()) - continue - - done = dispatch() - if done is not None: - return done - if last_seen is not None: - return last_seen - raise SeclaiError("Stream ended before receiving a 'done' event.") + try: + for line in response.iter_lines(): + if line == "": + run = dispatch() + if run is not None: + return run + elif line.startswith("event:"): + current_event = line[len("event:") :].strip() or None + elif line.startswith("data:"): + data_lines.append(line[len("data:") :].lstrip()) + # Checked after every line is handled; the event + # buffered so far is dispatched below, so a `done` + # whose lines were read by the deadline still counts. + if _time.monotonic() - start > timeout_seconds: + ending = timed_out + break + except httpx.TransportError as e: + if not raise_on_incomplete and not isinstance( + e, httpx.TimeoutException + ): + raise # as released: the cut surfaces raw + cause = e + ending = ( + timed_out + if isinstance(e, httpx.TimeoutException) + else f"The stream was cut ({type(e).__name__}: {e})" + ) except httpx.TimeoutException as e: - raise SeclaiError( - f"Timed out after {timeout_seconds}s waiting for streaming agent run to complete." - ) from e + cause = e + ending = timed_out + + # An event whose blank line never came (EOF, timeout) still counts. + run = dispatch() + if run is not None: + return run + if ending is None and not raise_on_incomplete and last_seen is not None: + return last_seen # as released + snapshot = result_seen if result_seen is not None else last_seen + outcome = ( + "the run had reported its result; read it from the error's `run`" + if result_seen is not None + else "the run had not reported a result" + ) + raise SeclaiStreamingError( + f"{ending or 'The stream ended'} before the 'done' event: {outcome}.", + run_id=snapshot.run_id if snapshot is not None else None, + run=snapshot, + ) from cause def list_agent_runs( self, agent_id: str, *, page: int = 1, limit: int = 50 @@ -3391,10 +3475,18 @@ def set_slack_trigger_config( Args: agent_id: Agent identifier. trigger_id: Trigger identifier. - body: Fields to set (mcp_client_id, form, scope, channel_ids, - allow_dms, activation, visibility, start_without_form, input, - turns_enabled, turns_anyone, max_turns, include_invoker_email, - notify_failure_after_answer). Omitted fields are unchanged. + body: Fields to set (mcp_client_id, alias, form, scope, + channel_ids, allow_dms, activation, visibility, + start_without_form, turns_enabled, turns_anyone, max_turns, + include_invoker_email, notify_failure_after_answer). Omitted + fields are unchanged. ``alias`` is the name people type after + ``/seclai`` to run this agent; it is generated from the agent's + name when not set. A run's input is the text after + ``/seclai ``, or the message the shortcut was used on; + form values reach it as ``{{metadata.}}``. + Deprecated: ``input``, the trigger's input template; the API + ignores it. A body that still sets it is sent as given, so + existing callers keep working. Returns: The trigger's Slack config, with ``missing_scopes`` listing what the @@ -3413,7 +3505,9 @@ def set_accepted_attachments( self, agent_id: str, trigger_id: str, - accepted_attachments: list[dict[str, Any]] | None, + accepted_attachments: ( + Sequence[AcceptedAttachmentSlot | Mapping[str, Any]] | None + ), ) -> AcceptedAttachmentsResponse: """Declare the input attachments a trigger accepts. @@ -3428,8 +3522,9 @@ def set_accepted_attachments( trigger_id: Trigger identifier, as :meth:`get_agent` returns it. accepted_attachments: The attachments, each with a ``name`` and optional ``label``, ``content_types``, ``name_pattern``, ``min`` - and ``max``. ``None`` accepts any files, as one attachment named - ``files``. Sent as given, so ``None`` is sent as ``null``. + and ``max``, as dicts or as the ``AcceptedAttachmentSlot`` + models a response returns. ``None`` accepts any files, as one + attachment named ``files``, and is sent as ``null``. Returns: The trigger's ``accepted_attachments`` with its ``agent_id`` and @@ -3440,7 +3535,20 @@ def set_accepted_attachments( SeclaiAPIStatusError: If the API returns a non-success status code. SeclaiError: If the response body does not decode as the model. """ - body: dict[str, Any] = {"accepted_attachments": accepted_attachments} + body: dict[str, Any] = { + "accepted_attachments": ( + None + if accepted_attachments is None + else [ + ( + slot.to_dict() + if isinstance(slot, AcceptedAttachmentSlot) + else dict(slot) + ) + for slot in accepted_attachments + ] + ) + } payload = self.request( "PUT", f"/agents/{agent_id}/triggers/{trigger_id}/accepted-attachments", @@ -3448,6 +3556,86 @@ def set_accepted_attachments( ) return _parse_model(payload, AcceptedAttachmentsResponse) + def get_metadata_keys( + self, + agent_id: str, + trigger_id: str, + ) -> MetadataKeysResponse: + """Get the run metadata keys a trigger declares. + + Steps reference a declared key as ``{{metadata.}}``. ``system`` + and ``source`` keys are written by the platform and are never required; + ``custom`` keys are sent by the caller. A run you start is refused with + a 400 when it lacks a required key or sends a custom key the trigger + does not declare. + + Args: + agent_id: Agent identifier. + trigger_id: Trigger identifier, as :meth:`get_agent` returns it. + + Returns: + The trigger's ``metadata_keys``, the ``declarable_keys`` its type + offers, and ``accepts_any_source_key``. ``warnings`` is always + empty here. + + Raises: + SeclaiAPIValidationError: If the API returns a validation error. + SeclaiAPIStatusError: If the API returns a non-success status code. + SeclaiError: If the response body does not decode as the model. + """ + payload = self.request( + "GET", + f"/agents/{agent_id}/triggers/{trigger_id}/metadata-keys", + ) + return _parse_model(payload, MetadataKeysResponse) + + def set_metadata_keys( + self, + agent_id: str, + trigger_id: str, + metadata_keys: Sequence[MetadataKeyDeclaration | Mapping[str, Any]], + ) -> MetadataKeysResponse: + """Declare the run metadata keys a trigger accepts. + + Replaces the trigger's whole declaration. The API answers 400 when the + agent references a key that no trigger of its branch then declares. + + Args: + agent_id: Agent identifier. + trigger_id: Trigger identifier, as :meth:`get_agent` returns it. + metadata_keys: The keys, each with a ``key``, an ``origin`` + (``system``, ``source`` or ``custom``) and an optional + ``required`` (default ``False``; only a ``custom`` key can be + required), as dicts or as the ``MetadataKeyDeclaration`` + models :meth:`get_metadata_keys` returns, so its + ``metadata_keys`` can be edited and sent back. ``[]`` declares + none. + + Returns: + The new declaration, as :meth:`get_metadata_keys` returns it. + ``warnings``, when the API sends it, names agents whose + ``call_agent`` mapping no longer fits it; it is ``UNSET`` when + omitted, so check ``isinstance(result.warnings, Unset)`` first + (``from seclai import Unset``). + + Raises: + SeclaiAPIValidationError: If the API returns a validation error. + SeclaiAPIStatusError: If the API returns a non-success status code. + SeclaiError: If the response body does not decode as the model. + """ + body: dict[str, Any] = { + "metadata_keys": [ + key.to_dict() if isinstance(key, MetadataKeyDeclaration) else dict(key) + for key in metadata_keys + ] + } + payload = self.request( + "PUT", + f"/agents/{agent_id}/triggers/{trigger_id}/metadata-keys", + json=body, + ) + return _parse_model(payload, MetadataKeysResponse) + # ── Knowledge Bases ─────────────────────────────────────────────────────── def list_knowledge_bases( @@ -3541,6 +3729,34 @@ def delete_knowledge_base(self, knowledge_base_id: str) -> None: """ self.request("DELETE", f"/knowledge_bases/{knowledge_base_id}") + def get_knowledge_base_metadata_key_stats( + self, knowledge_base_id: str + ) -> KnowledgeBaseMetadataKeyStats: + """Count the item-metadata keys on a knowledge base's content. + + For choosing the keys a content trigger declares + (:meth:`set_metadata_keys`). Each item is counted once, at its latest + version; a null value counts as absent, and reserved and + platform-set keys are left out. + + Args: + knowledge_base_id: Knowledge base identifier. + + Returns: + One entry in ``windows`` per window (``all_time``, + ``last_30_days``, ``last_7_days``), each with ``total_items`` and + its ``keys``, most frequent first, with their top values. + + Raises: + SeclaiAPIValidationError: If the API returns a validation error. + SeclaiAPIStatusError: If the API returns a non-success status code. + SeclaiError: If the response body does not decode as the model. + """ + payload = self.request( + "GET", f"/knowledge_bases/{knowledge_base_id}/metadata-key-stats" + ) + return _parse_model(payload, KnowledgeBaseMetadataKeyStats) + # ── Memory Banks ────────────────────────────────────────────────────────── def list_memory_banks( @@ -5678,27 +5894,48 @@ def run_agent_and_poll( *, poll_interval: float = 2.0, include_step_outputs: bool = False, + return_on_result: bool = False, ) -> AgentRunResponse: """Run an agent and poll until it reaches a terminal status. Starts the agent run and then repeatedly polls ``get_agent_run`` until - the status is ``"completed"`` or ``"failed"``. + the status is ``"completed"`` or ``"failed"``, or, with + ``return_on_result``, until the run has reported its result. Args: agent_id: Agent identifier. body: Agent run request payload. poll_interval: Seconds between poll attempts (default 2.0). - include_step_outputs: Include per-step outputs when polling. + include_step_outputs: Include per-step outputs when polling. When + the ``run_agent`` response would already end the poll, the + run is fetched once more with them, since that response + carries no step outputs. + return_on_result: Return as soon as a snapshot has + ``result_reported_at`` set: its ``output`` is the answer, and + for an agent whose ``report_success`` is ``on_result`` that can + be before later steps finish. The run's ``status`` may then + still be ``"processing"``, and the run can still fail after + its result. A terminal status is returned at once either way. Returns: - The final agent run (completed or failed). + The final agent run (completed or failed), or with + ``return_on_result`` the first snapshot that reported its result. Raises: SeclaiAPIValidationError: If the API returns a validation error. SeclaiAPIStatusError: If the API returns a non-success status code. """ run = self.run_agent(agent_id, body) - while run.status not in ("completed", "failed"): + if include_step_outputs and ( + run.status in ("completed", "failed") + or (return_on_result and run.result_reported_at) + ): + # The run_agent response carries no step outputs, so it must not + # end the poll: fetch the run with them and check that instead. + run = self.get_agent_run(run.run_id, include_step_outputs=True) + while run.status not in ("completed", "failed") and not ( + return_on_result and run.result_reported_at + ): time.sleep(poll_interval) run = self.get_agent_run( run.run_id, include_step_outputs=include_step_outputs @@ -5716,7 +5953,13 @@ def run_streaming_agent( """Run an agent via SSE streaming, yielding events as they arrive. This is a generator that yields ``(event_type, data)`` tuples for each - SSE event received. Event types include ``"init"`` and ``"done"``. + SSE event received. Event types include ``"init"`` (the first run + snapshot), ``"result"`` (the snapshot once the run has reported its + result: ``result_reported_at`` is set and ``output`` is the answer; it + can arrive while later steps still run) and ``"done"`` (the terminal + snapshot). Callers who only need the answer can stop at ``"result"``; + ``"done"`` says whether the whole run succeeded, which can still fail + after its result. Args: agent_id: Agent identifier. @@ -6077,15 +6320,61 @@ async def run_streaming_agent_and_wait( *, timeout: float | None = None, headers: Mapping[str, str] | None = None, + return_on_result: bool = False, + raise_on_incomplete: bool = False, ) -> AgentRunResponse: """Run an agent via SSE streaming and block until completion (async). - This uses POST /agents/{agent_id}/runs/stream and consumes Server-Sent Events (SSE). - The method returns when an `event: done` message is received. Every event - but `init` and `done` is discarded, so `include_reasoning` is removed - from the body before it is sent: reasoning events would only add - traffic and count against `timeout`. Use `run_streaming_agent` to - receive `stream_reasoning` events. + This uses POST /agents/{agent_id}/runs/stream and consumes Server-Sent + Events (SSE). The method returns the run from the ``done`` event, or, + with ``return_on_result``, the snapshot from the ``result`` event. + + By default, when the stream ends before ``done`` it returns the latest + snapshot, which may be a run that has not finished: check ``status`` + and ``result_reported_at``. A connection cut mid-stream raises the + ``httpx`` error. Pass ``raise_on_incomplete=True`` (recommended; the + default in the next major version) to raise + :class:`SeclaiStreamingError` instead, with the latest snapshot in + ``run`` (the ``result`` one if it arrived, so its ``output`` is the + answer). On ``timeout`` it raises :class:`SeclaiStreamingError` with + ``run`` either way. + + Every event but ``init``, ``result`` and ``done`` is discarded, so + ``include_reasoning`` is removed from the body before it is sent: + reasoning events would only add traffic and count against + ``timeout``. Use ``run_streaming_agent`` to receive + ``stream_reasoning`` events. + + Args: + agent_id: Agent identifier. + body: Streaming agent run request payload. + timeout: Max time (seconds) to wait for the final result + (client-side). Defaults to this client's configured timeout. + headers: Optional extra headers for this request. + return_on_result: Return the ``result`` snapshot as soon as it + arrives, without waiting for ``done``. That run may still be + in progress: its ``status`` may not be terminal and it can + still fail, so check ``result_reported_at``, not ``status``. + raise_on_incomplete: Raise :class:`SeclaiStreamingError` when the + stream ends or is cut before ``done``, rather than returning + the latest snapshot or letting the ``httpx`` error through. + Becomes the default in the next major version. + + Returns: + The run from the ``done`` event, or with ``return_on_result`` the + ``result`` snapshot. Without ``raise_on_incomplete``, the latest + snapshot when the stream ends before ``done``. + + Raises: + SeclaiAPIValidationError: If the API returns a validation error. + SeclaiAPIStatusError: If the API returns a non-success status code. + SeclaiStreamingError: If ``timeout`` passes before the run + finished, or the stream ends with no snapshot; with + ``raise_on_incomplete``, also if the stream ends or is cut + before ``done``. ``run`` holds the latest snapshot, or + ``None`` if none arrived. + httpx.TransportError: Without ``raise_on_incomplete``, if the + connection is cut mid-stream. """ import json as _json import time as _time @@ -6100,8 +6389,42 @@ async def run_streaming_agent_and_wait( _setdefault_header(merged_headers, "accept", "text/event-stream") timeout_seconds = self._options.timeout if timeout is None else timeout + timed_out = f"Timed out after {timeout_seconds}s waiting for streaming agent run to complete" start = _time.monotonic() + current_event: str | None = None + data_lines: list[str] = [] + last_seen: AgentRunResponse | None = None + result_seen: AgentRunResponse | None = None + + def dispatch() -> AgentRunResponse | None: + """Handle the buffered event; return the run to return, if any.""" + nonlocal current_event, data_lines, last_seen, result_seen + if current_event is None and not data_lines: + return None + data = "\n".join(data_lines) + evt = current_event + current_event = None + data_lines = [] + if not data: + return None + if evt not in {"init", "result", "done"}: + return None + try: + parsed_dict = cast(dict[str, Any], _json.loads(data)) + parsed = AgentRunResponse.from_dict(parsed_dict) + except Exception: + return None + last_seen = parsed + if evt == "result": + result_seen = parsed + if return_on_result: + return parsed + if evt == "done": + return parsed + return None + ending: str | None = None # None: the stream ended + cause: httpx.TransportError | None = None try: async with self._client.stream( "POST", @@ -6113,63 +6436,54 @@ async def run_streaming_agent_and_wait( # Lazy body inside `stream()`; read it so the error carries # its text and a 422 its field-level detail. await _araise_for_unread_status(response) - - current_event: str | None = None - data_lines: list[str] = [] - last_seen: AgentRunResponse | None = None - - def dispatch() -> AgentRunResponse | None: - nonlocal current_event, data_lines, last_seen - if current_event is None and not data_lines: - return None - data = "\n".join(data_lines) - evt = current_event - current_event = None - data_lines = [] - if not data: - return None - if evt not in {"init", "done"}: - return None - try: - parsed_dict = cast(dict[str, Any], _json.loads(data)) - parsed = AgentRunResponse.from_dict(parsed_dict) - last_seen = parsed - if evt == "done": - return parsed - except Exception: - return None - return None - - async for line in response.aiter_lines(): - if _time.monotonic() - start > timeout_seconds: - raise SeclaiError( - f"Timed out after {timeout_seconds}s waiting for streaming agent run to complete." - ) - - if line == "": - done = dispatch() - if done is not None: - return done - continue - if line.startswith(":"): - continue - if line.startswith("event:"): - current_event = line[len("event:") :].strip() or None - continue - if line.startswith("data:"): - data_lines.append(line[len("data:") :].lstrip()) - continue - - done = dispatch() - if done is not None: - return done - if last_seen is not None: - return last_seen - raise SeclaiError("Stream ended before receiving a 'done' event.") + try: + async for line in response.aiter_lines(): + if line == "": + run = dispatch() + if run is not None: + return run + elif line.startswith("event:"): + current_event = line[len("event:") :].strip() or None + elif line.startswith("data:"): + data_lines.append(line[len("data:") :].lstrip()) + # Checked after every line is handled; the event + # buffered so far is dispatched below, so a `done` + # whose lines were read by the deadline still counts. + if _time.monotonic() - start > timeout_seconds: + ending = timed_out + break + except httpx.TransportError as e: + if not raise_on_incomplete and not isinstance( + e, httpx.TimeoutException + ): + raise # as released: the cut surfaces raw + cause = e + ending = ( + timed_out + if isinstance(e, httpx.TimeoutException) + else f"The stream was cut ({type(e).__name__}: {e})" + ) except httpx.TimeoutException as e: - raise SeclaiError( - f"Timed out after {timeout_seconds}s waiting for streaming agent run to complete." - ) from e + cause = e + ending = timed_out + + # An event whose blank line never came (EOF, timeout) still counts. + run = dispatch() + if run is not None: + return run + if ending is None and not raise_on_incomplete and last_seen is not None: + return last_seen # as released + snapshot = result_seen if result_seen is not None else last_seen + outcome = ( + "the run had reported its result; read it from the error's `run`" + if result_seen is not None + else "the run had not reported a result" + ) + raise SeclaiStreamingError( + f"{ending or 'The stream ended'} before the 'done' event: {outcome}.", + run_id=snapshot.run_id if snapshot is not None else None, + run=snapshot, + ) from cause async def list_agent_runs( self, agent_id: str, *, page: int = 1, limit: int = 50 @@ -8265,10 +8579,18 @@ async def set_slack_trigger_config( Args: agent_id: Agent identifier. trigger_id: Trigger identifier. - body: Fields to set (mcp_client_id, form, scope, channel_ids, - allow_dms, activation, visibility, start_without_form, input, - turns_enabled, turns_anyone, max_turns, include_invoker_email, - notify_failure_after_answer). Omitted fields are unchanged. + body: Fields to set (mcp_client_id, alias, form, scope, + channel_ids, allow_dms, activation, visibility, + start_without_form, turns_enabled, turns_anyone, max_turns, + include_invoker_email, notify_failure_after_answer). Omitted + fields are unchanged. ``alias`` is the name people type after + ``/seclai`` to run this agent; it is generated from the agent's + name when not set. A run's input is the text after + ``/seclai ``, or the message the shortcut was used on; + form values reach it as ``{{metadata.}}``. + Deprecated: ``input``, the trigger's input template; the API + ignores it. A body that still sets it is sent as given, so + existing callers keep working. Returns: The trigger's Slack config, with ``missing_scopes`` listing what the @@ -8287,7 +8609,9 @@ async def set_accepted_attachments( self, agent_id: str, trigger_id: str, - accepted_attachments: list[dict[str, Any]] | None, + accepted_attachments: ( + Sequence[AcceptedAttachmentSlot | Mapping[str, Any]] | None + ), ) -> AcceptedAttachmentsResponse: """Declare the input attachments a trigger accepts. @@ -8302,8 +8626,9 @@ async def set_accepted_attachments( trigger_id: Trigger identifier, as :meth:`get_agent` returns it. accepted_attachments: The attachments, each with a ``name`` and optional ``label``, ``content_types``, ``name_pattern``, ``min`` - and ``max``. ``None`` accepts any files, as one attachment named - ``files``. Sent as given, so ``None`` is sent as ``null``. + and ``max``, as dicts or as the ``AcceptedAttachmentSlot`` + models a response returns. ``None`` accepts any files, as one + attachment named ``files``, and is sent as ``null``. Returns: The trigger's ``accepted_attachments`` with its ``agent_id`` and @@ -8314,7 +8639,20 @@ async def set_accepted_attachments( SeclaiAPIStatusError: If the API returns a non-success status code. SeclaiError: If the response body does not decode as the model. """ - body: dict[str, Any] = {"accepted_attachments": accepted_attachments} + body: dict[str, Any] = { + "accepted_attachments": ( + None + if accepted_attachments is None + else [ + ( + slot.to_dict() + if isinstance(slot, AcceptedAttachmentSlot) + else dict(slot) + ) + for slot in accepted_attachments + ] + ) + } payload = await self.request( "PUT", f"/agents/{agent_id}/triggers/{trigger_id}/accepted-attachments", @@ -8322,6 +8660,86 @@ async def set_accepted_attachments( ) return _parse_model(payload, AcceptedAttachmentsResponse) + async def get_metadata_keys( + self, + agent_id: str, + trigger_id: str, + ) -> MetadataKeysResponse: + """Get the run metadata keys a trigger declares. + + Steps reference a declared key as ``{{metadata.}}``. ``system`` + and ``source`` keys are written by the platform and are never required; + ``custom`` keys are sent by the caller. A run you start is refused with + a 400 when it lacks a required key or sends a custom key the trigger + does not declare. + + Args: + agent_id: Agent identifier. + trigger_id: Trigger identifier, as :meth:`get_agent` returns it. + + Returns: + The trigger's ``metadata_keys``, the ``declarable_keys`` its type + offers, and ``accepts_any_source_key``. ``warnings`` is always + empty here. + + Raises: + SeclaiAPIValidationError: If the API returns a validation error. + SeclaiAPIStatusError: If the API returns a non-success status code. + SeclaiError: If the response body does not decode as the model. + """ + payload = await self.request( + "GET", + f"/agents/{agent_id}/triggers/{trigger_id}/metadata-keys", + ) + return _parse_model(payload, MetadataKeysResponse) + + async def set_metadata_keys( + self, + agent_id: str, + trigger_id: str, + metadata_keys: Sequence[MetadataKeyDeclaration | Mapping[str, Any]], + ) -> MetadataKeysResponse: + """Declare the run metadata keys a trigger accepts. + + Replaces the trigger's whole declaration. The API answers 400 when the + agent references a key that no trigger of its branch then declares. + + Args: + agent_id: Agent identifier. + trigger_id: Trigger identifier, as :meth:`get_agent` returns it. + metadata_keys: The keys, each with a ``key``, an ``origin`` + (``system``, ``source`` or ``custom``) and an optional + ``required`` (default ``False``; only a ``custom`` key can be + required), as dicts or as the ``MetadataKeyDeclaration`` + models :meth:`get_metadata_keys` returns, so its + ``metadata_keys`` can be edited and sent back. ``[]`` declares + none. + + Returns: + The new declaration, as :meth:`get_metadata_keys` returns it. + ``warnings``, when the API sends it, names agents whose + ``call_agent`` mapping no longer fits it; it is ``UNSET`` when + omitted, so check ``isinstance(result.warnings, Unset)`` first + (``from seclai import Unset``). + + Raises: + SeclaiAPIValidationError: If the API returns a validation error. + SeclaiAPIStatusError: If the API returns a non-success status code. + SeclaiError: If the response body does not decode as the model. + """ + body: dict[str, Any] = { + "metadata_keys": [ + key.to_dict() if isinstance(key, MetadataKeyDeclaration) else dict(key) + for key in metadata_keys + ] + } + payload = await self.request( + "PUT", + f"/agents/{agent_id}/triggers/{trigger_id}/metadata-keys", + json=body, + ) + return _parse_model(payload, MetadataKeysResponse) + # ── Knowledge Bases ─────────────────────────────────────────────────────── async def list_knowledge_bases( @@ -8417,6 +8835,34 @@ async def delete_knowledge_base(self, knowledge_base_id: str) -> None: """ await self.request("DELETE", f"/knowledge_bases/{knowledge_base_id}") + async def get_knowledge_base_metadata_key_stats( + self, knowledge_base_id: str + ) -> KnowledgeBaseMetadataKeyStats: + """Count the item-metadata keys on a knowledge base's content. + + For choosing the keys a content trigger declares + (:meth:`set_metadata_keys`). Each item is counted once, at its latest + version; a null value counts as absent, and reserved and + platform-set keys are left out. + + Args: + knowledge_base_id: Knowledge base identifier. + + Returns: + One entry in ``windows`` per window (``all_time``, + ``last_30_days``, ``last_7_days``), each with ``total_items`` and + its ``keys``, most frequent first, with their top values. + + Raises: + SeclaiAPIValidationError: If the API returns a validation error. + SeclaiAPIStatusError: If the API returns a non-success status code. + SeclaiError: If the response body does not decode as the model. + """ + payload = await self.request( + "GET", f"/knowledge_bases/{knowledge_base_id}/metadata-key-stats" + ) + return _parse_model(payload, KnowledgeBaseMetadataKeyStats) + # ── Memory Banks ────────────────────────────────────────────────────────── async def list_memory_banks( @@ -10596,20 +11042,32 @@ async def run_agent_and_poll( *, poll_interval: float = 2.0, include_step_outputs: bool = False, + return_on_result: bool = False, ) -> AgentRunResponse: """Run an agent and poll until it reaches a terminal status. Starts the agent run and then repeatedly polls ``get_agent_run`` until - the status is ``"completed"`` or ``"failed"``. + the status is ``"completed"`` or ``"failed"``, or, with + ``return_on_result``, until the run has reported its result. Args: agent_id: Agent identifier. body: Agent run request payload. poll_interval: Seconds between poll attempts (default 2.0). - include_step_outputs: Include per-step outputs when polling. + include_step_outputs: Include per-step outputs when polling. When + the ``run_agent`` response would already end the poll, the + run is fetched once more with them, since that response + carries no step outputs. + return_on_result: Return as soon as a snapshot has + ``result_reported_at`` set: its ``output`` is the answer, and + for an agent whose ``report_success`` is ``on_result`` that can + be before later steps finish. The run's ``status`` may then + still be ``"processing"``, and the run can still fail after + its result. A terminal status is returned at once either way. Returns: - The final agent run (completed or failed). + The final agent run (completed or failed), or with + ``return_on_result`` the first snapshot that reported its result. Raises: SeclaiAPIValidationError: If the API returns a validation error. @@ -10618,7 +11076,16 @@ async def run_agent_and_poll( import asyncio run = await self.run_agent(agent_id, body) - while run.status not in ("completed", "failed"): + if include_step_outputs and ( + run.status in ("completed", "failed") + or (return_on_result and run.result_reported_at) + ): + # The run_agent response carries no step outputs, so it must not + # end the poll: fetch the run with them and check that instead. + run = await self.get_agent_run(run.run_id, include_step_outputs=True) + while run.status not in ("completed", "failed") and not ( + return_on_result and run.result_reported_at + ): await asyncio.sleep(poll_interval) run = await self.get_agent_run( run.run_id, include_step_outputs=include_step_outputs @@ -10636,7 +11103,14 @@ async def run_streaming_agent( """Run an agent via SSE streaming and yield events as they arrive. Use ``async for event_type, data in client.run_streaming_agent(...)`` to - process events lazily without buffering the entire stream. + process events lazily without buffering the entire stream. Event types + include ``"init"`` (the first run + snapshot), ``"result"`` (the snapshot once the run has reported its + result: ``result_reported_at`` is set and ``output`` is the answer; it + can arrive while later steps still run) and ``"done"`` (the terminal + snapshot). Callers who only need the answer can stop at ``"result"``; + ``"done"`` says whether the whole run succeeded, which can still fail + after its result. Args: agent_id: Agent identifier. diff --git a/seclai/versions.py b/seclai/versions.py index 0714fee..f5c986f 100644 --- a/seclai/versions.py +++ b/seclai/versions.py @@ -32,13 +32,15 @@ class ApiVersion(StrEnum): V2026_10_19 = "2026-10-19" V2026_10_21 = "2026-10-21" V2026_10_28 = "2026-10-28" + V2026_11_02 = "2026-11-02" + V2026_11_04 = "2026-11-04" #: Baseline applied to an unpinned, header-less caller. DEFAULT_API_VERSION = ApiVersion.V2026_07_01 #: Newest version known to this SDK release. May lag the server. -LATEST_API_VERSION = ApiVersion.V2026_10_28 +LATEST_API_VERSION = ApiVersion.V2026_11_04 def validate_api_version(version: str | None, *, allow_unknown: bool) -> str | None: diff --git a/tests/test_new_methods.py b/tests/test_new_methods.py index f19eb0b..1f838e4 100644 --- a/tests/test_new_methods.py +++ b/tests/test_new_methods.py @@ -6,8 +6,10 @@ from __future__ import annotations +import asyncio import json import pathlib +import time from collections.abc import Callable from typing import Any @@ -19,12 +21,16 @@ from seclai import versions as seclai_versions from seclai._generated.models import ( AcceptedAttachmentsResponse, + AgentRunRequest, ContentAttachmentDetailResponse, ContentAttachmentsListResponse, ContentEmbeddingsListResponse, EmailSourceRejectionListResponse, EvaluationStatus, InsufficientCreditsResponse, + KnowledgeBaseMetadataKeyStats, + MetadataKeysResponse, + MetadataOrigin, NonManualEvaluationSummaryResponse, ) from seclai._generated.models import ( @@ -4841,10 +4847,10 @@ def test_null_metadata_is_accepted(self) -> None: } -class TestLatestApiVersion20261028: - def test_latest_is_2026_10_28(self) -> None: +class TestLatestApiVersion20261104: + def test_latest_is_2026_11_04(self) -> None: assert ( - seclai_versions.LATEST_API_VERSION is seclai_versions.ApiVersion.V2026_10_28 + seclai_versions.LATEST_API_VERSION is seclai_versions.ApiVersion.V2026_11_04 ) def test_latest_is_sent_as_the_header(self) -> None: @@ -4856,7 +4862,7 @@ def handler(req: httpx.Request) -> httpx.Response: client = _sync_client(handler, api_version=seclai_versions.LATEST_API_VERSION) client.list_agents() - assert seen["version"] == "2026-10-28" + assert seen["version"] == "2026-11-04" class TestInsufficientCredits402: @@ -4983,6 +4989,7 @@ async def handler(req: httpx.Request) -> httpx.Response: "trigger_id": "t1", "agent_id": "a1", "mcp_client_id": "m1", + "alias": "support-bot", "slack_team_id": "T1", "form": [], "scope": "selected_channels", @@ -5013,7 +5020,12 @@ def handler(req: httpx.Request) -> httpx.Response: return _json_response(_SLACK_CONFIG) client = _sync_client(handler) - body = {"channel_ids": ["C1"], "visibility": "private", "max_turns": 5} + body = { + "alias": "support-bot", + "channel_ids": ["C1"], + "visibility": "private", + "max_turns": 5, + } result = client.set_slack_trigger_config("a1", "t1", body) assert seen["method"] == "PUT" assert seen["path"] == "/agents/a1/triggers/t1/slack-config" @@ -5037,6 +5049,170 @@ async def handler(req: httpx.Request) -> httpx.Response: assert seen["body"] == {"allow_dms": True} assert result == _SLACK_CONFIG + def test_deprecated_input_is_still_sent(self) -> None: + # `input` was dropped from the API, which now ignores it. The method + # passes the body through untouched, so a caller that still sets it + # keeps working rather than failing client-side. + seen: dict[str, Any] = {} + client = _sync_client(_recording_handler(seen, _SLACK_CONFIG)) + client.set_slack_trigger_config("a1", "t1", {"input": "{{metadata.q}}"}) + assert seen["body"] == {"input": "{{metadata.q}}"} + + +# --------------------------------------------------------------------------- +# 2026-11-04 sync: trigger metadata keys, knowledge-base metadata-key stats +# --------------------------------------------------------------------------- + +_METADATA_KEYS = [ + {"key": "topic", "origin": "custom", "required": True}, + {"key": "trigger_type", "origin": "system", "required": False}, +] + +_METADATA_KEYS_RESPONSE = { + "agent_id": "0b6f2a4e-3c1d-4e5f-8a9b-1c2d3e4f5a6b", + "trigger_id": "7d8e9f0a-1b2c-4d3e-9f4a-5b6c7d8e9f0a", + "metadata_keys": _METADATA_KEYS, + "declarable_keys": [ + {"key": "trigger_type", "origin": "system", "always_present": True} + ], + "accepts_any_source_key": False, + "warnings": [], +} + +_KB_METADATA_KEY_STATS = { + "knowledge_base_id": "kb1", + "windows": [ + { + "window": "all_time", + "since": None, + "total_items": 12, + "keys": [ + { + "key": "author", + "items": 10, + "distinct_values": 2, + "top_values": [{"value": "Ada", "items": 7}], + } + ], + }, + { + "window": "last_7_days", + "since": "2026-10-29T00:00:00+00:00", + "total_items": 0, + "keys": [], + }, + ], +} + +_METADATA_KEY_CALLS: list[ + tuple[str, tuple[Any, ...], str, str, Any, dict[str, Any], type[Any]] +] = [ + ( + "get_metadata_keys", + ("a1", "t1"), + "GET", + "/agents/a1/triggers/t1/metadata-keys", + None, + _METADATA_KEYS_RESPONSE, + MetadataKeysResponse, + ), + ( + "set_metadata_keys", + ("a1", "t1", _METADATA_KEYS), + "PUT", + "/agents/a1/triggers/t1/metadata-keys", + {"metadata_keys": _METADATA_KEYS}, + _METADATA_KEYS_RESPONSE, + MetadataKeysResponse, + ), + ( + # An empty declaration is sent as an empty list, not dropped. + "set_metadata_keys", + ("a1", "t1", []), + "PUT", + "/agents/a1/triggers/t1/metadata-keys", + {"metadata_keys": []}, + {**_METADATA_KEYS_RESPONSE, "metadata_keys": []}, + MetadataKeysResponse, + ), + ( + "get_knowledge_base_metadata_key_stats", + ("kb1",), + "GET", + "/knowledge_bases/kb1/metadata-key-stats", + None, + _KB_METADATA_KEY_STATS, + KnowledgeBaseMetadataKeyStats, + ), +] + + +class TestMetadataKeys: + @pytest.mark.parametrize( + ("name", "args", "verb", "path", "body", "response", "model"), + _METADATA_KEY_CALLS, + ) + def test_request( + self, + name: str, + args: tuple[Any, ...], + verb: str, + path: str, + body: Any, + response: dict[str, Any], + model: type[Any], + ) -> None: + seen: dict[str, Any] = {} + client = _sync_client(_recording_handler(seen, response)) + result = getattr(client, name)(*args) + assert seen == {"method": verb, "path": path, "query": [], "body": body} + assert isinstance(result, model) + assert result.to_dict() == response + + @pytest.mark.asyncio + @pytest.mark.parametrize( + ("name", "args", "verb", "path", "body", "response", "model"), + _METADATA_KEY_CALLS, + ) + async def test_request_async( + self, + name: str, + args: tuple[Any, ...], + verb: str, + path: str, + body: Any, + response: dict[str, Any], + model: type[Any], + ) -> None: + seen: dict[str, Any] = {} + client = _async_client(_recording_handler(seen, response)) + result = await getattr(client, name)(*args) + assert seen == {"method": verb, "path": path, "query": [], "body": body} + assert isinstance(result, model) + assert result.to_dict() == response + + def test_typed_fields(self) -> None: + client = _sync_client(lambda req: _json_response(_METADATA_KEYS_RESPONSE)) + keys = client.get_metadata_keys("a1", "t1") + assert keys.metadata_keys[0].key == "topic" + assert keys.metadata_keys[0].origin == MetadataOrigin.CUSTOM + assert keys.metadata_keys[0].required is True + assert keys.declarable_keys[0].always_present is True + + client = _sync_client(lambda req: _json_response(_KB_METADATA_KEY_STATS)) + stats = client.get_knowledge_base_metadata_key_stats("kb1") + assert stats.windows[0].since is None + assert stats.windows[0].keys[0].top_values[0].value == "Ada" + assert stats.windows[1].since is not None + + @pytest.mark.asyncio + async def test_async_undecodable_body_raises_seclai_error(self) -> None: + from seclai import SeclaiError + + client = _async_client(lambda req: _json_response({"agent_id": "a1"})) + with pytest.raises(SeclaiError): + await client.set_metadata_keys("a1", "t1", []) + # Each declared query filter: (method, positional args, kwargs, path, the query # the kwargs add, and the query the call sends when none of them is passed). @@ -5354,3 +5530,255 @@ async def handler(req: httpx.Request) -> httpx.Response: await client.get_non_manual_evaluation_summary() assert seen["path"] == "/agents/evaluation-results/non-manual-summary" assert dict(seen["query"]) == {} + + +# --------------------------------------------------------------------------- +# Read-modify-write: the setters take the models their getters return +# --------------------------------------------------------------------------- + + +class TestSettersAcceptModels: + def test_set_metadata_keys_round_trip(self) -> None: + seen: dict[str, Any] = {} + + def handler(req: httpx.Request) -> httpx.Response: + if req.method == "GET": + return _json_response(_METADATA_KEYS_RESPONSE) + response: httpx.Response = _recording_handler( + seen, _METADATA_KEYS_RESPONSE + )(req) + return response + + client = _sync_client(handler) + keys = client.get_metadata_keys("a1", "t1") + keys.metadata_keys[0].required = False + updated = client.set_metadata_keys("a1", "t1", keys.metadata_keys) + # The README's check, with `Unset` from the public package. + assert {"Unset", "UNSET"} <= set(seclai.__all__) + assert not isinstance(updated.warnings, seclai.Unset) + assert seen["body"] == { + "metadata_keys": [ + {"key": "topic", "origin": "custom", "required": False}, + {"key": "trigger_type", "origin": "system", "required": False}, + ] + } + + @pytest.mark.asyncio + async def test_set_metadata_keys_round_trip_async(self) -> None: + seen: dict[str, Any] = {} + + def handler(req: httpx.Request) -> httpx.Response: + if req.method == "GET": + return _json_response(_METADATA_KEYS_RESPONSE) + response: httpx.Response = _recording_handler( + seen, _METADATA_KEYS_RESPONSE + )(req) + return response + + client = _async_client(handler) + keys = await client.get_metadata_keys("a1", "t1") + await client.set_metadata_keys("a1", "t1", keys.metadata_keys) + assert seen["body"] == {"metadata_keys": _METADATA_KEYS} + + def test_set_accepted_attachments_round_trip(self) -> None: + response = { + "agent_id": "0b6f2a4e-3c1d-4e5f-8a9b-1c2d3e4f5a6b", + "trigger_id": "7d8e9f0a-1b2c-4d3e-9f4a-5b6c7d8e9f0a", + "accepted_attachments": [{"name": "invoice", "min": 1}], + } + seen: dict[str, Any] = {} + client = _sync_client(_recording_handler(seen, response)) + first = client.set_accepted_attachments("a1", "t1", [{"name": "invoice"}]) + client.set_accepted_attachments("a1", "t1", first.accepted_attachments) + assert seen["body"] == { + "accepted_attachments": [ + first.accepted_attachments[0].to_dict(), + ] + } + assert seen["body"]["accepted_attachments"][0]["name"] == "invoice" + + @pytest.mark.asyncio + async def test_set_accepted_attachments_round_trip_async(self) -> None: + response = { + "agent_id": "0b6f2a4e-3c1d-4e5f-8a9b-1c2d3e4f5a6b", + "trigger_id": "7d8e9f0a-1b2c-4d3e-9f4a-5b6c7d8e9f0a", + "accepted_attachments": [{"name": "invoice", "min": 1}], + } + seen: dict[str, Any] = {} + client = _async_client(_recording_handler(seen, response)) + first = await client.set_accepted_attachments("a1", "t1", [{"name": "invoice"}]) + await client.set_accepted_attachments("a1", "t1", first.accepted_attachments) + assert seen["body"]["accepted_attachments"][0]["name"] == "invoice" + + +# --------------------------------------------------------------------------- +# run_agent_and_poll(return_on_result=...) +# --------------------------------------------------------------------------- + + +def _run(status: str, *, reported: bool) -> dict[str, Any]: + return { + "attempts": [], + "credits": None, + "error_count": 0, + "input": None, + "output": "answer" if reported else None, + "priority": False, + "run_id": "run_1", + "status": status, + "result_reported_at": "2026-11-05T00:00:00Z" if reported else None, + } + + +def _poll_handler(polls: list[dict[str, Any]], seen: list[str]) -> Any: + def handler(req: httpx.Request) -> httpx.Response: + seen.append(f"{req.method} {req.url.path}") + if req.method == "POST": + return _json_response(_run("pending", reported=False)) + return _json_response(polls.pop(0)) + + return handler + + +_POLLS = [ + _run("processing", reported=True), + _run("completed", reported=True), +] + + +class TestRunAgentAndPollReturnOnResult: + def test_returns_on_result(self) -> None: + seen: list[str] = [] + client = _sync_client(_poll_handler(list(_POLLS), seen)) + run = client.run_agent_and_poll( + "a1", AgentRunRequest(input_="hi"), poll_interval=0, return_on_result=True + ) + assert run.status == "processing" + assert run.output == "answer" + assert seen == ["POST /agents/a1/runs", "GET /agents/runs/run_1"] + + def test_default_waits_for_terminal_status(self) -> None: + seen: list[str] = [] + client = _sync_client(_poll_handler(list(_POLLS), seen)) + run = client.run_agent_and_poll( + "a1", AgentRunRequest(input_="hi"), poll_interval=0 + ) + assert run.status == "completed" + assert len(seen) == 3 + + @staticmethod + def _terminal_at_once(seen: list[str]) -> Any: + def handler(req: httpx.Request) -> httpx.Response: + seen.append(f"{req.method} {req.url.path}?{req.url.query.decode()}") + run = _run("completed", reported=True) + if req.method == "GET": + run["output"] = "with steps" + return _json_response(run) + + return handler + + @pytest.mark.parametrize("return_on_result", [False, True]) + def test_step_outputs_fetch_the_run_even_if_the_start_is_terminal( + self, return_on_result: bool + ) -> None: + seen: list[str] = [] + client = _sync_client(self._terminal_at_once(seen)) + run = client.run_agent_and_poll( + "a1", + AgentRunRequest(input_="hi"), + poll_interval=0, + include_step_outputs=True, + return_on_result=return_on_result, + ) + assert run.output == "with steps" + assert seen == [ + "POST /agents/a1/runs?", + "GET /agents/runs/run_1?include_step_outputs=true", + ] + + def test_without_step_outputs_a_terminal_start_ends_the_poll(self) -> None: + seen: list[str] = [] + client = _sync_client(self._terminal_at_once(seen)) + run = client.run_agent_and_poll( + "a1", AgentRunRequest(input_="hi"), poll_interval=0 + ) + assert run.output == "answer" + assert seen == ["POST /agents/a1/runs?"] + + @staticmethod + def _pending_start(seen: list[str]) -> Any: + def handler(req: httpx.Request) -> httpx.Response: + seen.append(f"{req.method} {req.url.path}?{req.url.query.decode()}") + if req.method == "POST": + return _json_response(_run("pending", reported=False)) + return _json_response(_run("completed", reported=True)) + + return handler + + def test_step_outputs_add_no_fetch_when_the_start_is_pending( + self, monkeypatch: pytest.MonkeyPatch + ) -> None: + seen: list[str] = [] + monkeypatch.setattr(time, "sleep", lambda s: seen.append("sleep")) + client = _sync_client(self._pending_start(seen)) + run = client.run_agent_and_poll( + "a1", AgentRunRequest(input_="hi"), include_step_outputs=True + ) + assert run.status == "completed" + # The loop's own fetch, after the first interval; none before it. + assert seen == [ + "POST /agents/a1/runs?", + "sleep", + "GET /agents/runs/run_1?include_step_outputs=true", + ] + + @pytest.mark.asyncio + async def test_step_outputs_add_no_fetch_when_the_start_is_pending_async( + self, monkeypatch: pytest.MonkeyPatch + ) -> None: + seen: list[str] = [] + + async def fake_sleep(seconds: float) -> None: + seen.append("sleep") + + monkeypatch.setattr(asyncio, "sleep", fake_sleep) + client = _async_client(self._pending_start(seen)) + run = await client.run_agent_and_poll( + "a1", AgentRunRequest(input_="hi"), include_step_outputs=True + ) + assert run.status == "completed" + assert seen == [ + "POST /agents/a1/runs?", + "sleep", + "GET /agents/runs/run_1?include_step_outputs=true", + ] + + @pytest.mark.asyncio + @pytest.mark.parametrize("return_on_result", [False, True]) + async def test_step_outputs_fetch_the_run_even_if_the_start_is_terminal_async( + self, return_on_result: bool + ) -> None: + seen: list[str] = [] + client = _async_client(self._terminal_at_once(seen)) + run = await client.run_agent_and_poll( + "a1", + AgentRunRequest(input_="hi"), + poll_interval=0, + include_step_outputs=True, + return_on_result=return_on_result, + ) + assert run.output == "with steps" + assert seen == [ + "POST /agents/a1/runs?", + "GET /agents/runs/run_1?include_step_outputs=true", + ] + + @pytest.mark.asyncio + async def test_returns_on_result_async(self) -> None: + seen: list[str] = [] + client = _async_client(_poll_handler(list(_POLLS), seen)) + run = await client.run_agent_and_poll( + "a1", AgentRunRequest(input_="hi"), poll_interval=0, return_on_result=True + ) + assert run.status == "processing" + assert seen == ["POST /agents/a1/runs", "GET /agents/runs/run_1"] diff --git a/tests/test_specfix.py b/tests/test_specfix.py new file mode 100644 index 0000000..bf36832 --- /dev/null +++ b/tests/test_specfix.py @@ -0,0 +1,84 @@ +import copy +import importlib.util +import json +import subprocess +import sys +from pathlib import Path + +import pytest + +ROOT = Path(__file__).resolve().parent.parent +SPEC = ROOT / "openapi" / "seclai.openapi.json" +SPECFIX = ROOT / "scripts" / "specfix.py" + + +def _run(src: Path, dst: Path) -> subprocess.CompletedProcess[str]: + return subprocess.run( + [sys.executable, str(SPECFIX), str(src), str(dst)], + capture_output=True, + text=True, + check=False, + ) + + +def test_specfix_adds_the_retained_field(tmp_path: Path) -> None: + dst = tmp_path / "out.json" + result = _run(SPEC, dst) + assert result.returncode == 0, result.stderr + out = json.loads(dst.read_text(encoding="utf-8")) + props = out["components"]["schemas"]["SetSlackTriggerConfigApiRequest"][ + "properties" + ] + assert props["input"]["deprecated"] is True + + +def test_specfix_fails_when_the_spec_declares_a_retained_field_again( + tmp_path: Path, +) -> None: + spec = json.loads(SPEC.read_text(encoding="utf-8")) + spec["components"]["schemas"]["SetSlackTriggerConfigApiRequest"]["properties"][ + "input" + ] = {"type": "string"} + src = tmp_path / "in.json" + src.write_text(json.dumps(spec), encoding="utf-8") + dst = tmp_path / "out.json" + + result = _run(src, dst) + + assert result.returncode == 1 + assert ( + "stale entry `SetSlackTriggerConfigApiRequest.input` in the retained-fields " + "list: the spec declares it again; remove the entry" + ) in result.stderr + assert not dst.exists() + + +def test_specfix_applies_no_entry_when_one_is_stale( + monkeypatch: pytest.MonkeyPatch, +) -> None: + spec_loader = importlib.util.spec_from_file_location("specfix", SPECFIX) + assert spec_loader is not None and spec_loader.loader is not None + specfix = importlib.util.module_from_spec(spec_loader) + spec_loader.loader.exec_module(specfix) + monkeypatch.setattr( + specfix, + "RETAINED_REQUEST_FIELDS", + [ + ("Fresh", "kept", {"type": "string"}), + ("Stale", "back", {"type": "string"}), + ], + ) + spec = { + "components": { + "schemas": { + "Fresh": {"properties": {}}, + "Stale": {"properties": {"back": {"type": "integer"}}}, + } + } + } + before = copy.deepcopy(spec) + + errors = specfix.retain_removed_request_fields(spec) + + assert len(errors) == 1 and "stale entry `Stale.back`" in errors[0] + assert spec == before diff --git a/tests/test_streaming_agent_runs.py b/tests/test_streaming_agent_runs.py index 6e0477e..d74c2fd 100644 --- a/tests/test_streaming_agent_runs.py +++ b/tests/test_streaming_agent_runs.py @@ -1,3 +1,4 @@ +import asyncio import json import threading import time @@ -7,7 +8,13 @@ import httpx import pytest -from seclai import AgentRunStreamRequest, AsyncSeclai, Seclai, SeclaiError +from seclai import ( + AgentRunStreamRequest, + AsyncSeclai, + Seclai, + SeclaiError, + SeclaiStreamingError, +) def _agent_run_payload(status: str, *, output: str | None = None) -> dict[str, Any]: @@ -132,3 +139,405 @@ def log_message(self, format: str, *args: object) -> None: # noqa: A003 finally: server.shutdown() server.server_close() + + +def _reported(status: str) -> dict[str, Any]: + payload = _agent_run_payload(status, output="answer") + payload["result_reported_at"] = "2026-11-05T00:00:00Z" + return payload + + +def _sse(*events: tuple[str, dict[str, Any]]) -> bytes: + return b"".join( + f"event: {name}\ndata: {json.dumps(data)}\n\n".encode() for name, data in events + ) + + +def _stream_response(content: bytes) -> httpx.Response: + return httpx.Response( + status_code=200, headers={"content-type": "text/event-stream"}, content=content + ) + + +def _sync_client(stream: httpx.SyncByteStream | bytes) -> Seclai: + def handler(req: httpx.Request) -> httpx.Response: + if isinstance(stream, bytes): + return _stream_response(stream) + return httpx.Response( + 200, headers={"content-type": "text/event-stream"}, stream=stream + ) + + return Seclai( + api_key="test", + http_client=httpx.Client( + base_url="https://example.invalid", + transport=httpx.MockTransport(handler), + ), + ) + + +def _async_client(stream: httpx.AsyncByteStream | bytes) -> AsyncSeclai: + def handler(req: httpx.Request) -> httpx.Response: + if isinstance(stream, bytes): + return _stream_response(stream) + return httpx.Response( + 200, headers={"content-type": "text/event-stream"}, stream=stream + ) + + return AsyncSeclai( + api_key="test", + http_client=httpx.AsyncClient( + base_url="https://example.invalid", + transport=httpx.MockTransport(handler), + ), + ) + + +_INIT_AND_RESULT = _sse( + ("init", _agent_run_payload("processing")), + ("result", _reported("processing")), +) + + +def test_run_streaming_agent_and_wait_raises_with_result_when_stream_ends() -> None: + client = _sync_client(_INIT_AND_RESULT) + with pytest.raises(SeclaiStreamingError, match="reported its result") as exc: + client.run_streaming_agent_and_wait( + "agent_1", + body=AgentRunStreamRequest(input="hi"), + raise_on_incomplete=True, + ) + assert exc.value.run is not None + assert exc.value.run.output == "answer" + assert exc.value.run_id == "run_1" + + +def test_run_streaming_agent_and_wait_raises_with_init_when_stream_ends() -> None: + client = _sync_client(_sse(("init", _agent_run_payload("processing")))) + with pytest.raises(SeclaiStreamingError, match="not reported a result") as exc: + client.run_streaming_agent_and_wait( + "agent_1", + body=AgentRunStreamRequest(input="hi"), + raise_on_incomplete=True, + ) + assert exc.value.run is not None + assert exc.value.run.status == "processing" + + +def test_run_streaming_agent_and_wait_prefers_done_over_result() -> None: + client = _sync_client( + _INIT_AND_RESULT + _sse(("done", _reported("failed"))), + ) + res = client.run_streaming_agent_and_wait( + "agent_1", body=AgentRunStreamRequest(input="hi") + ) + assert res.status == "failed" + + +def test_run_streaming_agent_and_wait_return_on_result() -> None: + client = _sync_client( + _INIT_AND_RESULT + _sse(("done", _reported("failed"))), + ) + res = client.run_streaming_agent_and_wait( + "agent_1", body=AgentRunStreamRequest(input="hi"), return_on_result=True + ) + assert res.status == "processing" + assert res.output == "answer" + + +@pytest.mark.asyncio +async def test_async_run_streaming_agent_and_wait_raises_with_result_when_stream_ends() -> ( + None +): + async with _async_client(_INIT_AND_RESULT) as client: + with pytest.raises(SeclaiStreamingError) as exc: + await client.run_streaming_agent_and_wait( + "agent_1", + body=AgentRunStreamRequest(input="hi"), + raise_on_incomplete=True, + ) + assert exc.value.run is not None + assert exc.value.run.output == "answer" + + +@pytest.mark.asyncio +async def test_async_run_streaming_agent_and_wait_return_on_result() -> None: + async with _async_client( + _INIT_AND_RESULT + _sse(("done", _reported("failed"))) + ) as client: + res = await client.run_streaming_agent_and_wait( + "agent_1", body=AgentRunStreamRequest(input="hi"), return_on_result=True + ) + assert res.status == "processing" + + +_CUTS = [httpx.ReadError("connection reset"), httpx.RemoteProtocolError("cut")] + + +class _CutAfterResult(httpx.SyncByteStream): + def __init__(self, error: Exception) -> None: + self.error = error + + def __iter__(self) -> Any: + yield _INIT_AND_RESULT + raise self.error + + +class _AsyncCutAfterResult(httpx.AsyncByteStream): + def __init__(self, error: Exception) -> None: + self.error = error + + async def __aiter__(self) -> Any: + yield _INIT_AND_RESULT + raise self.error + + +@pytest.mark.parametrize("error", _CUTS) +def test_run_streaming_agent_and_wait_raises_with_result_when_stream_is_cut( + error: Exception, +) -> None: + client = _sync_client(_CutAfterResult(error)) + with pytest.raises(SeclaiStreamingError, match="stream was cut") as exc: + client.run_streaming_agent_and_wait( + "agent_1", + body=AgentRunStreamRequest(input="hi"), + raise_on_incomplete=True, + ) + assert exc.value.run is not None + assert exc.value.run.output == "answer" + assert exc.value.__cause__ is error + + +@pytest.mark.asyncio +@pytest.mark.parametrize("error", _CUTS) +async def test_async_run_streaming_agent_and_wait_raises_with_result_when_stream_is_cut( + error: Exception, +) -> None: + async with _async_client(_AsyncCutAfterResult(error)) as client: + with pytest.raises(SeclaiStreamingError, match="stream was cut") as exc: + await client.run_streaming_agent_and_wait( + "agent_1", + body=AgentRunStreamRequest(input="hi"), + raise_on_incomplete=True, + ) + assert exc.value.run is not None + assert exc.value.run.output == "answer" + + +_DONE_DATA = f"data: {json.dumps(_agent_run_payload('completed', output='final'))}\n" + + +class _DoneSpanningTheDeadline(httpx.SyncByteStream): + def __iter__(self) -> Any: + yield _INIT_AND_RESULT + b"event: done\n" + time.sleep(0.15) # past the 0.05s deadline + yield _DONE_DATA.encode() # the closing blank line never comes + time.sleep(1.0) + + +class _AsyncDoneSpanningTheDeadline(httpx.AsyncByteStream): + async def __aiter__(self) -> Any: + yield _INIT_AND_RESULT + b"event: done\n" + await asyncio.sleep(0.15) # past the 0.05s deadline + yield _DONE_DATA.encode() # the closing blank line never comes + await asyncio.sleep(1.0) + + +# The deadline is checked on every line, inside an event too; the event read +# so far is dispatched when it fires, rather than waiting for the stream. + + +def test_run_streaming_agent_and_wait_checks_the_deadline_inside_an_event() -> None: + client = _sync_client(_DoneSpanningTheDeadline()) + start = time.monotonic() + res = client.run_streaming_agent_and_wait( + "agent_1", body=AgentRunStreamRequest(input="hi"), timeout=0.05 + ) + assert time.monotonic() - start < 0.6 + assert res.status == "completed" + assert res.output == "final" + + +@pytest.mark.asyncio +async def test_async_run_streaming_agent_and_wait_checks_the_deadline_inside_an_event() -> ( + None +): + async with _async_client(_AsyncDoneSpanningTheDeadline()) as client: + start = time.monotonic() + res = await client.run_streaming_agent_and_wait( + "agent_1", body=AgentRunStreamRequest(input="hi"), timeout=0.05 + ) + assert time.monotonic() - start < 0.6 + assert res.status == "completed" + + +class _ResultThenHang(BaseHTTPRequestHandler): + protocol_version = "HTTP/1.1" + + def do_POST(self) -> None: # noqa: N802 + self.send_response(200) + self.send_header("Content-Type", "text/event-stream") + self.end_headers() + self.wfile.write(_INIT_AND_RESULT) + self.wfile.flush() + time.sleep(1.0) # longer than the client timeout; `done` never comes + + def log_message(self, format: str, *args: object) -> None: # noqa: A003 + return + + +def test_run_streaming_agent_and_wait_raises_with_result_on_timeout() -> None: + server = ThreadingHTTPServer(("127.0.0.1", 0), _ResultThenHang) + t = threading.Thread(target=server.serve_forever, daemon=True) + t.start() + try: + base_url = f"http://127.0.0.1:{server.server_address[1]}" + client = Seclai(api_key="test", http_client=httpx.Client(base_url=base_url)) + with pytest.raises(SeclaiStreamingError, match="Timed out") as exc: + client.run_streaming_agent_and_wait( + "agent_1", + body=AgentRunStreamRequest(input="hi"), + timeout=0.2, + raise_on_incomplete=True, + ) + assert exc.value.run is not None + assert exc.value.run.output == "answer" + finally: + server.shutdown() + server.server_close() + + +@pytest.mark.asyncio +async def test_async_run_streaming_agent_and_wait_raises_with_result_on_timeout() -> ( + None +): + server = ThreadingHTTPServer(("127.0.0.1", 0), _ResultThenHang) + t = threading.Thread(target=server.serve_forever, daemon=True) + t.start() + try: + base_url = f"http://127.0.0.1:{server.server_address[1]}" + async with AsyncSeclai( + api_key="test", http_client=httpx.AsyncClient(base_url=base_url) + ) as client: + with pytest.raises(SeclaiStreamingError, match="Timed out") as exc: + await client.run_streaming_agent_and_wait( + "agent_1", + body=AgentRunStreamRequest(input="hi"), + timeout=0.2, + raise_on_incomplete=True, + ) + assert exc.value.run is not None + assert exc.value.run.output == "answer" + finally: + server.shutdown() + server.server_close() + + +# With `raise_on_incomplete` off (the default), each ending behaves as in 1.9.0. + + +def test_run_streaming_agent_and_wait_returns_the_last_snapshot_when_stream_ends() -> ( + None +): + client = _sync_client(_sse(("init", _agent_run_payload("processing")))) + res = client.run_streaming_agent_and_wait( + "agent_1", body=AgentRunStreamRequest(input="hi") + ) + assert res.status == "processing" + + +@pytest.mark.asyncio +async def test_async_run_streaming_agent_and_wait_returns_the_last_snapshot_when_stream_ends() -> ( + None +): + async with _async_client( + _sse(("init", _agent_run_payload("processing"))) + ) as client: + res = await client.run_streaming_agent_and_wait( + "agent_1", body=AgentRunStreamRequest(input="hi") + ) + assert res.status == "processing" + + +def test_run_streaming_agent_and_wait_raises_on_an_empty_stream() -> None: + client = _sync_client(b": keepalive\n\n") + with pytest.raises(SeclaiError, match="before"): + client.run_streaming_agent_and_wait( + "agent_1", body=AgentRunStreamRequest(input="hi") + ) + + +class _CutAfterInit(httpx.SyncByteStream): + def __iter__(self) -> Any: + yield _sse(("init", _agent_run_payload("processing"))) + raise httpx.ReadError("connection reset") + + +class _AsyncCutAfterInit(httpx.AsyncByteStream): + async def __aiter__(self) -> Any: + yield _sse(("init", _agent_run_payload("processing"))) + raise httpx.ReadError("connection reset") + + +def test_run_streaming_agent_and_wait_lets_a_cut_through_by_default() -> None: + client = _sync_client(_CutAfterInit()) + with pytest.raises(httpx.ReadError): + client.run_streaming_agent_and_wait( + "agent_1", body=AgentRunStreamRequest(input="hi") + ) + + +@pytest.mark.asyncio +async def test_async_run_streaming_agent_and_wait_lets_a_cut_through_by_default() -> ( + None +): + async with _async_client(_AsyncCutAfterInit()) as client: + with pytest.raises(httpx.ReadError): + await client.run_streaming_agent_and_wait( + "agent_1", body=AgentRunStreamRequest(input="hi") + ) + + +@pytest.mark.asyncio +async def test_async_run_streaming_agent_and_wait_times_out_by_default() -> None: + server = ThreadingHTTPServer(("127.0.0.1", 0), _ResultThenHang) + t = threading.Thread(target=server.serve_forever, daemon=True) + t.start() + try: + base_url = f"http://127.0.0.1:{server.server_address[1]}" + async with AsyncSeclai( + api_key="test", http_client=httpx.AsyncClient(base_url=base_url) + ) as client: + with pytest.raises(SeclaiError, match="Timed out"): + await client.run_streaming_agent_and_wait( + "agent_1", body=AgentRunStreamRequest(input="hi"), timeout=0.2 + ) + finally: + server.shutdown() + server.server_close() + + +# The one difference from 1.9.0, which ignored `result`: the latest snapshot +# returned at the end of the stream is the `result` one when it arrived. + + +def test_run_streaming_agent_and_wait_returns_the_result_snapshot_when_stream_ends() -> ( + None +): + client = _sync_client(_INIT_AND_RESULT) + res = client.run_streaming_agent_and_wait( + "agent_1", body=AgentRunStreamRequest(input="hi") + ) + assert res.output == "answer" + assert res.result_reported_at + + +@pytest.mark.asyncio +async def test_async_run_streaming_agent_and_wait_returns_the_result_snapshot_when_stream_ends() -> ( + None +): + async with _async_client(_INIT_AND_RESULT) as client: + res = await client.run_streaming_agent_and_wait( + "agent_1", body=AgentRunStreamRequest(input="hi") + ) + assert res.output == "answer"