|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +C# SDK for the [AssemblyAI](https://www.assemblyai.com/) speech-to-text and audio intelligence API, auto-generated from the official AssemblyAI OpenAPI specification using [AutoSDK](https://github.com/HavenDV/AutoSDK). Published as NuGet package `tryAGI.AssemblyAI`. Note: AssemblyAI has an [official .NET SDK](https://github.com/AssemblyAI/assemblyai-csharp-sdk); this community SDK aims to match or exceed its capabilities. |
| 8 | + |
| 9 | +## Build Commands |
| 10 | + |
| 11 | +```bash |
| 12 | +# Build the solution |
| 13 | +dotnet build AssemblyAI.sln |
| 14 | + |
| 15 | +# Build for release (also produces NuGet package) |
| 16 | +dotnet build AssemblyAI.sln -c Release |
| 17 | + |
| 18 | +# Run integration tests (requires ASSEMBLYAI_API_KEY env var) |
| 19 | +dotnet test src/tests/IntegrationTests/AssemblyAI.IntegrationTests.csproj |
| 20 | + |
| 21 | +# Regenerate SDK from OpenAPI spec |
| 22 | +cd src/libs/AssemblyAI && ./generate.sh |
| 23 | +``` |
| 24 | + |
| 25 | +## Architecture |
| 26 | + |
| 27 | +### Code Generation Pipeline |
| 28 | + |
| 29 | +The SDK code in `src/libs/AssemblyAI/Generated/` is **entirely auto-generated** -- do not manually edit files there. |
| 30 | + |
| 31 | +1. `src/libs/AssemblyAI/openapi.yaml` -- the AssemblyAI OpenAPI spec (fetched from the official `assemblyai-api-spec` repo) |
| 32 | +2. `src/libs/AssemblyAI/generate.sh` -- orchestrates: download spec, run AutoSDK CLI with `--ignore-openapi-errors`, output to `Generated/` |
| 33 | +3. Note: the FixOpenApiSpec step is commented out in generate.sh for this SDK |
| 34 | +4. CI auto-updates the spec and creates PRs if changes are detected |
| 35 | + |
| 36 | +### Project Layout |
| 37 | + |
| 38 | +| Project | Purpose | |
| 39 | +|---------|---------| |
| 40 | +| `src/libs/AssemblyAI/` | Main SDK library (`AssemblyAIClient`) | |
| 41 | +| `src/tests/IntegrationTests/` | Integration tests against real AssemblyAI API | |
| 42 | +| `src/helpers/FixOpenApiSpec/` | OpenAPI spec fixer tool (currently unused) | |
| 43 | +| `src/helpers/GenerateDocs/` | Documentation generator from integration tests | |
| 44 | +| `src/helpers/TrimmingHelper/` | NativeAOT/trimming compatibility validator | |
| 45 | + |
| 46 | +### Hand-Written Extensions |
| 47 | + |
| 48 | +This SDK includes hand-written code for convenience wrappers and AI abstractions: |
| 49 | + |
| 50 | +| File/Directory | Purpose | |
| 51 | +|----------------|---------| |
| 52 | +| `Conversions/TranscriptParams.cs` | Helper for creating transcript parameters from URLs | |
| 53 | +| `Conversions/TranscriptParamsVariant1.cs` | Variant transcript parameter helpers | |
| 54 | +| `Conversions/LemurTaskParams.cs` | Lemur task parameter helpers | |
| 55 | +| `Conversions/LemurTaskParamsVariant1.cs` | Variant Lemur task parameter helpers | |
| 56 | +| `Extensions/Transcript.cs` | Transcript convenience methods (e.g., `EnsureStatusCompleted()`) | |
| 57 | +| `Extensions/AssemblyAIClient.SpeechToTextClient.cs` | Microsoft.Extensions.AI speech-to-text integration | |
| 58 | + |
| 59 | +### Build Configuration |
| 60 | + |
| 61 | +- **Target:** `net10.0` (single target) |
| 62 | +- **Language:** C# preview with nullable reference types |
| 63 | +- **Signing:** Strong-named assemblies via `src/key.snk` |
| 64 | +- **Versioning:** Semantic versioning from git tags (`v` prefix) via MinVer |
| 65 | +- **Analysis:** All .NET analyzers enabled, AOT/trimming compatibility enforced |
| 66 | +- **Testing:** MSTest + FluentAssertions |
| 67 | +- **Dependencies:** Microsoft.Extensions.AI.Abstractions |
| 68 | + |
| 69 | +### Key Conventions |
| 70 | + |
| 71 | +- The client class is named `AssemblyAIClient` |
| 72 | +- The namespace is `AssemblyAI` |
| 73 | +- Use `TranscriptParams.FromUrl()` for creating transcript requests |
| 74 | +- Transcript results expose `EnsureStatusCompleted()` for polling validation |
| 75 | + |
| 76 | +### CI/CD |
| 77 | + |
| 78 | +- Uses shared workflows from `HavenDV/workflows` repo |
| 79 | +- Dependabot updates NuGet packages weekly (auto-merged) |
| 80 | +- Documentation deployed to GitHub Pages via MkDocs Material |
0 commit comments