|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +This file provides guidance to Codex (Codex.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +C# SDK for the [OpenAI](https://openai.com/) API, auto-generated from the official OpenAI OpenAPI specification using [AutoSDK](https://github.com/tryAGI/AutoSDK). Published as the `tryAGI.OpenAI` NuGet package. Includes support for custom providers (Azure, DeepSeek, Groq, Ollama, OpenRouter, Together, and many more), a source generator for native C# function/tool definitions, pricing constants, and structured output helpers. |
| 8 | + |
| 9 | +## Build Commands |
| 10 | + |
| 11 | +```bash |
| 12 | +# Build the solution |
| 13 | +dotnet build OpenAI.slnx |
| 14 | + |
| 15 | +# Build for release (also produces NuGet package) |
| 16 | +dotnet build OpenAI.slnx -c Release |
| 17 | + |
| 18 | +# Run integration tests (requires OPENAI_API_KEY env var) |
| 19 | +dotnet test src/tests/OpenAI.IntegrationTests/OpenAI.IntegrationTests.csproj |
| 20 | + |
| 21 | +# Run snapshot tests for CSharpToJsonSchema |
| 22 | +dotnet test src/tests/CSharpToJsonSchema.SnapshotTests/CSharpToJsonSchema.SnapshotTests.csproj |
| 23 | + |
| 24 | +# Run unit tests for CSharpToJsonSchema |
| 25 | +dotnet test src/tests/CSharpToJsonSchema.UnitTests/CSharpToJsonSchema.UnitTests.csproj |
| 26 | + |
| 27 | +# Regenerate SDK from OpenAPI spec |
| 28 | +cd src/libs/tryAGI.OpenAI && ./generate.sh |
| 29 | +``` |
| 30 | + |
| 31 | +## Architecture |
| 32 | + |
| 33 | +### Code Generation Pipeline |
| 34 | + |
| 35 | +The SDK code in `Generated/` is **auto-generated** -- do not manually edit files in `src/libs/tryAGI.OpenAI/Generated/`. |
| 36 | + |
| 37 | +1. `src/libs/tryAGI.OpenAI/openapi.yaml` -- the OpenAI OpenAPI spec (fetched from Stainless) |
| 38 | +2. `src/libs/tryAGI.OpenAI/generate.sh` -- orchestrates: download spec, run AutoSDK CLI, output to `Generated/` |
| 39 | +3. CI auto-updates the spec and creates PRs if changes are detected |
| 40 | + |
| 41 | +### Hand-Written Extensions |
| 42 | + |
| 43 | +Unlike most other tryAGI SDKs, this repo has significant **hand-written code** alongside the generated code. Prefer moving behavior to AutoSDK/spec inputs when it improves client UX, and avoid maintaining manual `AsStream` wrappers when the generated surface can represent the same API directly. |
| 44 | + |
| 45 | +| Path | Purpose | |
| 46 | +|------|---------| |
| 47 | +| `Metadata/` | Pricing constants and model metadata (chat, embedding, images, TTS, STT) | |
| 48 | +| `Conversions/` | Implicit conversions for `ChatCompletionRequestMessage`, `CreateMessageRequest`, etc. | |
| 49 | +| `Extensions/StringExtensions.cs` | Helper extension methods | |
| 50 | +| `CustomProviders.cs` | Factory methods for Azure, DeepSeek, Groq, Ollama, OpenRouter, etc. | |
| 51 | +| `ChatClient.CreateChatCompletion.As.cs` | Structured output (`CreateChatCompletionAsAsync<T>`) | |
| 52 | +| `RealtimeConversationClient.cs` | Realtime API WebSocket client | |
| 53 | +| `OpenAiApi.Headers.cs` | Custom header helpers | |
| 54 | +| `TypeToSchemaHelpers.cs` | JSON schema generation helpers for tools | |
| 55 | +| `Image.Bytes.cs` | Image byte conversion helpers | |
| 56 | + |
| 57 | +### Project Layout |
| 58 | + |
| 59 | +| Project | Purpose | |
| 60 | +|---------|---------| |
| 61 | +| `src/libs/tryAGI.OpenAI/` | Main SDK library (`OpenAiClient` / `OpenAiApi`) | |
| 62 | +| `src/tests/OpenAI.IntegrationTests/` | Integration tests against real OpenAI API and custom providers | |
| 63 | +| `src/tests/CSharpToJsonSchema.SnapshotTests/` | Snapshot tests for schema generation | |
| 64 | +| `src/tests/CSharpToJsonSchema.UnitTests/` | Unit tests for schema generation | |
| 65 | +| `src/helpers/GenerateDocs/` | Documentation generator from integration tests | |
| 66 | +| `src/helpers/TrimmingHelper/` | NativeAOT/trimming compatibility validator | |
| 67 | + |
| 68 | +### Key Dependencies |
| 69 | + |
| 70 | +- `CSharpToJsonSchema` -- source generator for defining tools/functions via C# interfaces |
| 71 | +- `Tiktoken` -- token counting for pricing calculations |
| 72 | +- `System.Net.ServerSentEvents` APIs in .NET 10 -- SSE parsing for generated streaming endpoints |
| 73 | + |
| 74 | +### Build Configuration |
| 75 | + |
| 76 | +- **Target:** `net10.0` (single target) |
| 77 | +- **Language:** C# preview with nullable reference types |
| 78 | +- **Signing:** Strong-named assemblies via `src/key.snk` |
| 79 | +- **Versioning:** Semantic versioning from git tags (`v` prefix) via MinVer |
| 80 | +- **Analysis:** All .NET analyzers enabled, AOT/trimming compatibility enforced |
| 81 | +- **Testing:** MSTest + FluentAssertions |
| 82 | +- **CLS Compliant:** Assembly marked as CLS-compliant |
| 83 | + |
| 84 | +### CI/CD |
| 85 | + |
| 86 | +- Uses shared workflows from `HavenDV/workflows` repo |
| 87 | +- Dependabot updates NuGet packages weekly (auto-merged) |
| 88 | +- Documentation deployed to GitHub Pages via MkDocs Material |
| 89 | + |
| 90 | +## Key Conventions |
| 91 | + |
| 92 | +- The NuGet package name is `tryAGI.OpenAI` (not just `OpenAI`) to avoid conflicts with the official OpenAI package |
| 93 | +- The main client class is `OpenAiApi` (for backward compatibility) with `OpenAiClient` as the generated variant |
| 94 | +- Custom providers are accessed via static factory methods on `CustomProviders` class (e.g., `CustomProviders.Azure(...)`) |
0 commit comments