Skip to content

docs(agents): add language idioms guidance - #296

Draft
jeffdupont wants to merge 3 commits into
mainfrom
jdupont/language-idioms
Draft

jeffdupont wants to merge 3 commits into
mainfrom
jdupont/language-idioms

Conversation

@jeffdupont

@jeffdupont jeffdupont commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

What

Adds a ## Language idioms section to AGENTS.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:

  • Errors: dropped "never return error values". The contract defines result types with error fields (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)).
  • Errors: dropped "log it when you swallow". inspect_config's documented fallback does not log.
  • Layout: experimental features are submodules (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.
  • Options: settings passed through to a provider are TypedDict(total=False) (the *NativeGraphOptions types). 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.
  • Testing: cross-package tests live in the root tests/. Tests may use a fake server on loopback. They never use the external network.
  • Docs: a docstring is required on every public name you add or change. A few existing entry points don't have one yet.

No whole rule was dropped. Docs only, no code changes.

Update: refreshed on main and aligned with the Go section

main is 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:

  • Errors:
    • "Never return a (value, error) pair" now covers public calls only.
    • A bad argument may raise the feature's own exception.
    • "Never swallow" is replaced with the reasons a catch is allowed: contract fallbacks, and cleanup in close, flush and shutdown.
  • Layout: the leading-underscore rule applies inside public modules only.
  • Naming: the Literal rule covers the public API only; internal code uses StrEnum.
  • Concurrency: init_client builds on its own thread, as well as through asyncio.to_thread.
  • Options: result types are frozen dataclasses when the contract makes them immutable, and plain otherwise.
  • Testing: "no network" is now "no external network or LaunchDarkly endpoint". A fake server may bind to loopback and must be closed in teardown.
  • Dependencies: a provider SDK is a dependency of the handler packages that call it, never of launchdarkly-ai-server.

Docs only.

🤖 Generated with Claude Code

jeffdupont and others added 3 commits November 10, 2026 11:37
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant