Skip to content

AGENTS.md

Latest commit

 

History

History
117 lines (90 loc) · 5.89 KB

AGENTS.md

File metadata and controls

117 lines (90 loc) · 5.89 KB

AGENTS.md

This repository is a mostly generated .NET SDK for ElevenLabs. Most code under src/libs/ElevenLabs/Generated/ comes from the upstream OpenAPI document via AutoSDK, and only a small surface area is hand-maintained.

Repo Overview

  • src/libs/ElevenLabs/
    • Main NuGet package.
    • Generated/ is generated by AutoSDK from openapi.yaml.
    • Extensions/ and Realtime/ contain the main hand-written code.
  • src/tests/IntegrationTests/
    • MSTest project against the real ElevenLabs API.
    • Examples/ contains the curated user-facing examples that drive README and MkDocs generation.
  • src/helpers/GenerateDocs/
    • Console app that prepares MkDocs content from the repo.
  • src/helpers/TrimmingHelper/
    • Minimal helper used to surface trimming/AOT warnings during build/publish.
  • docs/
    • MkDocs assets only (css/, media/).
    • docs/index.md and docs/examples/*.md are generated by GenerateDocs and should not be treated as authoritative sources.
  • mkdocs.yml
    • MkDocs config shell. The block between # EXAMPLES:START and # EXAMPLES:END is generated.
  • README.md
    • Packed into the NuGet package.
    • The block between <!-- EXAMPLES:START --> and <!-- EXAMPLES:END --> is generated from integration-test examples.

Generated vs Manual Code

  • Do not manually edit src/libs/ElevenLabs/Generated/.
  • Regenerate SDK code from src/libs/ElevenLabs/generate.sh.
  • src/libs/ElevenLabs/openapi.yaml is a fetched artifact, not a hand-authored contract.
  • When OpenAPI output changes, review hand-written files in Extensions/ and Realtime/ for compatibility instead of patching generated files.

Important Hand-Written Files

  • src/libs/ElevenLabs/Extensions/ElevenLabsClient.Realtime.cs
  • src/libs/ElevenLabs/Extensions/SpeechToTextClient.Realtime.cs
  • src/libs/ElevenLabs/Extensions/SpeechToTextClient.ExtensionsAI.cs
  • src/libs/ElevenLabs/Realtime/RealtimeSpeechToTextSession.cs
  • src/libs/ElevenLabs/Realtime/RealtimeSpeechToTextEvents.cs
  • src/libs/ElevenLabs/Realtime/RealtimeSpeechToTextOptions.cs
  • src/libs/ElevenLabs/Realtime/RealtimeAudioFormat.cs
  • src/libs/ElevenLabs/Realtime/RealtimeCommitStrategy.cs
  • src/helpers/GenerateDocs/Program.cs

Build, Test, and Docs Commands

dotnet build ElevenLabs.slnx
dotnet test src/tests/IntegrationTests/ElevenLabs.IntegrationTests.csproj
dotnet run --project src/helpers/GenerateDocs/GenerateDocs.csproj .
python -m venv .venv && source .venv/bin/activate && pip install mkdocs-material && mkdocs build
cd src/libs/ElevenLabs && ./generate.sh

Notes:

  • Integration tests require ELEVENLABS_API_KEY.
  • The solution targets net10.0 and uses C# preview features.
  • README.md is included in the NuGet package through src/libs/Directory.Build.props.

Current Docs Pipeline

The current documentation flow is:

  1. Curated example tests live in src/tests/IntegrationTests/Examples/*.cs.
  2. Each example file starts with a block comment containing docs metadata (order, title, optional slug, then markdown description).
  3. GenerateDocs parses those example files, strips test-only assertions, and generates:
    • the README examples block
    • docs/index.md
    • docs/examples/*.md
  4. mkdocs.yml has the block between # EXAMPLES:START and # EXAMPLES:END regenerated from the discovered examples.
  5. GitHub Actions runs the docs generator before mkdocs build.

That means the current authoritative sources are split:

  • Top-level narrative docs scaffold: README.md
  • Code examples and their per-page descriptions: src/tests/IntegrationTests/Examples/*.cs
  • MkDocs site structure/theme: mkdocs.yml plus docs/ assets

Docs Sync Rules

If you are touching docs, examples, or onboarding content, use these rules:

  • Do not hand-edit docs/index.md or docs/examples/*.md; they are overwritten.
  • Do not hand-edit the generated README examples block; edit the source example files and rerun GenerateDocs.
  • Do not treat the generated MkDocs example nav as permanent; keep the # EXAMPLES:START / # EXAMPLES:END markers in source control.
  • If an example should compile and stay honest, put the example in integration tests first.
  • Keep one user-facing example per file in src/tests/IntegrationTests/Examples/.
  • Use the file header comment for page title, sort order, slug, and markdown description.

Current Generator Behavior

src/helpers/GenerateDocs/Program.cs now provides the docs sync mechanism:

  • It parses explicit example files only, not arbitrary tests.
  • It uses Roslyn to extract the single [TestMethod] body from each example file.
  • It removes assertion lines from generated snippets and rewrites GetAuthenticatedClient() usage to new ElevenLabsClient(apiKey).
  • It regenerates README, docs/index.md, docs/examples/*.md, and the MkDocs example nav from the same source.
  • It deletes stale generated example pages before writing new ones.

Recommended Direction For Docs

If the goal is first-class MkDocs documentation with synchronized examples, prefer this model:

  • Make executable tests the source of truth for code examples.
  • Make MkDocs the source of truth for long-form product documentation.
  • Keep README as a compact package-facing landing page with its example block generated from the same source as MkDocs.
  • Generate navigation from discovered examples instead of committing duplicated nav entries.
  • Prefer one curated example file per page, with a stable title/slug and a short markdown description in the file header.

PR Hygiene

  • For SDK regeneration changes, inspect generated diffs separately from manual files.
  • For docs/example changes, run the docs generator and inspect the resulting MkDocs build locally.
  • When changing tests used as docs samples, keep the executable path intact and avoid introducing setup code that makes the extracted snippet misleading.
  • Avoid editing generated output just to make docs look right; fix the generator or the actual source instead.