A .NET client library for BAML (Basically a Made-up Language) that uses C# Source Generators to provide type-safe, compile-time code generation for AI workflows and agents.
This library brings the power of BAML to the .NET ecosystem, allowing developers to define AI functions in BAML schema files and automatically generate strongly-typed C# client code. The library provides both synchronous and asynchronous APIs, with full support for streaming responses.
- Type-Safe Code Generation: Automatically generates C# types and client methods from BAML schema files
- Source Generators: Compile-time code generation with no runtime reflection
- Async/Await Support: Modern .NET async patterns throughout
- Streaming Support: Real-time streaming responses using
IAsyncEnumerable<T> - Error Handling: Comprehensive exception handling with BAML-specific error types
- Configurable Runtime: Flexible configuration for different BAML endpoints and authentication
- MSBuild Integration: Seamless integration with .NET build process
Install the BAML packages from NuGet:
dotnet add package Baml.Runtime
dotnet add package Baml.SourceGeneratorOr add them to your project file:
<ItemGroup>
<PackageReference Include="Baml.Runtime" Version="1.0.0" />
<PackageReference Include="Baml.SourceGenerator" Version="1.0.0" />
</ItemGroup>Add the BAML libraries to your project:
<ItemGroup>
<ProjectReference Include="path/to/Baml.Runtime/Baml.Runtime.csproj" />
<ProjectReference Include="path/to/Baml.SourceGenerator/Baml.SourceGenerator.csproj" />
</ItemGroup>Create a .baml file in your project (e.g., chat_agent.baml):
class Message {
role string
content string
}
class ReplyTool {
response string
}
function ChatAgent(messages: Message[], tone: "happy" | "sad") -> ReplyTool {
client "openai/gpt-4o-mini"
prompt #"
Be a {{ tone }} bot.
{{ ctx.output_format }}
{% for m in messages %}
{{ _.role(m.role) }}
{{ m.content }}
{% endfor %}
"#
}
Add the BAML file to your project:
<ItemGroup>
<AdditionalFiles Include="chat_agent.baml" />
</ItemGroup>using Baml.Runtime;
using Baml.Generated;
// Configure the runtime
var configuration = new BamlConfiguration
{
ApiEndpoint = "http://localhost:8000/api/baml/call",
StreamingEndpoint = "http://localhost:8000/api/baml/stream",
ApiKey = Environment.GetEnvironmentVariable("BAML_API_KEY")
};
// Create client
using var runtime = new BamlRuntime(configuration);
var client = new BamlGeneratedClient(runtime);
// Call BAML function
var messages = new List<Message>
{
new Message { Role = "user", Content = "Hello!" }
};
var response = await client.ChatAgentAsync(messages, "happy");
Console.WriteLine(response.Response);- Baml.Runtime: Core runtime library for HTTP communication and serialization
- Baml.SourceGenerator: C# Source Generator that parses BAML files and generates client code
- Generated Code: Type-safe client interfaces and implementations
- Build Time: Source generator discovers
.bamlfiles in the project - Parsing: BAML files are parsed to extract functions, classes, and enums
- Generation: C# code is generated for types and client methods
- Compilation: Generated code is compiled alongside your application code
// Simple text extraction
var result = await client.ExtractInfoAsync(
"John Doe is a software engineer at Microsoft.");
Console.WriteLine($"Extracted: {result}");// Streaming chat
await foreach (var chunk in client.StreamChatAgentAsync(messages, "happy"))
{
Console.Write(chunk.Response);
}try
{
var result = await client.ChatAgentAsync(messages, "happy");
// Handle success
}
catch (BamlFunctionException ex)
{
Console.WriteLine($"BAML function '{ex.FunctionName}' failed: {ex.Message}");
}
catch (BamlConfigurationException ex)
{
Console.WriteLine($"Configuration error: {ex.Message}");
}var configuration = new BamlConfiguration
{
ApiEndpoint = "http://localhost:8000/api/baml/call", // Required
StreamingEndpoint = "http://localhost:8000/api/baml/stream", // Required for streaming
ApiKey = "your-api-key", // Optional
Timeout = TimeSpan.FromMinutes(5) // Optional, default 5 minutes
};The library supports configuration via environment variables:
BAML_API_KEY: API key for authenticationBAML_API_ENDPOINT: Override default API endpointBAML_STREAMING_ENDPOINT: Override default streaming endpoint
- Primitives:
string,int,float,double,bool - Arrays:
Type[](mapped toIEnumerable<Type>) - Custom Classes: User-defined classes with properties
- Enums: String-based enumerations
- Union Types:
Type1 | Type2(mapped toobject)
function FunctionName(param1: Type1, param2: Type2) -> ReturnType {
client "model-provider/model-name"
prompt #"Your prompt template here"#
}
class ClassName {
property1 string
property2 int
property3 CustomType @description("Optional description")
}
enum StatusType {
"active"
"inactive"
"pending"
}
using var httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Add("Custom-Header", "value");
var runtime = new BamlRuntime(configuration, httpClient);// In Startup.cs or Program.cs
services.AddSingleton<BamlConfiguration>(provider => new BamlConfiguration
{
ApiEndpoint = "http://localhost:8000/api/baml/call",
ApiKey = Environment.GetEnvironmentVariable("BAML_API_KEY")
});
services.AddScoped<IBamlRuntime, BamlRuntime>();
services.AddScoped<IBamlGeneratedClient, BamlGeneratedClient>();- .NET 8.0 SDK or later
- Git
git clone <repository-url>
cd baml-dotnet
dotnet restore
dotnet buildUse the provided scripts to build NuGet packages for testing:
Linux/macOS:
./scripts/build-packages.shWindows:
.\scripts\build-packages.ps1Options:
-SkipTests: Skip running tests (PowerShell only)-TestInstall: Test package installation after building (PowerShell only)
# Simple example
cd examples/SimpleExample
dotnet run
# Streaming example
cd examples/StreamingExample
dotnet rundotnet testbaml-dotnet/
├── src/
│ ├── Baml.Runtime/ # Core runtime library
│ └── Baml.SourceGenerator/ # Source generator
├── examples/
│ ├── SimpleExample/ # Basic usage example
│ └── StreamingExample/ # Streaming example
├── tests/
│ ├── Baml.Runtime.Tests/
│ └── Baml.SourceGenerator.Tests/
└── README.md
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests for new functionality
- Ensure all tests pass
- Submit a pull request
This project is licensed under the Apache 2.0 License - see the LICENSE file for details.
- BAML Project - The original BAML language and runtime
- Microsoft Roslyn - C# Source Generators infrastructure
For issues and questions:
- Check the examples for common usage patterns
- Review the BAML documentation
- Open an issue on GitHub
- Baml.Runtime:
- Baml.SourceGenerator:
- Release packages: Published from git tags (e.g.,
v1.0.0→1.0.0) - Preview packages: Published from main branch commits (e.g.,
1.0.0-preview.42)