Imported from tryAGI/OpenAI (AGENTS.md). Install upstream with npx skills add tryAGI/OpenAI. Copyright stays with the author.

AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.

Project Overview

C# SDK for the OpenAI API, auto-generated from the official OpenAI OpenAPI specification using 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.

Build Commands

# Build the solution
dotnet build OpenAI.slnx

# Build for release (also produces NuGet package)
dotnet build OpenAI.slnx -c Release

# Run integration tests (requires OPENAI_API_KEY env var)
dotnet test src/tests/OpenAI.IntegrationTests/OpenAI.IntegrationTests.csproj

# Run snapshot tests for CSharpToJsonSchema
dotnet test src/tests/CSharpToJsonSchema.SnapshotTests/CSharpToJsonSchema.SnapshotTests.csproj

# Run unit tests for CSharpToJsonSchema
dotnet test src/tests/CSharpToJsonSchema.UnitTests/CSharpToJsonSchema.UnitTests.csproj

# Regenerate SDK from OpenAPI spec
cd src/libs/tryAGI.OpenAI && ./generate.sh

Architecture

Code Generation Pipeline

The SDK code in Generated/ is auto-generated -- do not manually edit files in src/libs/tryAGI.OpenAI/Generated/.

1. src/libs/tryAGI.OpenAI/openapi.yaml -- the OpenAI OpenAPI spec (fetched from Stainless)
2. src/libs/tryAGI.OpenAI/generate.sh -- orchestrates: download spec, run AutoSDK CLI, output to Generated/
3. CI auto-updates the spec and creates PRs if changes are detected

Hand-Written Extensions

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.

Project Layout

Key Dependencies

• CSharpToJsonSchema -- source generator for defining tools/functions via C# interfaces
• Tiktoken -- token counting for pricing calculations
• System.Net.ServerSentEvents APIs in .NET 10 -- SSE parsing for generated streaming endpoints

Build Configuration

• Target: net10.0 (single target)
• Language: C# preview with nullable reference types
• Signing: Strong-named assemblies via src/key.snk
• Versioning: Semantic versioning from git tags (v prefix) via MinVer
• Analysis: All .NET analyzers enabled, AOT/trimming compatibility enforced
• Testing: MSTest + FluentAssertions
• CLS Compliant: Assembly marked as CLS-compliant

CI/CD

• Uses shared workflows from HavenDV/workflows repo
• Dependabot updates NuGet packages weekly (auto-merged)
• Documentation deployed to GitHub Pages via MkDocs Material

Key Conventions

• The NuGet package name is tryAGI.OpenAI (not just OpenAI) to avoid conflicts with the official OpenAI package
• The main client class is OpenAiApi (for backward compatibility) with OpenAiClient as the generated variant
• Custom providers are accessed via static factory methods on CustomProviders class (e.g., CustomProviders.Azure(...))