Repository navigation
docs(agents): add language idioms guidance - #296
Draft
jeffdupont wants to merge 3 commits into
Draft
jeffdupont wants to merge 3 commits into
jeffdupont wants to merge 3 commits into
Conversation
Add a "Language idioms" section to AGENTS.md: how Python code in this repo handles errors, layout, naming, concurrency, options, tests, docs and dependencies, while the public contract stays shared with the other SDKs. Each rule was checked against the current code and worded to match it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Re-checked each rule in the Language idioms section against main and fixed the ones the code contradicts. Headings were already the same as the Go SDK's, in the same order. - What never varies: name the telemetry parts (span names, attributes, events) and what an error condition covers, as the Go section does. - Errors: the no-(value, error)-pair rule now covers public calls only; internal helpers such as list_raw_objects return (value, reason). Evaluations raises EvaluationsError for bad arguments, so a feature's own exception is allowed there. "Never swallow an exception" is replaced: shutdown cleanup and usage reporting catch and drop errors so they never fail the call. - Layout: the leading-underscore rule applies inside public modules. Internal modules such as skills_core export unprefixed helpers. - Naming: the Literal rule covers the public API. Evaluations uses StrEnum internally. - Concurrency: init_client moves its blocking build to its own thread, not asyncio.to_thread, so both are named. - Options: ReconcileReport, SkillOutcome and ShadowResult are frozen result types, so "result types are plain dataclasses" is now "frozen when the contract makes them immutable, otherwise plain". - Testing: "no external network or LaunchDarkly endpoint"; a fake server binds to loopback and is closed in teardown. - Dependencies: openai is also a dependency of litellm-agents, so the rule now says "the handler packages that call it". Docs only. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds a
## Language idiomssection toAGENTS.md, after the Code Quality section. It says how Python code in this repo is shaped: errors, layout, naming, concurrency, options, testing, docs and dependencies, plus what never varies. The JavaScript and Go SDKs get the same 10 headings in the same order.Why
The three AI SDKs share one public API contract: names, behaviour, defaults, wire payloads and telemetry. How each SDK builds things internally should follow its own language's idiom, not copy another SDK's shape. Until now nothing told an agent or contributor that, or which Python idioms this repo uses.
Rules reworded against the code
I checked every rule against
main. Where the code disagreed, I changed the wording and left the code alone:ParseFailure,ReconcileAction.error). The rule now bans(value, error)pairs. Bad arguments raise built-ins (ValueError,TypeError). A feature exception may subclass the closest built-in (TypesafeQuestionError(ValueError)).inspect_config's documented fallback does not log.launchdarkly_ai_server.experimental.shadow_requests), never re-exported from the root. "Private" now means modules without an API report, plus_-prefixed helpers. Most internal modules are not underscore-named.TypedDict(total=False)(the*NativeGraphOptionstypes). New settings are keyword-only. Units can also be fixed by a wrapped library:force_flush(timeout_millis=...)follows OpenTelemetry. Only config and value types are frozen dataclasses. Result types (EvalRunResult,JudgeResult) are plain@dataclass.tests/. Tests may use a fake server on loopback. They never use the external network.No whole rule was dropped. Docs only, no code changes.
Update: refreshed on main and aligned with the Go section
mainis merged in. A second commit makes the section use the same headings, in the same order, as the Go SDK's## Language idioms, and fixes rules the code contradicted:(value, error)pair" now covers public calls only.Literalrule covers the public API only; internal code usesStrEnum.init_clientbuilds on its own thread, as well as throughasyncio.to_thread.launchdarkly-ai-server.Docs only.
🤖 Generated with Claude Code