From 195355f4126cd49172739ea525ff84bb11f4381c Mon Sep 17 00:00:00 2001 From: Piotr Stachaczynski Date: Mon, 25 Aug 2025 19:57:35 +0200 Subject: [PATCH 1/2] feat: docs for knowledge base --- src/assets/docs/docs-index.json | 20 ++ .../docs/examples/agent-knowledge-overview.md | 131 ++++++++ .../examples/example-agent-knowledge-file.md | 170 ++++++++++ .../examples/example-agent-knowledge-mcp.md | 311 ++++++++++++++++++ .../examples/example-agent-knowledge-web.md | 210 ++++++++++++ 5 files changed, 842 insertions(+) create mode 100644 src/assets/docs/examples/agent-knowledge-overview.md create mode 100644 src/assets/docs/examples/example-agent-knowledge-file.md create mode 100644 src/assets/docs/examples/example-agent-knowledge-mcp.md create mode 100644 src/assets/docs/examples/example-agent-knowledge-web.md diff --git a/src/assets/docs/docs-index.json b/src/assets/docs/docs-index.json index 286a9e2..9b44711 100644 --- a/src/assets/docs/docs-index.json +++ b/src/assets/docs/docs-index.json @@ -101,6 +101,26 @@ "path": "examples/example-agent-talking" } ]}, + { + "title": "Knowledge base", + "children": [ + { + "title": "Overview", + "path": "examples/agent-knowledge-overview" + }, + { + "title": "With File source", + "path": "examples/example-agent-knowledge-file" + }, + { + "title": "With Web source", + "path": "examples/example-agent-knowledge-web" + }, + { + "title": "With Mcp source", + "path": "examples/example-agent-knowledge-mcp" + } + ]}, { "title": "Flow", "children": [ diff --git a/src/assets/docs/examples/agent-knowledge-overview.md b/src/assets/docs/examples/agent-knowledge-overview.md new file mode 100644 index 0000000..c0c1695 --- /dev/null +++ b/src/assets/docs/examples/agent-knowledge-overview.md @@ -0,0 +1,131 @@ +# Knowledge Base Feature Overview + +## Introduction + +The Knowledge Base feature in MaIN.NET 0.4.1 enables agents to access and utilize external information sources intelligently. This feature allows agents to provide accurate, context-aware responses by leveraging persisted knowledge from files, web sources, and MCP (Model Context Protocol) servers. + +## How Knowledge Base Works + +### Core Concept +The knowledge base system creates an `index.json` file that contains a set of sources with assigned tags. When an agent receives a query, it can: + +1. **Evaluate Query Relevance** - Determine if external knowledge is needed +2. **Tag Matching** - Find relevant knowledge sources based on tags +3. **Source Selection** - Choose appropriate knowledge items (1-4 tags maximum) +4. **Context Integration** - Use selected knowledge to enhance responses + +### Knowledge Storage Structure +Knowledge is persisted as an index with the following structure: +- **Name**: Identifier for the knowledge item +- **Type**: File, URL, Text, or MCP +- **Value**: Actual content or reference +- **Tags**: Array of searchable keywords + +## Knowledge Decision Process + +The `AnswerCommandHandler` implements intelligent knowledge usage through three modes: + +### KnowledgeUsage.UseMemory +Uses traditional chat memory without external knowledge sources. + +### KnowledgeUsage.UseKnowledge +Intelligently decides whether to use knowledge based on query analysis: +- Evaluates if the question requires external knowledge +- Uses knowledge unless certain the question needs only basic facts (like "What is 2+2?" or "Capital of France?") +- When in doubt, defaults to using external knowledge + +### KnowledgeUsage.AlwaysUseKnowledge +Always processes queries through the knowledge base system. + +## Knowledge Types Supported + +### File Sources (KnowledgeItemType.File) +- Local files (Markdown, text, etc.) +- Added to `ChatMemoryOptions.FilesData` +- Example: Company documentation, policies, manuals + +### Web Sources (KnowledgeItemType.Url) +- Web pages and online resources +- Added to `ChatMemoryOptions.WebUrls` +- Example: Online tutorials, documentation sites + +### Text Sources (KnowledgeItemType.Text) +- Direct text content +- Added to `ChatMemoryOptions.TextData` +- Example: Structured data, snippets + +### MCP Sources (KnowledgeItemType.Mcp) +- Model Context Protocol servers +- Handled through `mcpService.Prompt()` +- Example: GitHub integration, filesystem access, web search + +## Tag-Based Retrieval System + +The system uses JSON-serialized tag matching: + +1. **Index Creation**: Available knowledge sources with their tags +2. **Query Analysis**: LLM determines relevant tags for the user query +3. **Source Filtering**: Finds knowledge items where tags intersect with query tags or match item names +4. **Context Building**: Selected sources are integrated into the chat context + +## KnowledgeBuilder API + +The `KnowledgeBuilder` provides a fluent API for constructing knowledge bases: + +### File Sources +```csharp +KnowledgeBuilder.Instance + .AddFile("filename", "./path/to/file.md", tags: ["tag1", "tag2"]) +``` + +### Web Sources +```csharp +KnowledgeBuilder.Instance + .AddUrl("source_name", "https://example.com", tags: ["web", "tutorial"]) +``` + +### MCP Sources +```csharp +KnowledgeBuilder.Instance + .AddMcp(new Mcp + { + Name = "ServerName", + Command = "npx", + Arguments = ["server-package"], + Backend = BackendType.OpenAi, + Model = "gpt-4" + }, ["mcp", "external"]) +``` + +## Integration with Agents + +Knowledge bases integrate seamlessly with MaIN.NET agents: + +```csharp +var context = await AIHub.Agent() + .WithModel("your-model") + .WithKnowledge(KnowledgeBuilder.Instance + .AddFile(...) + .AddUrl(...) + .AddMcp(...)) + .WithSteps(StepBuilder.Instance + .AnswerUseKnowledge() + .Build()) + .CreateAsync(); +``` + +## Performance and Limitations + +- **Tag Limit**: Returns 1-4 tags maximum per query to maintain focus +- **MCP Limitation**: Cannot combine responses from multiple MCP servers in one request +- **Grammar Control**: Uses structured grammars for decision-making and tag selection +- **Memory Integration**: Knowledge sources are added to chat memory for processing + +## Notification System + +The system provides progress notifications showing: +- Selected knowledge items (Name|Type format) +- Model being used for processing +- Real-time updates during knowledge processing + +This knowledge base implementation provides a lightweight yet powerful way to enhance agent capabilities with external information sources while maintaining performance and accuracy. \ No newline at end of file diff --git a/src/assets/docs/examples/example-agent-knowledge-file.md b/src/assets/docs/examples/example-agent-knowledge-file.md new file mode 100644 index 0000000..ed7fd35 --- /dev/null +++ b/src/assets/docs/examples/example-agent-knowledge-file.md @@ -0,0 +1,170 @@ +# Agent with Knowledge File Example + +## Overview + +This example demonstrates how to create an agent that can access and query local file-based knowledge sources. The agent acts as a company assistant for "TechVibe Solutions," helping employees find answers about company information stored in multiple markdown files. + +## Code Example + +```csharp +using Examples.Utils; +using MaIN.Core.Hub; +using MaIN.Core.Hub.Utils; +using MaIN.Domain.Entities.Agents.AgentSource; + +namespace Examples.Agents; + +public class AgentWithKnowledgeFileExample : IExample +{ + public async Task Start() + { + Console.WriteLine("Agent with knowledge base example"); + AIHub.Extensions.DisableLLamaLogs(); + + var context = await AIHub.Agent() + .WithModel("gemma3:4b") + .WithInitialPrompt(""" + You are a helpful assistant that answers questions about a company. Try to + help employees find answers to their questions. Company you work for is TechVibe Solutions. + """) + .WithKnowledge(KnowledgeBuilder.Instance + .AddFile("people.md", "./Files/Knowledge/people.md", + tags: ["workers", "employees", "company"]) + .AddFile("organization.md", "./Files/Knowledge/organization.md", + tags:["company structure", "company policy", "company culture", "company overview"]) + .AddFile("events.md", "./Files/Knowledge/events.md", + tags: ["company events", "company calendar", "company agenda"]) + .AddFile("office_layout.md", "./Files/Knowledge/office_layout.md", + tags: ["company layout", "company facilities", "company environment", "office items", "supplies"])) + .WithSteps(StepBuilder.Instance + .AnswerUseKnowledge() + .Build()) + .CreateAsync(); + + var result = await context + .ProcessAsync("Hey! Where I can find some printer paper?"); + Console.WriteLine(result.Message.Content); + } +} +``` + +## Key Components + +### Model Configuration +- **Model**: `gemma3:4b` - A lightweight local model suitable for company assistance tasks +- **Initial Prompt**: Establishes the agent's role as a TechVibe Solutions company assistant + +### Knowledge Sources + +The example demonstrates four different file-based knowledge sources: + +#### 1. People Directory (`people.md`) +- **Purpose**: Employee information and contact details +- **Tags**: `["workers", "employees", "company"]` +- **Use Cases**: Finding colleagues, contact information, organizational structure + +#### 2. Organization Information (`organization.md`) +- **Purpose**: Company structure, policies, and culture documentation +- **Tags**: `["company structure", "company policy", "company culture", "company overview"]` +- **Use Cases**: Understanding company hierarchy, policies, cultural guidelines + +#### 3. Events Calendar (`events.md`) +- **Purpose**: Company events and calendar information +- **Tags**: `["company events", "company calendar", "company agenda"]` +- **Use Cases**: Upcoming meetings, company events, important dates + +#### 4. Office Layout (`office_layout.md`) +- **Purpose**: Physical office information, facilities, and supplies +- **Tags**: `["company layout", "company facilities", "company environment", "office items", "supplies"]` +- **Use Cases**: Finding office resources, navigation, facility information + +### Step Configuration +- Uses `AnswerUseKnowledge()` which intelligently determines when to access knowledge sources +- The system evaluates each query to decide if external knowledge is needed + +## Example Query Flow + +When a user asks: **"Hey! Where I can find some printer paper?"** + +1. **Query Analysis**: The system analyzes the question and identifies relevant tags +2. **Knowledge Matching**: Matches tags like "office items" and "supplies" to `office_layout.md` +3. **Content Retrieval**: Loads the relevant file content into memory +4. **Response Generation**: Uses the file content to provide specific location information + +## File Structure Requirements + +The example expects the following file structure: +``` +./Files/Knowledge/ +├── people.md +├── organization.md +├── events.md +└── office_layout.md +``` + +## Use Cases + +This pattern is ideal for: + +### Corporate Knowledge Bases +- Employee handbooks +- Policy documentation +- Organizational charts +- Office information + +### Documentation Systems +- Technical documentation +- User manuals +- FAQ collections +- Standard operating procedures + +### Educational Content +- Course materials +- Reference guides +- Learning resources +- Curriculum information + +## Best Practices + +### Tag Selection +- Use specific, descriptive tags that match how users might ask questions +- Include both broad categories (`"company"`) and specific terms (`"supplies"`) +- Consider synonyms and alternative ways users might phrase queries + +### File Organization +- Keep files focused on specific topics +- Use clear, descriptive filenames +- Maintain consistent formatting within files +- Regular updates to keep information current + +### Model Selection +- Local models like `gemma3:4b` work well for company-specific knowledge +- Consider model size vs. response quality based on your needs +- Test with your specific knowledge content to ensure good performance + +## Integration Tips + +### Error Handling +Consider adding error handling for missing files: +```csharp +// Verify files exist before creating agent +var filePaths = new[] { + "./Files/Knowledge/people.md", + "./Files/Knowledge/organization.md", + // ... other files +}; + +foreach (var path in filePaths) +{ + if (!File.Exists(path)) + throw new FileNotFoundException($"Knowledge file not found: {path}"); +} +``` + +### Dynamic Content +For frequently updated content, consider: +- Implementing file watchers to detect changes +- Periodic knowledge base rebuilding +- Version control integration for content management + +This example provides a solid foundation for building file-based knowledge systems that can scale to handle extensive corporate or domain-specific information repositories. \ No newline at end of file diff --git a/src/assets/docs/examples/example-agent-knowledge-mcp.md b/src/assets/docs/examples/example-agent-knowledge-mcp.md new file mode 100644 index 0000000..677469f --- /dev/null +++ b/src/assets/docs/examples/example-agent-knowledge-mcp.md @@ -0,0 +1,311 @@ +# Agent with Knowledge MCP Example + +## Overview + +This example demonstrates the most advanced knowledge integration using Model Context Protocol (MCP) servers. The agent can access multiple external services including web search, filesystem operations, and GitHub integration, each powered by different AI models and backends for optimal performance. + +## Code Example + +```csharp +using MaIN.Core.Hub; +using MaIN.Core.Hub.Utils; +using MaIN.Domain.Configuration; + +namespace Examples.Mcp; + +public class AgentWithKnowledgeMcpExample : IExample +{ + public async Task Start() + { + //Note: to run this example that uses 3 different AI providers. You have to assign api keys for those providers in ENV variables or in appsettings + //Note: to run this example, you should do 'gh auth login' to give octocode mcp server access to github CLI + Console.WriteLine("Agent with knowledge base example MCP sources"); + AIHub.Extensions.DisableLLamaLogs(); + + var context = await AIHub.Agent() + .WithBackend(BackendType.OpenAi) + .WithModel("gpt-4o-mini") + .WithKnowledge(KnowledgeBuilder.Instance + .AddMcp(new MaIN.Domain.Entities.Mcp + { + Name = "ExaDeepSearch", + Arguments = ["-y", "exa-mcp-server"], + Command = "npx", + EnvironmentVariables = {{"EXA_API_KEY","ef8d90d8-90c2-4985-a1e0-db28fa55feb5"}}, + Backend = BackendType.Gemini, + Model = "gemini-2.0-flash" + }, ["search", "browser", "web access", "research"]) + .AddMcp(new MaIN.Domain.Entities.Mcp + { + Name = "FileSystem", + Command = "npx", + Arguments = ["-y", + "@modelcontextprotocol/server-filesystem", + "C:\\Users\\stach\\Desktop", //Align paths to fit your system + "C:\\WiseDev"], //Align paths to fit your system + Backend = BackendType.GroqCloud, + Model = "openai/gpt-oss-20b" + }, ["filesystem", "file operations", "read write", "disk search"]) + .AddMcp(new MaIN.Domain.Entities.Mcp + { + Name = "Octocode", + Command = "npx", + Arguments = ["octocode-mcp"], + Backend = BackendType.OpenAi, + Model = "gpt-5-nano" + }, ["code", "github", "repository", "packages", "npm"])) + .WithSteps(StepBuilder.Instance + .AnswerUseKnowledge() + .Build()) + .CreateAsync(); + + Console.WriteLine("Agent ready! Type 'exit' to quit.\n"); + + while (true) + { + Console.ForegroundColor = ConsoleColor.Blue; + Console.Write("You: "); + Console.ResetColor(); + + var input = Console.ReadLine(); + + if (input?.ToLower() == "exit") break; + if (string.IsNullOrWhiteSpace(input)) continue; + + Console.ForegroundColor = ConsoleColor.Green; + Console.Write("Agent: "); + + var result = await context.ProcessAsync(input); + Console.WriteLine(result.Message.Content); + Console.ResetColor(); + Console.WriteLine(); + } + } +} +``` + +## Key Components + +### Multi-Backend Architecture +This example showcases using different AI backends for different MCP servers: +- **Primary Agent**: OpenAI GPT-4o-mini for general conversation +- **Web Search**: Gemini 2.0 Flash for search operations +- **Filesystem**: GroqCloud for file operations +- **GitHub**: OpenAI GPT-5-nano for code-related tasks + +### Prerequisites + +#### API Keys Required +You must set up API keys for three different AI providers: +- **OpenAI**: For primary agent and GitHub operations +- **Google Gemini**: For web search functionality +- **GroqCloud**: For filesystem operations +- **Exa API**: For enhanced web search capabilities + +#### GitHub CLI Setup +```bash +gh auth login +``` +This gives the Octocode MCP server access to GitHub CLI for repository operations. + +## MCP Server Configurations + +### 1. ExaDeepSearch MCP Server +```csharp +.AddMcp(new MaIN.Domain.Entities.Mcp +{ + Name = "ExaDeepSearch", + Arguments = ["-y", "exa-mcp-server"], + Command = "npx", + EnvironmentVariables = {{"EXA_API_KEY","ef8d90d8-90c2-4985-a1e0-db28fa55feb5"}}, + Backend = BackendType.Gemini, + Model = "gemini-2.0-flash" +}, ["search", "browser", "web access", "research"]) +``` + +**Purpose**: Advanced web search and research capabilities +- **Command**: Runs via npm package manager +- **Environment**: Requires Exa API key for enhanced search +- **Backend**: Uses Gemini 2.0 Flash for optimal search result processing +- **Tags**: Triggers on search-related queries + +### 2. FileSystem MCP Server +```csharp +.AddMcp(new MaIN.Domain.Entities.Mcp +{ + Name = "FileSystem", + Command = "npx", + Arguments = ["-y", + "@modelcontextprotocol/server-filesystem", + "C:\\Users\\stach\\Desktop", //Align paths to fit your system + "C:\\WiseDev"], //Align paths to fit your system + Backend = BackendType.GroqCloud, + Model = "openai/gpt-oss-20b" +}, ["filesystem", "file operations", "read write", "disk search"]) +``` + +**Purpose**: Local filesystem access and operations +- **Scope**: Limited to specified directories for security +- **Backend**: GroqCloud for efficient file processing +- **Path Configuration**: Customizable to your system paths +- **Tags**: Activates for file-related operations + +### 3. Octocode MCP Server +```csharp +.AddMcp(new MaIN.Domain.Entities.Mcp +{ + Name = "Octocode", + Command = "npx", + Arguments = ["octocode-mcp"], + Backend = BackendType.OpenAi, + Model = "gpt-5-nano" +}, ["code", "github", "repository", "packages", "npm"]) +``` + +**Purpose**: GitHub repository and package management +- **Integration**: Requires GitHub CLI authentication +- **Backend**: OpenAI for code understanding and generation +- **Capabilities**: Repository analysis, package management, code operations +- **Tags**: Responds to development-related queries + +## Interactive Console Interface + +The example includes a full interactive console: + +```csharp +Console.WriteLine("Agent ready! Type 'exit' to quit.\n"); + +while (true) +{ + Console.ForegroundColor = ConsoleColor.Blue; + Console.Write("You: "); + Console.ResetColor(); + + var input = Console.ReadLine(); + + if (input?.ToLower() == "exit") break; + if (string.IsNullOrWhiteSpace(input)) continue; + + Console.ForegroundColor = ConsoleColor.Green; + Console.Write("Agent: "); + + var result = await context.ProcessAsync(input); + Console.WriteLine(result.Message.Content); + Console.ResetColor(); + Console.WriteLine(); +} +``` + +## Example Usage Scenarios + +### Web Research Queries +- **"Find the latest information about .NET 9 features"** +- **"Research current best practices for microservices architecture"** +- **"What are the trending JavaScript frameworks in 2025?"** + +These queries trigger the ExaDeepSearch MCP server using Gemini 2.0 Flash. + +### Filesystem Operations +- **"List all .cs files in my project directory"** +- **"Read the contents of README.md in my desktop folder"** +- **"Create a new file with project documentation"** + +These queries activate the FileSystem MCP server using GroqCloud. + +### GitHub/Code Operations +- **"Show me the recent commits in my repository"** +- **"What npm packages are outdated in my project?"** +- **"Create a new branch for the feature I'm working on"** + +These queries utilize the Octocode MCP server with OpenAI. + +## Advanced Features + +### Intelligent Backend Selection +Each MCP server is configured with the optimal AI backend: +- **Gemini**: Excellent for search and research tasks +- **GroqCloud**: Fast and efficient for file operations +- **OpenAI**: Superior for code understanding and generation + +### Environment Configuration +```csharp +EnvironmentVariables = {{"EXA_API_KEY","your-api-key-here"}} +``` +Supports custom environment variables for MCP server configuration. + +### Security Considerations +- **Filesystem Access**: Limited to specified directories +- **GitHub Access**: Requires explicit authentication +- **API Keys**: Stored securely in environment variables + +## Setup Instructions + +### 1. Install Required Packages +```bash +npm install -g exa-mcp-server +npm install -g @modelcontextprotocol/server-filesystem +npm install -g octocode-mcp +``` + +### 2. Configure API Keys +Set environment variables or appsettings.json: +```json +{ + "OpenAI": { + "ApiKey": "your-openai-key" + }, + "Gemini": { + "ApiKey": "your-gemini-key" + }, + "GroqCloud": { + "ApiKey": "your-groq-key" + } +} +``` + +### 3. GitHub Authentication +```bash +gh auth login +``` + +### 4. Customize File Paths +Update the filesystem paths in the code to match your system: +```csharp +Arguments = ["-y", + "@modelcontextprotocol/server-filesystem", + "/path/to/your/directory1", + "/path/to/your/directory2"] +``` + +## Limitations and Considerations + +### Current MCP Limitations +- **Single Server Response**: Cannot combine responses from multiple MCP servers in one request +- **Sequential Processing**: MCP calls are processed individually +- **Error Handling**: Network or server failures affect functionality + +### Performance Considerations +- **Network Latency**: MCP servers require network calls +- **API Rate Limits**: Multiple AI providers have different rate limits +- **Resource Usage**: Multiple backend models consume more resources + +## Best Practices + +### Tag Strategy +- Use specific, non-overlapping tags to avoid conflicts +- Include both broad and specific terms for flexible matching +- Consider user's natural language patterns + +### Error Handling +```csharp +// Consider implementing timeout handling +// Add retry logic for failed MCP calls +// Provide fallback responses when MCP servers are unavailable +``` + +### Cost Optimization +- Choose appropriate models for each task type +- Monitor API usage across different providers +- Consider caching frequently accessed information + +This MCP example demonstrates the most sophisticated knowledge integration available in MaIN.NET, enabling agents to access external tools and services while intelligently routing different types of queries to the most appropriate AI backends for optimal results. \ No newline at end of file diff --git a/src/assets/docs/examples/example-agent-knowledge-web.md b/src/assets/docs/examples/example-agent-knowledge-web.md new file mode 100644 index 0000000..5268d9e --- /dev/null +++ b/src/assets/docs/examples/example-agent-knowledge-web.md @@ -0,0 +1,210 @@ +# Agent with Knowledge Web Example + +## Overview + +This example creates a specialized Piano Learning Assistant that leverages multiple online knowledge sources. The agent provides expert instruction on piano techniques, scales, chords, and practice methods by accessing curated web resources in real-time. + +## Code Example + +```csharp +using Examples.Utils; +using MaIN.Core.Hub; +using MaIN.Core.Hub.Utils; +using MaIN.Domain.Entities; +using MaIN.Domain.Entities.Agents.AgentSource; + +namespace Examples.Agents; + +public class AgentWithKnowledgeWebExample : IExample +{ + public async Task Start() + { + Console.WriteLine("Piano Learning Assistant with Focused Knowledge Sources"); + AIHub.Extensions.DisableLLamaLogs(); + + var context = await AIHub.Agent() + .WithModel("llama3.2:3b") + .WithMemoryParams(new MemoryParams(){ContextSize = 2137}) + .WithInitialPrompt(""" + You are an expert piano instructor specializing in teaching specific pieces, + techniques, and solving common playing problems. Help students learn exact + fingerings, chord progressions, and troubleshoot technical issues with + detailed, step-by-step guidance for both classical and popular music. + """) + .WithKnowledge(KnowledgeBuilder.Instance + .AddUrl("piano_scales_major", "https://www.pianoscales.org/major.html", + tags: ["scale_fingerings", "c_major_scale", "d_major_scale", "fingering_patterns"]) + .AddUrl("piano_chord_database", "https://www.pianochord.org/", + tags: ["chord_fingerings", "cmaj7_chord", "chord_inversions", "left_hand_chords"]) + .AddUrl("fundamentals_practice_book", "https://fundamentals-of-piano-practice.readthedocs.io/", + tags: ["memorization_techniques", "mental_play_method", "practice_efficiency", "difficult_passages"]) + .AddUrl("hanon_exercises", "https://www.hanon-online.com/", + tags: ["hanon_exercises", "finger_independence", "daily_technical_work", "exercise_1_through_20"]) + .AddUrl("sheet_music_reading", + "https://www.simplifyingtheory.com/how-to-read-sheet-music-for-beginners/", + tags: ["bass_clef_reading", "treble_clef_notes", "note_identification", "staff_reading_speed"]) + .AddUrl("piano_fundamentals", "https://music2me.com/en/magazine/learn-piano-in-13-steps", + tags: ["proper_posture", "finger_numbering", "hand_position", "keyboard_orientation"]) + .AddUrl("theory_lessons", "https://www.8notes.com/theory/", + tags: ["interval_identification", "key_signatures", "circle_of_fifths", "time_signatures"]) + .AddUrl("piano_terms", "https://www.libertyparkmusic.com/musical-terms-learning-piano/", + tags: ["dynamics_markings", "tempo_markings", "articulation_symbols", "expression_terms"])) + .WithSteps(StepBuilder.Instance + .AnswerUseKnowledge() + .Build()) + .CreateAsync(); + + var result = await context + .ProcessAsync("I want to learn the C major scale. What's the exact fingering pattern for both hands?" + "I want short and concrete answer"); + Console.WriteLine(result.Message.Content); + } +} +``` + +## Key Components + +### Model Configuration +- **Model**: `llama3.2:3b` - Efficient local model suitable for educational content +- **Memory Context**: 2137 tokens context size for handling detailed musical information +- **Specialized Prompt**: Positions the agent as an expert piano instructor + +### Knowledge Sources + +The example demonstrates eight carefully curated web-based knowledge sources: + +#### 1. Piano Scales Major (`piano_scales_major`) +- **URL**: https://www.pianoscales.org/major.html +- **Tags**: `["scale_fingerings", "c_major_scale", "d_major_scale", "fingering_patterns"]` +- **Purpose**: Specific fingering patterns for major scales + +#### 2. Piano Chord Database (`piano_chord_database`) +- **URL**: https://www.pianochord.org/ +- **Tags**: `["chord_fingerings", "cmaj7_chord", "chord_inversions", "left_hand_chords"]` +- **Purpose**: Comprehensive chord fingerings and inversions + +#### 3. Fundamentals Practice Book (`fundamentals_practice_book`) +- **URL**: https://fundamentals-of-piano-practice.readthedocs.io/ +- **Tags**: `["memorization_techniques", "mental_play_method", "practice_efficiency", "difficult_passages"]` +- **Purpose**: Advanced practice methods and techniques + +#### 4. Hanon Exercises (`hanon_exercises`) +- **URL**: https://www.hanon-online.com/ +- **Tags**: `["hanon_exercises", "finger_independence", "daily_technical_work", "exercise_1_through_20"]` +- **Purpose**: Technical exercises for finger development + +#### 5. Sheet Music Reading (`sheet_music_reading`) +- **URL**: https://www.simplifyingtheory.com/how-to-read-sheet-music-for-beginners/ +- **Tags**: `["bass_clef_reading", "treble_clef_notes", "note_identification", "staff_reading_speed"]` +- **Purpose**: Music reading fundamentals + +#### 6. Piano Fundamentals (`piano_fundamentals`) +- **URL**: https://music2me.com/en/magazine/learn-piano-in-13-steps +- **Tags**: `["proper_posture", "finger_numbering", "hand_position", "keyboard_orientation"]` +- **Purpose**: Basic piano setup and posture + +#### 7. Theory Lessons (`theory_lessons`) +- **URL**: https://www.8notes.com/theory/ +- **Tags**: `["interval_identification", "key_signatures", "circle_of_fifths", "time_signatures"]` +- **Purpose**: Music theory concepts + +#### 8. Piano Terms (`piano_terms`) +- **URL**: https://www.libertyparkmusic.com/musical-terms-learning-piano/ +- **Tags**: `["dynamics_markings", "tempo_markings", "articulation_symbols", "expression_terms"]` +- **Purpose**: Musical terminology and symbols + +## Example Query Flow + +When a user asks: **"I want to learn the C major scale. What's the exact fingering pattern for both hands?"** + +1. **Query Analysis**: System identifies relevant tags like "c_major_scale", "scale_fingerings", "fingering_patterns" +2. **Source Matching**: Matches to `piano_scales_major` source based on tags +3. **Web Content Retrieval**: Fetches current content from pianoscales.org +4. **Expert Response**: Provides specific fingering patterns with step-by-step guidance + +## Advanced Features + +### Memory Parameters +```csharp +.WithMemoryParams(new MemoryParams(){ContextSize = 2137}) +``` +- Custom context size to handle detailed musical information +- Ensures sufficient memory for complex musical concepts + +### Response Optimization +The query includes: `"I want short and concrete answer"` +- Demonstrates how to guide response format +- Encourages focused, actionable answers + +## Use Cases + +This web-based knowledge pattern is ideal for: + +### Educational Applications +- Subject-specific tutoring systems +- Skills training assistants +- Academic research helpers +- Certification exam preparation + +### Professional Development +- Industry-specific guidance +- Best practices repositories +- Current standards and regulations +- Professional certification support + +### Hobby and Interest Areas +- Specialized skill development +- Community knowledge sharing +- Project-specific guidance +- Learning path recommendations + +## Best Practices + +### Source Selection +- **Currency**: Web sources provide up-to-date information +- **Authority**: Choose reputable, expert sources +- **Specificity**: Select sources that match your domain precisely +- **Diversity**: Include multiple perspectives and approaches + +### Tag Strategy +- **Granular Tags**: Use specific terms like "c_major_scale" rather than just "scales" +- **Synonyms**: Include alternative terms users might use +- **Progressive Difficulty**: Tags can indicate skill levels +- **Cross-References**: Related concepts should share some tags + +### Performance Considerations +- **Source Reliability**: Ensure web sources have good uptime +- **Content Stability**: Prefer sources with stable URLs and content structure +- **Load Time**: Consider the time needed to fetch web content +- **Fallback Options**: Have alternative sources for critical information + +## Error Handling + +### Network Issues +Consider handling network connectivity problems: +```csharp +// Implement retry logic for web requests +// Have offline fallback content for critical information +// Provide graceful degradation when sources are unavailable +``` + +### Content Changes +Web sources may change structure or content: +- Monitor source availability +- Implement content validation +- Have backup sources for critical information + +## Integration Tips + +### Dynamic Content Updates +Web-based knowledge automatically stays current, but consider: +- Caching strategies for frequently accessed content +- Content freshness validation +- Source monitoring for structural changes + +### Multi-Language Support +For international applications: +- Include sources in multiple languages +- Use language-specific tags +- Consider cultural differences in teaching approaches + +This web-based knowledge example demonstrates how to create domain experts that leverage the vast, current information available online while maintaining focused, accurate responses through intelligent tag-based source selection. \ No newline at end of file From e7c316f7541501be53c1f588510e1b7b212b9b36 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Piotr=20Stachaczy=C5=84ski?= <111281468+wisedev-pstach@users.noreply.github.com> Date: Wed, 27 Aug 2025 15:05:32 +0200 Subject: [PATCH 2/2] Update agent-knowledge-overview.md --- src/assets/docs/examples/agent-knowledge-overview.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/assets/docs/examples/agent-knowledge-overview.md b/src/assets/docs/examples/agent-knowledge-overview.md index c0c1695..dec90af 100644 --- a/src/assets/docs/examples/agent-knowledge-overview.md +++ b/src/assets/docs/examples/agent-knowledge-overview.md @@ -2,7 +2,7 @@ ## Introduction -The Knowledge Base feature in MaIN.NET 0.4.1 enables agents to access and utilize external information sources intelligently. This feature allows agents to provide accurate, context-aware responses by leveraging persisted knowledge from files, web sources, and MCP (Model Context Protocol) servers. +The Knowledge Base feature in MaIN.NET 0.5.0 enables agents to access and utilize external information sources intelligently. This feature allows agents to provide accurate, context-aware responses by leveraging persisted knowledge from files, web sources, and MCP (Model Context Protocol) servers. ## How Knowledge Base Works @@ -128,4 +128,4 @@ The system provides progress notifications showing: - Model being used for processing - Real-time updates during knowledge processing -This knowledge base implementation provides a lightweight yet powerful way to enhance agent capabilities with external information sources while maintaining performance and accuracy. \ No newline at end of file +This knowledge base implementation provides a lightweight yet powerful way to enhance agent capabilities with external information sources while maintaining performance and accuracy.