Skip to content

CLAUDE.md

Latest commit

 

History

History
99 lines (71 loc) · 4.71 KB

CLAUDE.md

File metadata and controls

99 lines (71 loc) · 4.71 KB

CLAUDE.md

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

Project Overview

C# SDK for the Google Gemini generative AI API, auto-generated from a curated Google AI OpenAPI specification using AutoSDK. Published as NuGet package Google_Gemini.

Build Commands

# Build the solution
dotnet build Google.Gemini.slnx

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

# Run integration tests (requires GOOGLE_GEMINI_API_KEY or API_KEY env var)
dotnet test src/tests/IntegrationTests/Google.Gemini.IntegrationTests.csproj

# Regenerate SDK from OpenAPI spec
cd src/libs/Google.Gemini && ./generate.sh

Architecture

Code Generation Pipeline

The SDK code is entirely auto-generated -- do not manually edit files in src/libs/Google.Gemini/Generated/.

  1. src/libs/Google.Gemini/openapi.yaml -- the Google Gemini OpenAPI spec (fetched from a curated spec in the langchain_dart repo)
  2. src/libs/Google.Gemini/generate.sh -- orchestrates: download spec, fix spec, run AutoSDK CLI, output to Generated/
  3. CI auto-updates the spec and creates PRs if changes are detected

Project Layout

Project Purpose
src/libs/Google.Gemini/ Main SDK library (GeminiClient)
src/libs/Google.Gemini/Live/ Hand-written Live API (WebSocket) types and session
src/tests/IntegrationTests/ Integration tests against real Google Gemini API
samples/LiveVoiceAssistant/ Console app sample for Live API

Documentation Generation

Tests in src/tests/IntegrationTests/Examples are the single source of truth for both test coverage and documentation:

  • Each file has a JSDoc header (order, title, slug) consumed by autosdk docs sync .
  • Comments prefixed with //// become prose paragraphs in generated docs
  • CI workflow (.github/workflows/mkdocs.yml) auto-generates docs/examples/ and populates EXAMPLES:START/END markers in README.md, docs/index.md, and mkdocs.yml
  • Config: autosdk.docs.json points to src/tests/IntegrationTests/Examples

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 + AwesomeAssertions
  • NuGet Package ID: Google_Gemini (underscores due to NuGet naming restrictions)

Key Conventions

  • The client class is named GeminiClient
  • The namespace is Google.Gemini
  • Note the NuGet package ID uses underscores (Google_Gemini) while the namespace uses dots (Google.Gemini)

Hand-Written Extensions

While the HTTP API client is purely auto-generated, the following hand-written files extend the SDK:

Live API (WebSocket real-time streaming):

  • src/libs/Google.Gemini/Live/ — Message types for the bidirectional WebSocket protocol
    • LiveSetupConfig.cs — Session setup configuration
    • LiveClientMessage.cs — Client → server message union
    • LiveServerMessage.cs — Server → client message union + JSON parsing
    • LiveServerContent.cs — Model turn, transcriptions, interruption
    • LiveToolCall.cs — Tool call + cancellation wrappers
    • LiveRealtimeInput.cs — Audio/text/video input chunks
    • LiveGoAway.cs — Graceful disconnect notification
    • LiveSessionResumption.cs — Session resumption handle types
    • LiveJsonContext.cs — Source-generated JSON context for AOT (reserved)
    • GeminiLiveSession.cs — WebSocket session class (IAsyncDisposable)
    • ResilientLiveSession.cs — Auto-reconnect wrapper that handles GoAway messages
  • src/libs/Google.Gemini/Extensions/GeminiClientExtensions.Live.cs — ConnectLiveAsync and ConnectResilientLiveAsync factory methods

MEAI integration:

  • src/libs/Google.Gemini/Extensions/ — IChatClient and IEmbeddingGenerator implementations

Important: The Live API sends JSON as Binary WebSocket frames (not Text). Live-compatible models (e.g., models/gemini-3.1-flash-live-preview) support bidiGenerateContent and require AUDIO response modality. Gemini 3.1+ models use realtimeInput.text/audio/video instead of the deprecated clientContent and mediaChunks formats.

Samples

  • samples/LiveVoiceAssistant/ — Console app demonstrating the Live API (text-in/audio-out with transcription)

CI/CD

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