From a774fa0e97a8c0d02b85c8f6ee25f98f5614086a Mon Sep 17 00:00:00 2001 From: Thorsten Sommer Date: Tue, 27 Jan 2026 07:58:21 +0100 Subject: [PATCH] Add AGENTS.md for project guidance and architecture details --- AGENTS.md | 185 +++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 186 +----------------------------------------------------- 2 files changed, 186 insertions(+), 185 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..02078f06 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,185 @@ +# AGENTS.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +MindWork AI Studio is a cross-platform desktop application for interacting with Large Language Models (LLMs). The app uses a hybrid architecture combining a Rust Tauri runtime (for the native desktop shell) with a .NET Blazor Server web application (for the UI and business logic). + +**Key Architecture Points:** +- **Runtime:** Rust-based Tauri v1.8 application providing the native window, system integration, and IPC layer +- **App:** .NET 9 Blazor Server application providing the UI and core functionality +- **Communication:** The Rust runtime and .NET app communicate via HTTPS with TLS certificates generated at startup +- **Providers:** Multi-provider architecture supporting OpenAI, Anthropic, Google, Mistral, Perplexity, self-hosted models, and others +- **Plugin System:** Lua-based plugin system for language packs, configuration, and future assistant plugins + +## Building + +### Prerequisites +- .NET 9 SDK +- Rust toolchain (stable) +- Tauri v1.6.2 CLI: `cargo install --version 1.6.2 tauri-cli` +- Tauri prerequisites (platform-specific dependencies) +- **Note:** Development on Linux is discouraged due to complex Tauri dependencies that vary by distribution + +### Build +```bash +cd app/Build +dotnet run build +``` +This builds the .NET app as a Tauri "sidecar" binary, which is required even for development. + + +### Running Tests +Currently, no automated test suite exists in the repository. + +## Architecture Details + +### Rust Runtime (`runtime/`) +**Entry point:** `runtime/src/main.rs` + +Key modules: +- `app_window.rs` - Tauri window management, updater integration +- `dotnet.rs` - Launches and manages the .NET sidecar process +- `runtime_api.rs` - Rocket-based HTTPS API for .NET ↔ Rust communication +- `certificate.rs` - Generates self-signed TLS certificates for secure IPC +- `secret.rs` - Secure secret storage using OS keyring (Keychain/Credential Manager) +- `clipboard.rs` - Cross-platform clipboard operations +- `file_data.rs` - File processing for RAG (extracts text from PDF, DOCX, XLSX, PPTX, etc.) +- `encryption.rs` - AES-256-CBC encryption for sensitive data +- `pandoc.rs` - Integration with Pandoc for document conversion +- `log.rs` - Logging infrastructure using `flexi_logger` + +### .NET App (`app/MindWork AI Studio/`) +**Entry point:** `app/MindWork AI Studio/Program.cs` + +Key structure: +- **Program.cs** - Bootstraps Blazor Server, configures Kestrel, initializes encryption and Rust service +- **Provider/** - LLM provider implementations (OpenAI, Anthropic, Google, Mistral, etc.) + - `BaseProvider.cs` - Abstract base for all providers with streaming support + - `IProvider.cs` - Provider interface defining capabilities and streaming methods +- **Chat/** - Chat functionality and message handling +- **Assistants/** - Pre-configured assistants (translation, summarization, coding, etc.) + - `AssistantBase.razor` - Base component for all assistants +- **Agents/** - contains all agents, e.g., for data source selection, context validation, etc. + - `AgentDataSourceSelection.cs` - Selects appropriate data sources for queries + - `AgentRetrievalContextValidation.cs` - Validates retrieved context relevance +- **Tools/PluginSystem/** - Lua-based plugin system +- **Tools/Services/** - Core background services (settings, message bus, data sources, updates) +- **Tools/Rust/** - .NET wrapper for Rust API calls +- **Settings/** - Application settings and data models +- **Components/** - Reusable Blazor components +- **Pages/** - Top-level page components + +### IPC Communication Flow +1. Rust runtime starts and generates TLS certificate +2. Rust starts internal HTTPS API on random port +3. Rust launches .NET sidecar, passing: API port, certificate fingerprint, API token, secret key +4. .NET reads environment variables and establishes secure HTTPS connection to Rust +5. .NET requests an app port from Rust, starts Blazor Server on that port +6. Rust opens Tauri webview pointing to localhost:app_port +7. Bi-directional communication: .NET ↔ Rust via HTTPS API + +### Configuration and Metadata +- `metadata.txt` - Build metadata (version, build time, component versions) read by both Rust and .NET +- `startup.env` - Development environment variables (generated by build script) +- `.NET project` reads metadata.txt at build time and injects as assembly attributes + +## Plugin System + +**Location:** `app/MindWork AI Studio/Plugins/` + +Plugins are written in Lua and provide: +- **Language plugins** - I18N translations (e.g., German language pack) +- **Configuration plugins** - Enterprise IT configurations for centrally managed providers, settings +- **Future:** Assistant plugins for custom assistants + +**Example configuration plugin:** `app/MindWork AI Studio/Plugins/configuration/plugin.lua` + +Plugins can configure: +- Self-hosted LLM providers +- Update behavior +- Preview features visibility +- Preselected profiles +- Chat templates +- etc. + +When adding configuration options, update: +- `app/MindWork AI Studio/Tools/PluginSystem/PluginConfiguration.cs`: In method `TryProcessConfiguration` register new options. +- `app/MindWork AI Studio/Tools/PluginSystem/PluginFactory.Loading.cs`: In method `LoadAll` check for leftover configuration. +- The corresponding data class in `app/MindWork AI Studio/Settings/DataModel/` to call `ManagedConfiguration.Register(...)`, when adding config options (in contrast to complex config. objects) +- `app/MindWork AI Studio/Tools/PluginSystem/PluginConfigurationObject.cs` for parsing logic of complex configuration objects. +- `app/MindWork AI Studio/Plugins/configuration/plugin.lua` to document the new configuration option. + +## RAG (Retrieval-Augmented Generation) + +RAG integration is currently in development (preview feature). Architecture: +- **External Retrieval Interface (ERI)** - Contract for integrating external data sources +- **Data Sources** - Local files and external data via ERI servers +- **Agents** - AI agents select data sources and validate retrieval quality +- **Embedding providers** - Support for various embedding models +- **Vector database** - Planned integration with Qdrant for vector storage +- **File processing** - Extracts text from PDF, DOCX, XLSX via Rust runtime + +## Enterprise IT Support + +AI Studio supports centralized configuration for enterprise environments: +- **Registry (Windows)** or **environment variables** (all platforms) specify configuration server URL and ID +- Configuration downloaded as ZIP containing Lua plugin +- Checks for updates every ~16 minutes via ETag +- Allows IT departments to pre-configure providers, settings, and chat templates + +**Documentation:** `documentation/Enterprise IT.md` + +## Provider Confidence System + +Multi-level confidence scheme allows users to control which providers see which data: +- Confidence levels: e.g. `NONE`, `LOW`, `MEDIUM`, `HIGH`, and some more granular levels +- Each assistant/feature can require a minimum confidence level +- Users assign confidence levels to providers based on trust + +**Implementation:** `app/MindWork AI Studio/Provider/Confidence.cs` + +## Dependencies and Frameworks + +**Rust:** +- Tauri 1.8 - Desktop application framework +- Rocket 0.5 - HTTPS API server +- tokio - Async runtime +- keyring - OS keyring integration +- pdfium-render - PDF text extraction +- calamine - Excel file parsing + +**.NET:** +- Blazor Server - UI framework +- MudBlazor 8.12 - Component library +- LuaCSharp - Lua scripting engine +- HtmlAgilityPack - HTML parsing +- ReverseMarkdown - HTML to Markdown conversion + +## Security + +- **Encryption:** AES-256-CBC with PBKDF2 key derivation for sensitive data +- **IPC:** TLS-secured communication with random ports and API tokens +- **Secrets:** OS keyring for persistent secret storage (API keys, etc.) +- **Sandboxing:** Tauri provides OS-level sandboxing + +## Release Process + +1. Create changelog file: `app/MindWork AI Studio/wwwroot/changelog/vX.Y.Z.md` +2. Commit changelog +3. Run from `app/Build`: `dotnet run release --action ` +4. Create PR with version bump and changes +5. After PR merge, maintainer creates git tag: `vX.Y.Z` +6. GitHub Actions builds release binaries for all platforms +7. Binaries uploaded to GitHub Releases + +## Important Development Notes + +- **File changes require Write/Edit tools** - Never use bash commands like `cat <` +- **Spaces in paths** - Always quote paths with spaces in bash commands +- **Debug environment** - Reads `startup.env` file with IPC credentials +- **Production environment** - Runtime launches .NET sidecar with environment variables +- **MudBlazor** - Component library requires DI setup in Program.cs +- **Encryption** - Initialized before Rust service is marked ready +- **Message Bus** - Singleton event bus for cross-component communication inside the .NET app diff --git a/CLAUDE.md b/CLAUDE.md index 689378d2..eef4bd20 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,185 +1 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Project Overview - -MindWork AI Studio is a cross-platform desktop application for interacting with Large Language Models (LLMs). The app uses a hybrid architecture combining a Rust Tauri runtime (for the native desktop shell) with a .NET Blazor Server web application (for the UI and business logic). - -**Key Architecture Points:** -- **Runtime:** Rust-based Tauri v1.8 application providing the native window, system integration, and IPC layer -- **App:** .NET 9 Blazor Server application providing the UI and core functionality -- **Communication:** The Rust runtime and .NET app communicate via HTTPS with TLS certificates generated at startup -- **Providers:** Multi-provider architecture supporting OpenAI, Anthropic, Google, Mistral, Perplexity, self-hosted models, and others -- **Plugin System:** Lua-based plugin system for language packs, configuration, and future assistant plugins - -## Building - -### Prerequisites -- .NET 9 SDK -- Rust toolchain (stable) -- Tauri v1.6.2 CLI: `cargo install --version 1.6.2 tauri-cli` -- Tauri prerequisites (platform-specific dependencies) -- **Note:** Development on Linux is discouraged due to complex Tauri dependencies that vary by distribution - -### Build -```bash -cd app/Build -dotnet run build -``` -This builds the .NET app as a Tauri "sidecar" binary, which is required even for development. - - -### Running Tests -Currently, no automated test suite exists in the repository. - -## Architecture Details - -### Rust Runtime (`runtime/`) -**Entry point:** `runtime/src/main.rs` - -Key modules: -- `app_window.rs` - Tauri window management, updater integration -- `dotnet.rs` - Launches and manages the .NET sidecar process -- `runtime_api.rs` - Rocket-based HTTPS API for .NET ↔ Rust communication -- `certificate.rs` - Generates self-signed TLS certificates for secure IPC -- `secret.rs` - Secure secret storage using OS keyring (Keychain/Credential Manager) -- `clipboard.rs` - Cross-platform clipboard operations -- `file_data.rs` - File processing for RAG (extracts text from PDF, DOCX, XLSX, PPTX, etc.) -- `encryption.rs` - AES-256-CBC encryption for sensitive data -- `pandoc.rs` - Integration with Pandoc for document conversion -- `log.rs` - Logging infrastructure using `flexi_logger` - -### .NET App (`app/MindWork AI Studio/`) -**Entry point:** `app/MindWork AI Studio/Program.cs` - -Key structure: -- **Program.cs** - Bootstraps Blazor Server, configures Kestrel, initializes encryption and Rust service -- **Provider/** - LLM provider implementations (OpenAI, Anthropic, Google, Mistral, etc.) - - `BaseProvider.cs` - Abstract base for all providers with streaming support - - `IProvider.cs` - Provider interface defining capabilities and streaming methods -- **Chat/** - Chat functionality and message handling -- **Assistants/** - Pre-configured assistants (translation, summarization, coding, etc.) - - `AssistantBase.razor` - Base component for all assistants -- **Agents/** - contains all agents, e.g., for data source selection, context validation, etc. - - `AgentDataSourceSelection.cs` - Selects appropriate data sources for queries - - `AgentRetrievalContextValidation.cs` - Validates retrieved context relevance -- **Tools/PluginSystem/** - Lua-based plugin system -- **Tools/Services/** - Core background services (settings, message bus, data sources, updates) -- **Tools/Rust/** - .NET wrapper for Rust API calls -- **Settings/** - Application settings and data models -- **Components/** - Reusable Blazor components -- **Pages/** - Top-level page components - -### IPC Communication Flow -1. Rust runtime starts and generates TLS certificate -2. Rust starts internal HTTPS API on random port -3. Rust launches .NET sidecar, passing: API port, certificate fingerprint, API token, secret key -4. .NET reads environment variables and establishes secure HTTPS connection to Rust -5. .NET requests an app port from Rust, starts Blazor Server on that port -6. Rust opens Tauri webview pointing to localhost:app_port -7. Bi-directional communication: .NET ↔ Rust via HTTPS API - -### Configuration and Metadata -- `metadata.txt` - Build metadata (version, build time, component versions) read by both Rust and .NET -- `startup.env` - Development environment variables (generated by build script) -- `.NET project` reads metadata.txt at build time and injects as assembly attributes - -## Plugin System - -**Location:** `app/MindWork AI Studio/Plugins/` - -Plugins are written in Lua and provide: -- **Language plugins** - I18N translations (e.g., German language pack) -- **Configuration plugins** - Enterprise IT configurations for centrally managed providers, settings -- **Future:** Assistant plugins for custom assistants - -**Example configuration plugin:** `app/MindWork AI Studio/Plugins/configuration/plugin.lua` - -Plugins can configure: -- Self-hosted LLM providers -- Update behavior -- Preview features visibility -- Preselected profiles -- Chat templates -- etc. - -When adding configuration options, update: -- `app/MindWork AI Studio/Tools/PluginSystem/PluginConfiguration.cs`: In method `TryProcessConfiguration` register new options. -- `app/MindWork AI Studio/Tools/PluginSystem/PluginFactory.Loading.cs`: In method `LoadAll` check for leftover configuration. -- The corresponding data class in `app/MindWork AI Studio/Settings/DataModel/` to call `ManagedConfiguration.Register(...)`, when adding config options (in contrast to complex config. objects) -- `app/MindWork AI Studio/Tools/PluginSystem/PluginConfigurationObject.cs` for parsing logic of complex configuration objects. -- `app/MindWork AI Studio/Plugins/configuration/plugin.lua` to document the new configuration option. - -## RAG (Retrieval-Augmented Generation) - -RAG integration is currently in development (preview feature). Architecture: -- **External Retrieval Interface (ERI)** - Contract for integrating external data sources -- **Data Sources** - Local files and external data via ERI servers -- **Agents** - AI agents select data sources and validate retrieval quality -- **Embedding providers** - Support for various embedding models -- **Vector database** - Planned integration with Qdrant for vector storage -- **File processing** - Extracts text from PDF, DOCX, XLSX via Rust runtime - -## Enterprise IT Support - -AI Studio supports centralized configuration for enterprise environments: -- **Registry (Windows)** or **environment variables** (all platforms) specify configuration server URL and ID -- Configuration downloaded as ZIP containing Lua plugin -- Checks for updates every ~16 minutes via ETag -- Allows IT departments to pre-configure providers, settings, and chat templates - -**Documentation:** `documentation/Enterprise IT.md` - -## Provider Confidence System - -Multi-level confidence scheme allows users to control which providers see which data: -- Confidence levels: e.g. `NONE`, `LOW`, `MEDIUM`, `HIGH`, and some more granular levels -- Each assistant/feature can require a minimum confidence level -- Users assign confidence levels to providers based on trust - -**Implementation:** `app/MindWork AI Studio/Provider/Confidence.cs` - -## Dependencies and Frameworks - -**Rust:** -- Tauri 1.8 - Desktop application framework -- Rocket 0.5 - HTTPS API server -- tokio - Async runtime -- keyring - OS keyring integration -- pdfium-render - PDF text extraction -- calamine - Excel file parsing - -**.NET:** -- Blazor Server - UI framework -- MudBlazor 8.12 - Component library -- LuaCSharp - Lua scripting engine -- HtmlAgilityPack - HTML parsing -- ReverseMarkdown - HTML to Markdown conversion - -## Security - -- **Encryption:** AES-256-CBC with PBKDF2 key derivation for sensitive data -- **IPC:** TLS-secured communication with random ports and API tokens -- **Secrets:** OS keyring for persistent secret storage (API keys, etc.) -- **Sandboxing:** Tauri provides OS-level sandboxing - -## Release Process - -1. Create changelog file: `app/MindWork AI Studio/wwwroot/changelog/vX.Y.Z.md` -2. Commit changelog -3. Run from `app/Build`: `dotnet run release --action ` -4. Create PR with version bump and changes -5. After PR merge, maintainer creates git tag: `vX.Y.Z` -6. GitHub Actions builds release binaries for all platforms -7. Binaries uploaded to GitHub Releases - -## Important Development Notes - -- **File changes require Write/Edit tools** - Never use bash commands like `cat <` -- **Spaces in paths** - Always quote paths with spaces in bash commands -- **Debug environment** - Reads `startup.env` file with IPC credentials -- **Production environment** - Runtime launches .NET sidecar with environment variables -- **MudBlazor** - Component library requires DI setup in Program.cs -- **Encryption** - Initialized before Rust service is marked ready -- **Message Bus** - Singleton event bus for cross-component communication inside the .NET app +@AGENTS.md \ No newline at end of file