# DeepLake

**Repository Path**: mingjue/deep-lake

## Basic Information

- **Project Name**: DeepLake
- **Description**: DeepLake 是一个基于 C# 开发的 AI 智能体框架，采用动态可调用路由设计，专门用于构建智能多智能体系统。该框架支持基于会话的编排管理，能够智能地将用户请求路由到合适的执行体进行处理。

  
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-03-06
- **Last Updated**: 2026-03-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DeepLake - AI Agent Framework

[![.NET](https://img.shields.io/badge/.NET-9.0-purple.svg)](https://dotnet.microsoft.com/download/dotnet/9.0)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

DeepLake is a powerful C# AI agent framework with dynamic executable routing, designed for building intelligent multi-agent systems with session-based orchestration.

## 🚀 Quick Start

### Prerequisites
- **.NET 9.0 SDK**
- **DeepSeek API Key** (or other supported AI provider)
- **Python 3.8+** (optional, for MCP server integration)

### Environment Variables

```bash
# DeepSeek API Key for AI model access
export DL_DEEPSEEK_API="your-deepseek-api-key"

# Root path of the DeepLake solution
export DL_ROOT_PATH="/path/to/DeepLake"
```

**Windows (PowerShell):**
```powershell
$env:DL_DEEPSEEK_API = "your-deepseek-api-key"
$env:DL_ROOT_PATH = "C:\path\to\DeepLake"
```

### Installation & Running

```bash
# Clone the repository
git clone <repository-url>
cd DeepLake

# Build the solution
dotnet build

# Run the CLI application
dotnet run --project DeepLakeCli
```

## ✨ Key Features

### 🤖 Intelligent Agent System
- **Executable Abstraction**: All invokable objects inherit from `Executable` base class
- **Multiple Types**: Support for agents, groups, workflows, custom executables, and builtin executables
- **Direct Invocation**: Users invoke executables directly by name
- **Context Cloning**: Isolated execution with cloned context for safety

### 🔧 Plugin System
- **Function Plugins**: C# methods with `[DLPluginFunction]` attribute automatically become AI tools
- **MCP Plugins**: Model Context Protocol servers (SSE and stdio transports)
- **Auto-Discovery**: Plugins automatically discovered and integrated
- **Vector Search**: Semantic plugin discovery when enabled
- **JSON Schema**: Automatic generation of AI tool-compliant schemas

### 🌐 Multi-Provider Support
- **DeepSeek Integration**: Native support for DeepSeek models
- **OpenAI Compatibility**: Support for OpenAI-compatible APIs
- **Provider Abstraction**: Easy switching between AI providers
- **Dual Models**: Chat model + Reasoner model support

### 📊 Monitoring & Observability
- **Execution Monitoring**: Real-time monitoring with callbacks
- **Session Management**: Stateful sessions with chat history preservation
- **Source Generator**: Roslyn-based automatic logging with `[DLLogged]` attribute

### 🗄️ Vector Store Support
- **Qdrant Integration**: Vector database for semantic search
- **In-Memory Store**: Built-in store for development

## 📁 Project Structure

```
DeepLake/
├── DeepLakeCoreLibrary/          # Core framework (managers, components, executables)
├── DeepLakeGenerator/            # Roslyn source generator for logging
├── DeepLakeCli/                  # Command-line interface
├── DeepLakeWebServer/            # ASP.NET Core Web API (http://127.0.0.1:5030)
├── DeepLakeCoreLibrary.Tests/    # xUnit test suite
├── DeepLakeCli.Tests/            # API validation tests
├── SituationPuzzle/              # Example application
├── DeepLakeMCPSSEServerCSharp/   # C# MCP server (SSE transport)
├── DeepLakeMCPStdioServerCSharp/ # C# MCP server (stdio transport)
├── DeepLakeMCPServerPython/      # Python MCP server (testing)
└── DeepLakeLink/app/             # Electron + Vue.js editor (being rebuilt)
```

## 🏗️ Architecture

### Core Components

**Managers** (all implement `IManager` interface):
- **DLCoreManager**: AI provider connections and configuration
- **DLExecutableManager**: Central registry and factory for all executables
- **DLPluginManager**: Plugin discovery and tool schema generation
- **DLMonitorManager**: Execution monitoring
- **DLSessionManager**: Session management with context cloning

**Executable Types**:
- **DLAgent**: Individual AI agent with system prompt, core assignment, and plugin discovery
- **DLGroup**: Multi-executable coordination (Sequential, Parallel, AutoSelect modes)
- **DLWorkflow**: Multi-step pipelines with conditional branching
- **Custom Executables**: User-defined via `[DLCustomExecutable]` attribute
- **Builtin Executables**: System-provided (UserInput, Todo, CleanContext)

**Core Components**:
- **DLContext**: Execution context with cloned chat history
- **DLCore**: AI provider communication with automatic tool calling loop
- **DLChatHistory**: Immutable history with clone support

### Key Data Flow

```
User Request → DeepLakeEnv.Talk(sessionId, executableName)
    ↓
SessionManager.Talk() → DLExecutableManager.Get(executableName)
    ↓
executable.Execute(context) with CLONED context
    ↓
Agent injects system prompt → Core.SendMessage() with plugins
    ↓
AI response + tool calling loop → Result returned
```

**Critical Design**: Context is cloned before each executable execution, ensuring side-effect isolation while preserving session history.

## ⚙️ Configuration

### Two-Stage Configuration Architecture

**Stage 1: Main Configuration (AIConfig.toml)**
```toml
CoreConfigPaths = ["CoreConfig.toml"]
ExecutableConfigPaths = ["AgentConfig.toml", "WorkflowConfig.toml", "CustomExecutableConfig.toml"]
PluginConfigPaths = ["PluginConfig.toml"]
MonitorConfigPaths = ["MonitorConfig.toml"]
# DefaultExecutable = "WelcomeAgent"  # Optional
```

**Stage 2: Component-Specific TOML Files**

### Configuration Class Hierarchy
```
ExecutableInfo (base)
├─ NamedExecutableInfo (name, description, order)
│   ├─ UserAgentInfo (CoreName, Plugins[], Prefer*)
│   ├─ UserGroupInfo (Executables[], GroupType, SummarizeDescription)
│   └─ UserWorkflowInfo (EntryStep, WorkflowStepInfos[])
├─ BuiltinExecutableInfo (BuiltinType)
│   └─ BuiltinUserInputExecutableInfo (Prefix)
└─ UserCustomExecutableInfo (AssemblyPathOrName, ExecutableClassName[])
```

### Example Configuration

**CoreConfig.toml**:
```toml
DefaultCore = "Deepseek"

[[CoreInfoList]]
CoreName = "Deepseek"
APIKeyName = "DL_DEEPSEEK_API"
EndPoint = "https://api.deepseek.com"
ModelChatId = "deepseek-chat"
ModelReasonerId = "deepseek-reasoner"
```

**AgentConfig.toml**:
```toml
[[ExecutableInfos]]
ExecutableType = "Agent"
ExecutableName = "WelcomeAgent"
ExecutableDescription = "Say welcome to user"
CoreName = "Deepseek"
PreferReasoner = false
PreferStream = false
PreferAutoPlugins = false
Order = 1
```

**PluginConfig.toml**:
```toml
# Assembly plugin
[[PluginInfos]]
Type = "Function"
AssemblyPaths = ["path/to/plugin.dll"]

# MCP SSE server
[[PluginInfos]]
Type = "MCP"
Transport = "SSE"
Endpoint = "http://localhost:8080/sse"

# MCP stdio server
[[PluginInfos]]
Type = "MCP"
Transport = "Stdio"
Command = "python"
WorkDir = "path/to/server"
Arguments = ["mcp_server.py"]
```

### ConfigLoader Utility

**Location**: `DeepLakeCoreLibrary/Misc/ConfigLoader.cs`

```csharp
// Load single config
var config = ConfigLoader.LoadConfig<UserAIConfig>(path, basePath);

// Load arrays from multiple files
var executableInfos = ConfigLoader.LoadConfigItems<UserExecutableConfig, ExecutableInfo>(
    configPaths!,
    basePath,
    config => config.ExecutableInfos
);
```

## 🛠️ Development

### Building and Testing

```bash
# Build entire solution
dotnet build

# Run all tests
dotnet test

# Run specific test project (use DeepLakeCoreLibrary.Tests, NOT DeepLakeLibrary.Tests)
dotnet test --project DeepLakeCoreLibrary.Tests

# Run specific test class
dotnet test --filter "FullyQualifiedName~DeepLakeAgentTests"

# Build with detailed output (for source generator debugging)
dotnet build DeepLakeCoreLibrary/DeepLakeCoreLibrary.csproj -v detailed
```

### Running Applications

```bash
# CLI application
dotnet run --project DeepLakeCli

# Web API server (http://127.0.0.1:5030)
cd DeepLakeWebServer
dotnet run

# Electron + Vue.js editor (being rebuilt)
cd DeepLakeLink/app
npm install
npm run dev

# C# MCP servers
cd DeepLakeMCPSSEServerCSharp
dotnet run

cd DeepLakeMCPStdioServerCSharp
dotnet run
```

### Creating Plugins

```csharp
public class MyPlugin
{
    [DLPluginFunction("get_user_info", "Get user information")]
    public string GetUserInfo(
        [DLPluginParam("user_id", "User ID")] string userId)
    {
        return $"Information for user {userId}";
    }
}
```

## 📚 Documentation

- **[CLAUDE.md](CLAUDE.md)** - Comprehensive architecture and development guide for Claude Code
- **[TODOs.md](TODOs.md)** - Development roadmap and pending tasks

## 🎯 Example Applications

### SituationPuzzle
A complete example demonstrating:
- Multi-agent collaboration
- Workflow orchestration
- Plugin integration
- Real-time monitoring

### DeepLakeWebServer
REST API server providing HTTP access to DeepLake core functionality. Features:
- Swagger/OpenAPI documentation at `http://127.0.0.1:5030/swagger`
- Health check endpoint
- Session management
- CORS support for Electron integration

## 🔍 Architecture Insights

### Context Cloning Pattern
- **Isolation**: Context cloned before each executable execution
- **Session History**: Accumulates in session, executables work with copies
- **Trade-off**: Safety over performance (cloning can be expensive for long conversations)

### Workflow Execution Flow
- **Separate Context**: Workflows maintain `flowContext` for step execution
- **History Accumulation**: Each step result added to flow context
- **Conditional Branching**: AI evaluates conditions to determine next step
- **Default Tags**: `"default"` condition always executes

### AutoSelect Group Pattern
- **Todo Scheduling**: AI schedules executables as todo items based on context
- **Failure Recovery**: AI can reschedule failed tasks
- **Dynamic Execution**: Not all tasks need to complete - AI decides based on results

## 🧪 Testing

Sample configurations are located in:
- `DeepLakeCoreLibrary.Tests/SampleConfig/` - Test configurations for various components
- `SituationPuzzle/Configs/` - Example application configurations

Test categories:
- Agent tests: `DeepLakeAPI_Agent*`
- MCP tests: `DeepLakeAPI_MCP_*`
- Plugin tests: `PluginManager_*`
- Workflow tests: `DeepLakeAPI_Workflow`
- Group tests: `DeepLakeAPI_AgentGroup_*`
- Builtin executable tests: `DeepLakeAPI_BuiltinExecutable_*`

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🤝 Contributing

We welcome contributions! Please:
1. Check the [CLAUDE.md](CLAUDE.md) for development guidelines
2. Review sample configurations for examples
3. Ensure tests pass before submitting PRs

## 📞 Support

- Check [CLAUDE.md](CLAUDE.md) for comprehensive documentation
- Review sample configurations in `SituationPuzzle/Configs/`
- Examine test cases for implementation examples

---

**DeepLake** - Building the future of intelligent agent systems, one conversation at a time.