Jasmine AI Assistant

A cross-platform AI chatbot client built with C# (.NET 9) featuring clean architecture, fully pluginable responder system, and a modern terminal-based interface with support for multiple AI backends and unlimited custom chat responders.

graph TB
    User([User]) <--> CLI[Jasmine.CLI<br/>Terminal Interface]
    CLI <--> Core[Jasmine.Core<br/>AI Services & Logic]
    
    subgraph "Jasmine.CLI - Presentation Layer"
        UI[ChatUI<br/>Dynamic Terminal Interface]
        Bridge[ChatService<br/>UI Bridge]
        Program[Program.cs<br/>DI & Startup]
    end
    
    subgraph "Jasmine.Core - Business Layer"
        Registry[ResponderRegistry<br/>Dynamic Plugin Management]
        PAS[PluginableAIService<br/>Zero Hardcoded References]
        Config[Configuration<br/>& Persistence]
        Plugins[Plugin System<br/>HTTP & Time & Tools]
        Logging[Logging Infrastructure<br/>File & Rotation]
    end
    
    subgraph "Pluginable Responders"
        Echo[Echo Responder<br/>Testing & Development]
        Ollama[Ollama Responder<br/>Local AI Models]
        Azure[Azure OpenAI<br/>Cloud AI Models] 
        Human[Human Chat<br/>Operator Relay*]
        Quote[Random Quote<br/>Example Plugin]
        Custom[Custom Responders<br/>Unlimited Extensibility]
    end
    
    CLI --> UI
    CLI --> Bridge
    CLI --> Program
    
    Core --> Registry
    Core --> PAS
    Core --> Config
    Core --> Plugins
    Core --> Logging
    
    Registry -.-> Echo
    Registry -.-> Ollama
    Registry -.-> Azure
    Registry -.-> Human
    Registry -.-> Quote
    Registry -.-> Custom
    
    PAS --> Registry
    
    style User fill:#f9f,stroke:#333
    style CLI fill:#9cf,stroke:#333
    style Core fill:#fc9,stroke:#333
    style UI fill:#e1f5fe,stroke:#01579b
    style Bridge fill:#e1f5fe,stroke:#01579b
    style Program fill:#e1f5fe,stroke:#01579b
    style Registry fill:#e8f5e8,stroke:#2e7d32
    style PAS fill:#fff3e0,stroke:#e65100
    style Config fill:#fff3e0,stroke:#e65100
    style Plugins fill:#fff3e0,stroke:#e65100
    style Logging fill:#fff3e0,stroke:#e65100
    style Custom fill:#f3e5f5,stroke:#7b1fa2

Loading

What is Jasmine?

Jasmine is a modern, cross-platform AI chatbot client that provides a truly pluginable responder architecture for seamless integration of AI services, human operators, and unlimited custom chat responders. Built with .NET 9 and leveraging Microsoft Semantic Kernel, it offers clean separation between user interface and AI logic while supporting unlimited extensibility through its fully dynamic plugin system.

? Architecture Highlights

Fully Pluginable Design - No Hardcoded References ?

• Dynamic Discovery: Responders discovered at runtime with zero core code changes needed
• Zero Hardcoded References: Core service dynamically configures all responders without hardcoded IDs or types
• First-Available Selection: Intelligent default responder selection based on registration order
• Unified Interface: All responders implement IChatResponder for consistent behavior and configuration
• Runtime Registration: Add new responders by simply implementing interface and registering in DI

Clean Architecture Principles ?

• Separation of Concerns: UI layer handles only presentation, Core layer manages all AI logic and responder orchestration
• Dynamic Configuration: Responder configuration applied dynamically based on legacy mappings where applicable
• Event-Driven Updates: Reactive UI programming with clean event handling
• Interface-Based Design: Zero dependencies on concrete implementations

Project Structure

src/
??? Jasmine.CLI/           # Terminal UI (Presentation Layer)
?   ??? ChatUI.cs          # Dynamic Terminal.Gui interface
?   ??? ChatService.cs     # UI-Core bridge with responder support  
?   ??? Program.cs         # DI setup with responder registration
??? Jasmine.Core/          # AI Services & Business Logic
?   ??? Abstractions/      # Clean interfaces (IChatResponder, IAIService)
?   ??? Services/          # PluginableAIService & ResponderRegistry
?   ??? Responders/        # Built-in responder implementations
?   ?   ??? EchoResponder.cs          # Testing/development
?   ?   ??? OllamaResponder.cs        # Local AI models
?   ?   ??? AzureOpenAIResponder.cs   # Cloud AI models
?   ?   ??? HumanChatResponder.cs     # Human operator relay (placeholder)
?   ?   ??? RandomQuoteResponder.cs   # Example custom responder
?   ??? AI/               # AI configuration and integrations
?   ??? Utils/            # Token management, conversation memory
?   ??? Plugins/          # Semantic Kernel plugins
??? tests/
    ??? Jasmine.Tests/        # Comprehensive test suite with 240+ tests
        ??? Integration/      # Including CustomResponderIntegrationTests
        ??? Architecture/     # Clean architecture validation
        ??? Security/         # Data privacy and protection
        ??? Performance/      # Concurrency and load testing

?? Key Features

Revolutionary Pluginable Responder System ?

• True Plugin Architecture: Add new responders without any core code changes
• Dynamic Registration: Responders auto-discovered via dependency injection at startup
• Automatic UI Integration: New responders automatically appear in menus with generated configuration dialogs
• Zero Core Modifications: Proven by comprehensive integration tests with custom responders
• Configuration Flexibility: Each responder defines its own parameters, validation, and defaults
• Legacy Compatibility: Existing enum-based API still works during migration period

Built-in Responder Types

• AI Responders:
  • ?? Ollama (local models) with full Semantic Kernel integration and streaming
  • ?? Azure OpenAI (cloud models) with streaming support and enterprise features
• Utility Responders:
  • ?? Echo Service: Simple testing responder that echoes user input with configurable delays
  • ?? Random Quote: Example responder demonstrating custom implementation patterns
  • ?? Human Chat: Relay system for human operator communication (placeholder with WebSocket/SignalR ready architecture)
• Custom Responders: Unlimited extensibility - implement IChatResponder and register!

Advanced Terminal UI Features ???

• Dynamic Menu Generation: Menus automatically populated from registered responders at runtime
• Keyboard-Driven Interface: Full Terminal.Gui implementation with comprehensive shortcuts
• Real-time Streaming: Live display of AI responses as they're generated with progress indicators
• Animated Progress: Context-aware progress bars during responder processing
• Smart Text Selection: Multi-line selection with standard copy/paste keyboard shortcuts
• Auto-Generated Dialogs: Configuration dialogs dynamically created from responder parameters
• Adaptive Status Display: Real-time status showing current responder details and configuration state

Production-Ready Architecture ???

• Clean Abstractions: IChatResponder interface hides implementation complexity completely
• Registry Pattern: ResponderRegistry manages available responders with thread-safe operations
• Backward Compatibility: Legacy SupportedAIServices enum fully supported with bidirectional mapping
• Robust Configuration: JSON-based settings with automatic saving, loading, and corruption recovery
• Comprehensive Logging: File-based logging with rotation, error handling, and privacy protection
• Tools Integration: OpenAPI and MCP (Model Context Protocol) tools configuration support

Enterprise Developer Experience ?????

• Zero Learning Curve: Implement one interface, get full integration with all features
• No Breaking Changes: Add responders without modifying any existing application code
• Rich Configuration System: Support for parameters, validation, defaults, and UI generation
• Mock-Friendly Testing: Clean interfaces enable comprehensive unit and integration testing
• Modern C# Features: Leverages C# 13 features, .NET 9 capabilities, and latest async patterns

?? Quick Start

Prerequisites

• .NET 9 SDK (latest version)
• Terminal supporting Unicode characters (Windows Terminal, macOS Terminal, or Linux terminal)
• Ollama (optional, for local AI models)

Building and Running

# Clone the repository
git clone <repository-url>
cd Jasmine

# Restore dependencies
dotnet restore

# Build the solution
dotnet build

# Run the CLI application
dotnet run --project src/Jasmine.CLI

Configuration Setup

The application automatically creates a default ai_services_config.json configuration file on first run. To use AI services:

1. For Azure OpenAI: Update the generated config file with your endpoint and API key
2. For Ollama: Ensure Ollama is running locally (default: http://localhost:11434)
3. For importing settings: Copy your existing ai_services_config.json to the CLI project directory

The configuration file is excluded from version control for security. A template file is provided for reference.

?? Adding a Custom Responder (Zero Core Changes Required!)

Creating a new responder is incredibly simple and requires no modifications to core code:

1. Create the responder:

public class WeatherResponder : IChatResponder
{
    private readonly Dictionary<string, string> _parameters = new()
    {
        ["ApiKey"] = "",
        ["DefaultCity"] = "Seattle",
        ["Units"] = "metric"
    };

    public string Id => "weather";
    public string DisplayName => "Weather Service";
    public string Description => "Get weather information for any city";
    public IReadOnlyDictionary<string, string> Parameters => _parameters;
    public bool RequiresConfiguration => true;
    public bool SupportsStreaming => false;

    public Task ConfigureAsync(Dictionary<string, string> parameters) { /* ... */ }
    public Task<IChatMessage> RespondAsync(string userInput, IReadOnlyList<IChatMessage> history, Action<string>? onStreamingUpdate = null) { /* ... */ }
    public bool IsConfigured() => !string.IsNullOrEmpty(_parameters["ApiKey"]);
    public Dictionary<string, string> GetDefaultConfiguration() => new(_parameters);
}

2. Register in Program.cs:

// Add to DI container
services.AddSingleton<WeatherResponder>();

// Register with the responder registry
registry.Register(serviceProvider.GetRequiredService<WeatherResponder>());

3. That's it! ? Your responder:
   • Automatically appears in the UI menu
   • Gets a dynamically generated configuration dialog
   • Works with all existing features (streaming, events, error handling)
   • Supports all UI operations (switching, configuration, status display)

?? Project Documentation

Detailed Documentation

• Core Project README - AI services, responders, and business logic architecture
• CLI Project README - Terminal interface and dynamic UI architecture
• Test Project README - Testing strategy, patterns, and coverage details

Architecture Validation

Our architecture is validated by comprehensive tests including:

• Custom Responder Integration Tests: Prove that external responders work seamlessly
• Architecture Boundary Tests: Enforce clean separation and zero forbidden dependencies
• Legacy Compatibility Tests: Ensure backward compatibility during migration
• Performance Tests: Validate concurrent responder operations and registry scalability

?? Responder Types & Extensibility

AI-Powered Responders

• Ollama: Local AI models with configurable endpoints, streaming, and model switching
• Azure OpenAI: Enterprise-grade GPT models with streaming, token management, and tools integration

Utility & Example Responders

• Echo: Development and testing responder with configurable prefix and delays
• Random Quote: Demonstrates simple custom responder implementation patterns
• Human Chat: Architecture for human operator integration (WebSocket/SignalR ready)

Unlimited Extensibility Examples

The pluginable architecture enables any type of responder:

• ??? Weather Services: API-based weather information with geolocation
• ??? Database Responders: Query databases and return formatted results with SQL support
• ?? External APIs: Integration with any REST, GraphQL, or WebSocket service
• ?? Custom AI Models: Integration with any AI service, local models, or custom inference
• ?? Business Logic: Domain-specific responders with complex workflow support
• ?? Interactive Services: Games, quizzes, tutorials, or interactive experiences

?? Testing

Run the comprehensive test suite:

# Run all tests
dotnet test

# Run with detailed output and coverage
dotnet test --verbosity normal --collect:"XPlat Code Coverage"

# Run specific test categories  
dotnet test --filter "Category=Integration"
dotnet test --filter "Category=Architecture" 
dotnet test --filter "Priority=Critical"

The test project includes 240+ tests across multiple categories:

• Unit Tests: Individual component testing with mocked dependencies (60+ tests)
• Integration Tests: Cross-layer interaction validation including custom responders (50+ tests)
• Architecture Tests: Clean architecture boundary enforcement and dependency validation (15+ tests)
• Security Tests: Data privacy, API key protection, and sensitive information handling (15+ tests)
• Streaming Tests: Real-time response validation and edge cases (25+ tests)
• Error Handling Tests: Graceful failure scenarios and resilience testing (20+ tests)
• Performance Tests: Concurrency, load testing, and registry scalability (15+ tests)
• Compatibility Tests: Legacy system integration and backward compatibility (20+ tests)
• Tools Integration Tests: OpenAPI and MCP tools functionality (20+ tests)

Key Test Validations ?

• Custom Responder Integration: Proves external responders work without core changes
• Zero Hardcoded Dependencies: Validates dynamic responder discovery and configuration
• Thread Safety: Concurrent responder operations and registry modifications
• Security: API keys never appear in logs, error messages, or debug output
• Legacy Compatibility: Enum-based API continues working during migration

?? Contributing

Development Guidelines

1. Maintain Clean Architecture: Keep presentation and business logic completely separated
2. Use Pluginable Patterns: All new responder types should implement IChatResponder interface only
3. Zero Breaking Changes: New features must not break existing responders or APIs
4. Comprehensive Testing: Add tests for new responders, edge cases, and integration scenarios
5. Documentation First: Update relevant README files and add XML documentation for new public APIs
6. Security Conscious: Never log sensitive data, always validate responder parameters
7. Performance Aware: Consider concurrent usage, memory usage, and responder registry scalability

Adding New Responders

The pluginable architecture makes it incredibly easy to contribute new responder types:

1. Create your responder class implementing IChatResponder
2. Add comprehensive tests in the test project with integration validation
3. Register in Program.cs for dependency injection and registry registration
4. Update documentation with examples and usage patterns
5. Submit PR with your responder - no core code changes required!

??? Future Roadmap

Short-term Enhancements (Next 3 months)

• Complete Human Chat Implementation: Full WebSocket and SignalR integration for real-time human operator communication
• Additional AI Providers: OpenAI, Claude, Google Gemini, and Cohere responders with streaming support
• Enhanced Tools Integration: Expand OpenAPI and MCP tools with authentication and complex workflow support
• Advanced Configuration: Environment-specific responder configurations and deployment profiles

Medium-term Goals (6 months)

• Multi-modal Responders: Image processing, document analysis, and file upload responders
• Agent Orchestration: Multi-responder workflows, handoffs, and complex conversation routing
• Voice Interface: Speech-to-text and text-to-speech responder integration with real-time processing
• Web Interface: Browser-based alternative UI with full responder ecosystem support
• Database Integration: Built-in SQL and NoSQL database responders with query builders

Long-term Vision (1 year+)

• Distributed Responders: Network-based responder deployment, load balancing, and horizontal scaling
• Enterprise Features: Authentication, audit trails, responder permissions, and usage quotas
• Mobile Support: .NET MAUI applications with full responder ecosystem and offline support
• Cloud Deployment: Container-based responder hosting, management, and auto-scaling
• Marketplace: Community responder marketplace with ratings, reviews, and easy installation

?? License

MIT License - Feel free to use this pluginable architecture in your own projects!

?? Project Achievements

• ? Zero Hardcoded References: Successfully removed all hardcoded responder dependencies
• ? True Plugin Architecture: Proven by comprehensive integration tests with external responders
• ? Clean Architecture: Validated by architectural boundary tests and dependency analysis
• ? Backward Compatibility: Legacy APIs continue working during migration period
• ? Production Ready: 240+ tests covering all scenarios including security and performance
• ? Developer Friendly: Simple interface implementation provides full feature integration