# 🧠 Sentient Brain Multi-Agent System for Smithery.ai

**Advanced AI Code Developer with Multi-Agent Architecture** 🚀

*Last deployment: 2025-01-27*

Advanced AI Code Developer system leveraging multi-agent architecture with SurrealDB unified data layer. Designed for seamless deployment on [Smithery.ai](https://smithery.ai) platform.

## 🚀 Features

- **Ultra Orchestrator**: Master agent coordinating multi-agent workflows
- **Architect Agent**: Intelligent project design and planning
- **Code Analysis**: Deep code understanding and semantic indexing
- **Knowledge Graph**: Unified memory layer with semantic search
- **Debug & Refactor**: Intelligent code improvement and error resolution
- **Failure Prevention**: Advanced mechanisms to prevent common AI failures

## 🏗️ Architecture

### Multi-Agent Framework
- **Ultra Orchestrator**: Routes tasks and manages agent coordination
- **Architect Agent**: Handles project planning and design
- **Code Analysis Agent**: Provides deep code understanding
- **Knowledge Search Agent**: Semantic search across project knowledge
- **Debug & Refactor Agent**: Code improvement and error resolution

### Technology Stack
- **Runtime**: Python 3.11+ with FastAPI
- **Database**: SurrealDB for unified data layer
- **LLM**: Groq API for high-performance inference
- **Framework**: LangGraph for agent workflows
- **Protocol**: MCP (Model Context Protocol) compatible

## 📦 Smithery.ai Deployment

This package is optimized for deployment on Smithery.ai platform using the **Custom Deploy** method.

### Prerequisites
- Smithery.ai account
- GitHub repository
- Required API keys (Groq, optional Google)

### Deployment Steps

1. **Repository Setup**
   ```bash
   git clone <your-repo>
   cd sentient-brain-smithery
   ```

2. **Configuration**
   - Ensure `smithery.yaml` and `Dockerfile` are in root
   - Configure required environment variables in Smithery dashboard

3. **Deploy on Smithery**
   - Connect your GitHub repository to Smithery
   - Navigate to Deployments tab
   - Click "Deploy" to build and host your container

### Required Configuration

| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `GROQ_API_KEY` | Groq API key for LLM inference | Yes | - |
| `SURREAL_URL` | SurrealDB connection URL | Yes | `ws://localhost:8000/rpc` |
| `SURREAL_USER` | SurrealDB username | Yes | `root` |
| `SURREAL_PASS` | SurrealDB password | Yes | `root` |
| `GOOGLE_API_KEY` | Google GenAI API key | No | - |

## 🛠️ Available Tools

### Core Tools

1. **sentient-brain/orchestrate**
   - Master coordination and workflow management
   - Analyzes user intent and routes to appropriate agents

2. **sentient-brain/architect**
   - Project design and architecture planning
   - Technology stack recommendations

3. **sentient-brain/analyze-code**
   - Deep code analysis and understanding
   - Structure, quality, and dependency analysis

4. **sentient-brain/search-knowledge**
   - Semantic search across project knowledge graph
   - Multi-modal search (code, docs, concepts)

5. **sentient-brain/debug-assist**
   - Intelligent debugging and code improvement
   - Error resolution and refactoring suggestions

## 🔧 Usage Examples

### Basic Orchestration
```json
{
  "tool": "sentient-brain/orchestrate",
  "arguments": {
    "query": "I want to build a REST API for user authentication",
    "context": {
      "project_type": "web_api",
      "tech_stack": ["python", "fastapi"]
    }
  }
}
```

### Project Architecture
```json
{
  "tool": "sentient-brain/architect",
  "arguments": {
    "project_type": "web_api",
    "requirements": "User authentication with JWT tokens",
    "tech_stack": ["python", "fastapi", "postgresql"]
  }
}
```

### Knowledge Search
```json
{
  "tool": "sentient-brain/search-knowledge",
  "arguments": {
    "query": "authentication middleware implementation",
    "node_type": "code_chunk",
    "limit": 10
  }
}
```

## 🔍 Health Check

The server provides a health check endpoint:
- `GET /` - Basic server status
- `GET /mcp` - MCP protocol info and available tools

## 🐛 Debugging

### Common Issues

1. **Connection Issues**
   - Verify SurrealDB connection parameters
   - Check network connectivity

2. **API Key Issues**
   - Ensure Groq API key is valid and has sufficient credits
   - Verify API key format and permissions

3. **Configuration Issues**
   - Check Smithery configuration parameters
   - Verify environment variable mapping

### Logs
The server uses structured logging with configurable levels:
- `DEBUG`: Detailed debugging information
- `INFO`: General operational messages
- `WARNING`: Warning messages
- `ERROR`: Error conditions

## 📈 Performance

- **Optimized Docker**: Multi-stage build for minimal image size
- **Async Operations**: Full async/await support for high concurrency
- **Caching**: Intelligent caching for frequently accessed data
- **Connection Pooling**: Efficient database connection management

## 🔒 Security

- **Non-root User**: Container runs as non-privileged user
- **Input Validation**: Comprehensive input validation using Pydantic
- **Rate Limiting**: Built-in rate limiting for API endpoints
- **Secure Defaults**: Security-first configuration defaults

## 📚 Documentation

- [Smithery.ai Documentation](https://smithery.ai/docs)
- [MCP Protocol Specification](https://spec.modelcontextprotocol.io/)
- [SurrealDB Documentation](https://surrealdb.com/docs)
- [Groq API Documentation](https://console.groq.com/docs)

## 🤝 Support

- **Issues**: [GitHub Issues](https://github.com/sentient-brain/smithery-deployment/issues)
- **Documentation**: [docs.sentient-brain.ai](https://docs.sentient-brain.ai)
- **Email**: support@sentient-brain.ai

## 📄 License

MIT License - see LICENSE file for details.

---

**Ready for Smithery.ai deployment!** 🚀

---

## 🇻🇳 Tài liệu Tiếng Việt

### 🧠 Công cụ Cốt lõi

1. **sentient-brain/orchestrate**
   - Điều phối chính và quản lý luồng công việc
   - Phân tích ý định người dùng và chuyển tiếp đến các agent phù hợp

2. **sentient-brain/architect**
   - Thiết kế dự án và lập kế hoạch kiến trúc
   - Đề xuất lựa chọn công nghệ

3. **sentient-brain/analyze-code**
   - Phân tích mã nguồn sâu và hiểu mã
   - Phân tích cấu trúc, chất lượng và phụ thuộc

4. **sentient-brain/search-knowledge**
   - Tìm kiếm ngữ nghĩa trên đồ thị tri thức dự án
   - Tìm kiếm đa phương tiện (mã nguồn, tài liệu, khái niệm)

5. **sentient-brain/debug-assist**
   - Gỡ lỗi thông minh và nâng cao chất lượng mã
   - Gợi ý sửa lỗi và refactor

## 🔧 Ví dụ Sử Dụng

### Điều phối cơ bản
```json
{
  "tool": "sentient-brain/orchestrate",
  "arguments": {
    "query": "Tôi muốn xây dựng REST API cho xác thực người dùng",
    "context": {
      "project_type": "web_api",
      "tech_stack": ["python", "fastapi"]
    }
  }
}
```

### Thiết kế Kiến trúc Dự án
```json
{
  "tool": "sentient-brain/architect",
  "arguments": {
    "project_type": "web_api",
    "requirements": "Xác thực người dùng bằng JWT",
    "tech_stack": ["python", "fastapi", "postgresql"]
  }
}
```

### Tìm kiếm Tri thức
```json
{
  "tool": "sentient-brain/search-knowledge",
  "arguments": {
    "query": "triển khai middleware xác thực",
    "node_type": "code_chunk",
    "limit": 10
  }
}
```

## 🔍 Kiểm tra Sức khỏe

Máy chủ cung cấp các endpoint kiểm tra sức khỏe:
- `GET /` - Kiểm tra trạng thái cơ bản
- `GET /mcp` - Thông tin giao thức MCP và danh sách công cụ khả dụng

## 🐛 Gỡ Lỗi

### Các Vấn Đề Thường Gặp

1. **Kết nối đến CSDL**
   - Kiểm tra lại thông tin kết nối SurrealDB
   - Xác nhận kết nối mạng

2. **Vấn đề API Key**
   - Đảm bảo API key Groq hợp lệ và còn hạn mức sử dụng
   - Kiểm tra định dạng và quyền truy cập của API key

3. **Vấn đề Cấu hình**
   - Kiểm tra lại các tham số cấu hình Smithery
   - Đảm bảo ánh xạ biến môi trường chính xác

### Ghi log
Máy chủ sử dụng logging có cấu trúc với các mức độ cấu hình:
- `DEBUG`: Thông tin gỡ lỗi chi tiết
- `INFO`: Thông báo hoạt động chung
- `WARNING`: Cảnh báo
- `ERROR`: Lỗi nghiêm trọng

## 📈 Hiệu Năng

- **Docker tối ưu**: Multi-stage build giúp giảm kích thước image
- **Hoạt động bất đồng bộ**: Hỗ trợ async/await cho hiệu suất cao
- **Bộ nhớ đệm**: Cache thông minh cho dữ liệu truy cập thường xuyên
- **Kết nối pooling**: Quản lý kết nối CSDL hiệu quả

## 🔒 Bảo Mật

- **Chạy không quyền root**: Container chạy bằng user không đặc quyền
- **Kiểm tra đầu vào**: Sử dụng Pydantic để kiểm tra dữ liệu vào
- **Giới hạn tốc độ**: Tích hợp rate limiting cho các endpoint
- **Cấu hình an toàn mặc định**: Ưu tiên bảo mật từ đầu

## 📚 Tài liệu

- [Tài liệu Smithery.ai](https://smithery.ai/docs)
- [Đặc tả giao thức MCP](https://spec.modelcontextprotocol.io/)
- [Tài liệu SurrealDB](https://surrealdb.com/docs)
- [Tài liệu Groq API](https://console.groq.com/docs)

## 🤝 Hỗ trợ

- **Báo lỗi/Góp ý**: [GitHub Issues](https://github.com/sentient-brain/smithery-deployment/issues)
- **Tài liệu**: [docs.sentient-brain.ai](https://docs.sentient-brain.ai)
- **Email**: support@sentient-brain.ai

## 📄 Giấy phép

MIT License - xem file LICENSE để biết chi tiết.

---

**Sẵn sàng triển khai trên Smithery.ai!** 🚀