|
| 1 | +# Generative AI in .NET -- Companion Code |
| 2 | + |
| 3 | +Runnable code samples for **Generative AI in .NET** (Najaf Shaikh). |
| 4 | + |
| 5 | +Every sample in this repo corresponds to a section of the printed book. The full map between book and code lives in [`docs/citation-index.md`](docs/citation-index.md). When the book has been condensed in favor of pointing here, the manuscript cites a **tag** (e.g. `v1.0-print-ready`) so the code stays aligned with the print run. |
| 6 | + |
| 7 | +## Layout |
| 8 | + |
| 9 | +``` |
| 10 | +samples/ |
| 11 | + ch01-foundations/ |
| 12 | + 01.3-hello-chat/ -- IChatClient with provider selection |
| 13 | + 01.3-embeddings/ -- IEmbeddingGenerator + cosine similarity |
| 14 | + 01.4-secrets-and-config/ -- appsettings + user-secrets + env vars |
| 15 | + ch02-extensions-ai/ |
| 16 | + 02.1-console-chat-loop/ -- Sliding-window chat REPL |
| 17 | + 02.2-streaming-aspnet/ -- SSE streaming in a Minimal API |
| 18 | + 02.2-structured-output/ -- GetResponseAsync<T>() |
| 19 | + 02.3-function-calling/ -- Three-tool weather + calendar + reminders |
| 20 | + 02.4-middleware-pipeline/ -- Logging + caching pipeline |
| 21 | + 02.4-custom-middleware/ -- Token-budget DelegatingChatClient |
| 22 | + ch03-rag/ |
| 23 | + 03.1-semantic-search/ -- Embedding + cosine over a product catalog |
| 24 | + 03.2-rag-basic/ -- Retrieve / augment / generate |
| 25 | + 03.2-ingestion-pipeline/ -- Load + chunk + hash + embed + upsert |
| 26 | + 03.2.7-evaluation/ -- LLM-as-judge for RAG (faithfulness + relevance) |
| 27 | + 03.3-vision-extract/ -- Receipt image -> typed Receipt record |
| 28 | + 03.5-local-rag/ -- Local-only RAG (Ollama) |
| 29 | + ch04-agent-framework/ |
| 30 | + 04.2.1-hello-agent/ -- ChatClientAgent hello world |
| 31 | + 04.2.4-anthropic-agents/ -- Same agent API, Claude under the hood |
| 32 | + 04.3-persistent-session/ -- AgentThread serialize / resume |
| 33 | + 04.4-tools-and-approval/ -- Function tools + RequiresApproval marker |
| 34 | + 04.5-agent-middleware/ -- Custom run-middleware |
| 35 | + 04.6.3-text-processing-walkthrough/ -- Linear workflow walkthrough |
| 36 | + 04.6.7-content-workflow/ -- Researcher / Writer / Editor multi-agent |
| 37 | + 04.7-a2a-server/ -- Expose an agent via A2A protocol |
| 38 | + 04.8-agent-with-mcp/ -- Agent with mixed local + MCP tools |
| 39 | + ch05-mcp/ |
| 40 | + 05.2.10-inventory-server/ -- Full MCP server (tools + resources + prompts) |
| 41 | + 05.3.1-stdio-transport/ -- Minimal stdio server |
| 42 | + 05.3.2-sse-transport/ -- ASP.NET Core SSE transport |
| 43 | + 05.3.3-streamable-http/ -- Streamable HTTP (recommended) |
| 44 | + 05.4-mcp-client/ -- Interactive MCP client REPL |
| 45 | + 05.6.3-mcp-agent-factory/ -- McpAgentFactory |
| 46 | + cached-mcp-tool-provider/ -- CachedMcpToolProvider (Critical-1 fix) |
| 47 | + ch06-production/ |
| 48 | + 06.1-observability/ -- OpenTelemetry tracing + OTLP export |
| 49 | + 06.2.1-resilience/ -- Standard resilience handler |
| 50 | + 06.2.4-model-routing/ -- Classify-then-route cost optimization |
| 51 | + 06.5.1-unit-testing/ -- xUnit + StubChatClient |
| 52 | + 06.5.3-llm-as-judge/ -- Evaluation harness |
| 53 | + output-guard-chat-client/ -- OutputGuardChatClient (Critical-3 fix) |
| 54 | +docs/ |
| 55 | + citation-index.md |
| 56 | + version-matrix.md |
| 57 | +.github/workflows/ci.yml |
| 58 | +Directory.Packages.props |
| 59 | +global.json |
| 60 | +``` |
| 61 | + |
| 62 | +## Prerequisites |
| 63 | + |
| 64 | +- **.NET 9 SDK** (`dotnet --version` should be 9.0.x). |
| 65 | +- **Provider credentials** for samples that hit a live model -- each sample's README names what it needs: |
| 66 | + - `OPENAI_API_KEY` for OpenAI / GitHub Models samples. |
| 67 | + - `AZURE_OPENAI_ENDPOINT` + `AZURE_OPENAI_KEY` for Azure OpenAI samples. |
| 68 | + - `ANTHROPIC_API_KEY` for Claude samples. |
| 69 | +- **Local services** for offline samples: [Ollama](https://ollama.com/) for local inference; an MCP-compatible runtime (`dnx`) for some MCP samples. |
| 70 | + |
| 71 | +The repo uses **central package management** -- versions live in [`Directory.Packages.props`](Directory.Packages.props), shared properties in [`samples/Directory.Build.props`](samples/Directory.Build.props). Project files only carry `<PackageReference Include="..." />` -- no version attributes. |
| 72 | + |
| 73 | +## Running a sample |
| 74 | + |
| 75 | +```bash |
| 76 | +dotnet run --project samples/ch04-agent-framework/04.6.3-text-processing-walkthrough |
| 77 | +``` |
| 78 | + |
| 79 | +Each sample folder has its own `README.md` with run instructions, expected output, and the manuscript section it backs. |
| 80 | + |
| 81 | +## Building everything |
| 82 | + |
| 83 | +```bash |
| 84 | +dotnet build |
| 85 | +``` |
| 86 | + |
| 87 | +## What's offline-runnable |
| 88 | + |
| 89 | +These samples need **only** Ollama (no API keys, no cloud calls): |
| 90 | + |
| 91 | +- `ch01/01.3-hello-chat` (default profile), `01.3-embeddings`, `01.4-secrets-and-config` |
| 92 | +- `ch02/02.1-console-chat-loop`, `02.2-streaming-aspnet`, `02.4-middleware-pipeline`, `02.4-custom-middleware` |
| 93 | +- `ch03/03.1-semantic-search`, `03.2-rag-basic`, `03.2-ingestion-pipeline`, `03.5-local-rag` |
| 94 | +- `ch04/04.2.1-hello-agent`, `04.3-persistent-session`, `04.5-agent-middleware`, `04.7-a2a-server` |
| 95 | +- `ch05/*` (all MCP samples; `05.4-mcp-client` needs a server to talk to) |
| 96 | +- `ch06/06.1-observability`, `06.2.1-resilience`, `06.5.1-unit-testing`, `output-guard-chat-client` |
| 97 | + |
| 98 | +The rest assume an OpenAI / Anthropic / Azure OpenAI key. |
| 99 | + |
| 100 | +## Versioning and tags |
| 101 | + |
| 102 | +| Tag | Meaning | |
| 103 | +|---|---| |
| 104 | +| `v1.0-print-ready` | Code as it appears in the first print run. | |
| 105 | +| `v1.x-second-print` | Updated for subsequent print revisions. | |
| 106 | +| `main` | Always-current; may drift from any specific print run. | |
| 107 | + |
| 108 | +Use a **tag** in any URL you cite from the book -- never `main`. |
| 109 | + |
| 110 | +## Errata |
| 111 | + |
| 112 | +Open an issue at [github.com/CodeShayk/generative-ai-dotnet-samples](https://github.com/CodeShayk/generative-ai-dotnet-samples). Confirmed errata roll into the next print tag and are noted in the parent book's errata page. |
| 113 | + |
| 114 | +## License |
| 115 | + |
| 116 | +MIT -- see [`LICENSE`](LICENSE). |
0 commit comments