diff --git a/README.md b/README.md index 03abcc2..87a7c37 100644 --- a/README.md +++ b/README.md @@ -12,8 +12,19 @@ The Model Command Line Interface (M-CLI) is a minimalist tool designed for devel ## Configuration This sample requires configuration setting in order to connect to remote services. You will need to define settings for Azure Open AI. ```powershell -// Generated by Copilot dotnet user-secrets set "AzureOpenAISettings:ApiKey" "" dotnet user-secrets set "AzureOpenAISettings:Endpoint" "" dotnet user-secrets set "AzureOpenAISettings:ChatModelDeployment" "gpt-4o" ``` + +## Documentation + +Detailed documentation is available in the [`doc/`](doc/README.md) folder: + +| Document | Description | +|----------|-------------| +| [Project Overview](doc/project-overview.md) | Architecture, design philosophy, external dependencies, and potential features | +| [Getting Started](doc/getting-started.md) | Prerequisites, installation, and first-run walkthrough | +| [Configuration Guide](doc/configuration.md) | Azure OpenAI settings, AI parameters, and advanced options | +| [Tools Reference](doc/tools-reference.md) | Kernel functions available to the AI agent | +| [Troubleshooting](doc/troubleshooting.md) | Common issues and solutions | diff --git a/doc/README.md b/doc/README.md index 251218a..03dd0f0 100644 --- a/doc/README.md +++ b/doc/README.md @@ -9,7 +9,7 @@ Welcome to the **CardMaker** project documentation! This AI-powered tool helps y - [**Configuration Guide**](configuration.md) - Setting up Azure OpenAI and user secrets ### πŸ“– Project Information -- [**Project Overview**](project-overview.md) - Architecture and design philosophy +- [**Project Overview**](project-overview.md) - Architecture, design philosophy, external dependencies, and potential features - [**Tools Reference**](tools-reference.md) - Available AI tools and functions ### πŸ› οΈ Support diff --git a/doc/project-overview.md b/doc/project-overview.md index 1dcbcf1..3fa491d 100644 --- a/doc/project-overview.md +++ b/doc/project-overview.md @@ -177,6 +177,45 @@ Example card structure: } ``` +## 🌐 External Dependencies + +CardMaker relies on the following external services and libraries. All must be available for the application to function. + +### Required External Services + +| Service | Purpose | Configuration Key | Notes | +|---------|---------|-------------------|-------| +| **Azure OpenAI** – Chat Completion | Drives the AI assistant that generates card content | `AzureOpenAISettings:Endpoint`, `AzureOpenAISettings:ApiKey`, `AzureOpenAISettings:ChatModelDeployment` | Requires a deployed model (e.g., `gpt-4o`). The endpoint must be a valid Azure OpenAI resource URL in the form `https://.openai.azure.com/`. | +| **Azure OpenAI** – Assistants API | Creates and manages the stateful OpenAI Assistant and its thread | Same credentials as above | Uses `OpenAIAssistantAgent` from `Microsoft.SemanticKernel.Agents.OpenAI`. The assistant is created on startup and deleted on exit. | +| **Azure OpenAI** – Vector Stores | Provides a RAG (Retrieval-Augmented Generation) knowledge base for the assistant | Same credentials as above | An empty vector store is created on startup and deleted on exit. File upload to the store is commented out by default; see `Program.cs` lines 35-42. | + +### Optional / Implicit Network Dependencies + +| Service | Purpose | Notes | +|---------|---------|-------| +| **Bing Search** (`www.bing.com`) | Target URL embedded in generated QR codes | The `create_qr_code` tool builds a URL of the form `https://www.bing.com/search?q=+site:learn.microsoft.com`. No API key is required; the URL is encoded in the QR image. | +| **Microsoft Learn** (`learn.microsoft.com`) | Documentation destination for QR codes | Reachable by end-users who scan generated QR codes. No direct API call is made. | + +### NuGet Package Dependencies + +| Package | Version | Purpose | +|---------|---------|---------| +| `Microsoft.SemanticKernel` | 1.32.0 | AI orchestration and kernel plugin system | +| `Microsoft.SemanticKernel.Agents.OpenAI` | 1.32.0-alpha | OpenAI Assistants API integration | +| `Microsoft.SemanticKernel.Yaml` | 1.32.0 | YAML prompt template loading | +| `Azure.AI.OpenAI.Assistants` | 1.0.0-beta.4 | Azure OpenAI Assistants client | +| `Azure.Identity` | 1.13.1 | Azure authentication | +| `QRCoder` | 1.6.0 | QR code image generation | +| `TextCopy` | 6.2.1 | System clipboard access | +| `System.Drawing.Common` | 9.0.0 | Bitmap image handling (Windows-only) | +| `ConsoleTextFormat` | 1.3.0 | Unicode escape-code terminal formatting | +| `Microsoft.Extensions.Configuration` | 9.0.0 | Configuration/user-secrets binding | +| `OpenTelemetry.Exporter.Console` | 1.10.0 | Optional observability tracing | + +> ⚠️ **Platform note:** `System.Drawing.Common` and `TextCopy` clipboard operations require a Windows host. The project target framework is `net9.0-windows`. + +--- + ## 🌟 Extensibility ### Adding New Tools @@ -194,4 +233,42 @@ Example card structure: 2. Update agent prompt documents 3. Include additional vector store files +--- + +## πŸš€ Potential Features + +The following are ideas for extending CardMaker beyond its current capabilities. + +### Card Generation & Content +| Feature | Description | +|---------|-------------| +| **Multi-deck themes** | Support themes beyond Platform Engineering (e.g., DevSecOps, Cloud Architecture, SRE). | +| **Custom card ranks and suits** | Allow users to configure the number of suits and card values, or use non-standard decks. | +| **AI image generation** | Integrate Azure OpenAI DALLΒ·E or another image model to generate card artwork automatically. | +| **Card validation** | Add a tool that checks generated JSON against a schema to ensure all required fields are present before saving. | + +### Output & Integration +| Feature | Description | +|---------|-------------| +| **PDF/print export** | Generate print-ready PDFs directly from JSON card specs, removing the manual Illustrator data-merge step. | +| **Web UI** | Wrap the CLI in a lightweight web front-end (e.g., Blazor or React) to make card creation accessible without a terminal. | +| **Template marketplace** | Provide downloadable card face templates (SVG/Illustrator) alongside the JSON specs. | +| **CSV / Excel export** | Export card data to spreadsheet formats for non-technical stakeholders. | + +### AI & Knowledge +| Feature | Description | +|---------|-------------| +| **Populated vector store** | Pre-load the vector store with curated Platform Engineering documentation so the assistant has richer domain knowledge out of the box. | +| **Multi-model support** | Allow switching between Azure OpenAI and standard OpenAI endpoints (the `OpenAISettings` class in `Settings.cs` already defines a skeleton for this). | +| **Feedback loop** | Let users rate generated cards and feed that signal back to refine prompts or fine-tune a model. | +| **Localization** | Generate card content in multiple languages using a language parameter passed to the agent. | + +### Developer Experience +| Feature | Description | +|---------|-------------| +| **Unit tests** | Add a test project covering `Tools.cs` and `Settings.cs` to enable CI validation. | +| **Cross-platform support** | Replace `System.Drawing.Common` with a cross-platform imaging library (e.g., ImageSharp) to allow Linux/macOS execution. | +| **Docker image** | Publish a Docker image so the tool can run in containerized environments without a local .NET SDK install. | +| **Configuration wizard** | Add an interactive first-run setup that prompts for Azure OpenAI credentials instead of requiring manual `dotnet user-secrets` commands. | + Ready to dive deeper? Check out the [**Tools Reference**](tools-reference.md) for detailed function documentation! πŸ”§ \ No newline at end of file