Ufuq (Moniaar)

Ufuq人工智能辅导平台

一个离线的第一个人工智能辅导系统，为难民和服务不足的学生使用模型上下文协议（MCP）。通过Wi-Fi热点与可选的云集成在本地工作。

🌟 特性

核心能力

• 离线优先：使用本地AI模型在没有互联网的情况下工作
• 多代理系统：辅导、翻译、测验和内容检索的专业代理
• 双语支持：阿拉伯语和英语，实时翻译
• 渐进式Web应用程序：适用于手机、平板电脑和电脑
• 本地网络接入：学生通过Wi-Fi热点或局域网连接
• 云同步：互联网可用时同步进度

MCP代理

1. 助教代理人 -解释概念，回答问题
2. 翻译代理 -阿拉伯语↔ 英语翻译
3. 测验代理 -生成并评分评估
4. 内容代理 -从存储的教育材料（RAG）中检索
5. 同步代理 -在线时将数据同步到云端

🚀 快速开始

先决条件

• Python 3.9+
• 4GB+RAM（适用于本地型号）
• Wi-Fi热点功能或本地网络

安装

# Clone the repository
git clone 
cd ufuq

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Download models (first time only)
python download_models.py

配置

创建一个 .env 文件：

# Optional: Add API keys for online mode
OPENAI_API_KEY=your_key_here
SAMBANOVA_API_KEY=your_key_here
MODAL_API_KEY=your_key_here

# Debug mode
DEBUG=True

运行服务器

# Start the Flask backend
python app.py

服务器将在上运行 http://0.0.0.0:5000 （可在本地网络上访问）

连接学生

1. 启用Wi-Fi热点 在主机设备上
2. 学生连接到热点
3. 学生打开浏览器并导航到： http://:5000
4. 开始学习！

📁 项目结构

ufuq/
├── app.py                 # Main Flask application
├── mcp_runtime.py         # MCP agent orchestration hub
├── agents.py              # All 5 MCP agents
├── storage.py             # Database and caching
├── config.py              # Configuration management
├── requirements.txt       # Python dependencies
├── download_models.py     # Model download script
├── data/
│   ├── ufuq.db           # SQLite database
│   ├── cache/            # Offline cache
│   ├── vectordb/         # ChromaDB vector storage
│   └── content/          # Educational PDFs/materials
└── frontend/             # React PWA (separate)
    └── ...

🔧 API终点

聊天（导师代理）

POST /api/chat
{
  "student_id": "student_123",
  "message": "Explain Newton's laws",
  "language": "en"
}

翻译

POST /api/translate
{
  "text": "Hello, how are you?",
  "source_lang": "en",
  "target_lang": "ar"
}

生成测验

POST /api/quiz/generate
{
  "student_id": "student_123",
  "topic": "Physics - Newton's Laws",
  "difficulty": "medium",
  "num_questions": 5,
  "language": "en"
}

提交测验

POST /api/quiz/submit
{
  "student_id": "student_123",
  "quiz_id": 1,
  "answers": ["A", "B", "C", "D", "A"]
}

检索内容（RAG）

POST /api/content/retrieve
{
  "query": "What is photosynthesis?",
  "subject": "biology",
  "language": "en"
}

学生进步

GET /api/student/progress?student_id=student_123

同步数据

POST /api/sync
{
  "student_id": "student_123"
}

检查模式

GET /api/mode

🤖 MCP架构

运作原理

1. 学生申请 → Flask收到HTTP请求
2. MCP路由器 → 通往合适代理商的路线
3. 代理执行 → 使用本地/云模型的代理进程
4. 模式检测 → 自动在离线/在线之间切换
5. 响应 → 将结果返回给学生
6. 存储 → 在本地保存交互，在线时同步

代理选择逻辑

# MCP Runtime automatically routes based on request type
mcp_runtime.route_request(
    agent_type="tutor",  # or "translator", "quiz", "content", "sync"
    payload={...}
)

离线↔ 在线切换

系统会自动检测互联网连接：

• 离线：使用拥抱脸模型（FLAN-T5，赫尔辛基NLP）
• 在线的：使用OpenAI GPT-4获得更好的质量
• 混合：如果联机失败，则返回脱机状态

📚 添加教育内容

为RAG摄取PDF

# Create a content ingestion script
from content_ingestion import ingest_pdf

# Add textbooks
ingest_pdf('path/to/physics_textbook.pdf', subject='physics')
ingest_pdf('path/to/math_textbook.pdf', subject='mathematics')

手动添加内容

from agents import ContentAgent
from config import Config

config = Config()
content_agent = ContentAgent(config)

# Add content manually
content_agent.collection.add(
    documents=["Newton's First Law: Objects at rest stay at rest..."],
    metadatas=[{"subject": "physics", "source": "textbook_ch1"}],
    ids=["physics_newton_1"]
)

🌐 云集成（可选）

OpenAI设置

# Set API key in .env
OPENAI_API_KEY=sk-...

模态设置（用于无服务器功能）

pip install modal
modal token new

SambaNova设置

# Add SambaNova API key
SAMBANOVA_API_KEY=your_key

🧪 测试

# Run tests
pytest tests/

# Test specific agent
pytest tests/test_tutor_agent.py

# Test offline mode
FORCE_OFFLINE=True pytest tests/

📱 前端集成

React PWA连接到这些端点。例子：

// Chat with tutor
const response = await fetch('http://:5000/api/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    student_id: 'student_123',
    message: 'Explain gravity',
    language: 'en'
  })
});

const data = await response.json();
console.log(data.response);  // AI tutor's explanation

🔐 安全考虑

• 仅限本地网络：默认情况下，只能在局域网上访问
• 无身份验证：添加生产身份验证
• 数据隐私：所有数据存储在本地，可选择同步
• API密钥：保持 .env，永远不要承诺使用git

🐛 故障排除

模型未加载

# Re-download models
python download_models.py --force

端口已在使用中

# Change port in app.py
app.run(host='0.0.0.0', port=5001)

内存不足

• 减小模型尺寸 config.py
• 使用较小的模型（例如。， flan-t5-small 而不是 base)
• 禁用本地模型加载并使用仅在线模式

连接问题

• 检查防火墙设置
• 确保同一网络上的所有设备
• 使用IP地址而不是localhost

📊 性能优化

对于低资源设备

# In config.py, use smaller models
'offline': {
    'tutor': 'google/flan-t5-small',  # Instead of base
    'translator': 'Helsinki-NLP/opus-mt-tc-big-en-ar'  # Smaller variant
}

批处理

# Process multiple quiz questions at once
quiz_agent.execute({
    'action': 'batch_generate',
    'topics': ['physics', 'math', 'chemistry']
})

🤝 贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 测试离线和在线模式
5. 提交拉取请求

📄 许可证

麻省理工学院许可证-可自由用于教育目的

🆘 支持

关于黑客马拉松期间的问题：

• 检查日志： tail -f logs/ufuq.log
• 测试模式： curl http://localhost:5000/health

🚀 后续步骤

• \[\]添加语音输入/输出
• \[\]实现点对点测验共享
• \[\]添加游戏化（积分、徽章）
• \[\]多用户协作功能
• \[\]教师监控仪表板
• \[\]更多语言（法语、西班牙语）
• \[\]离线视频课程

______________________________________________________________________

内置于❤️ 面向全球服务不足的学生