# self-assessment-agent

**Repository Path**: kevinlights/self-assessment-agent

## Basic Information

- **Project Name**: self-assessment-agent
- **Description**: Self Assessment Agent, built with RAG, LLM, etc.
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-01
- **Last Updated**: 2026-06-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Self Assessment Agent

## Overview
Generate Assessment Questions and Answers for Self Assessment, based on the user's input and the context.
根据用户输入和上下文，生成自我评估的问题和答案。

The context is from RAG which is built on top of the Langchain.
上下文来自基于 Langchain 构建的 RAG（检索增强生成）。

User gives the document or the link as input, and the tool will fetch docs and prepare vector store.
用户提供文档或链接作为输入，工具将获取文档并准备向量存储。

After that, the Agent will generate the assessment questions and answers based on the vector store, and the user can know the level of his knowledge.
之后，智能体将基于向量库生成评估问题和答案，用户可以了解自己的知识水平。

## Features / 功能特性

- **RAG-based Question Generation**: Generate assessment questions from any document or URL using Retrieval-Augmented Generation
  **基于 RAG 的问题生成**：使用检索增强生成从任何文档或 URL 生成评估问题

- **Topic-Focused Questions**: Provide a specific topic and focus areas to generate more targeted questions
  **主题聚焦问题**：提供特定主题和聚焦领域，生成更有针对性的问题

- **Self-Assessment Flow**: After each question, users rate their knowledge as Known (知道), Vague (模糊), or Unknown (不知道)
  **自我评估流程**：每个问题后，用户评价自己的知识为：知道、模糊、不知道

- **Bilingual Support**: Full English and Simplified Chinese bilingual support with toggle
  **双语支持**：完整的英文和简体中文双语支持，可切换

- **Beautiful TUI**: Built with Textual framework, providing an interactive terminal UI with rich styling
  **漂亮的终端界面**：基于 Textual 框架构建，提供丰富的终端交互界面

- **Assessment Report**: Generate a comprehensive report with mastery percentage, knowledge level, and detailed review
  **评估报告**：生成包含掌握百分比、知识水平和详细回顾的综合报告

- **Q&A Details View**: View detailed question-answer pairs with bilingual display
  **问答详情视图**：查看双语对照的详细问答对

- **Assessment History**: All assessments are automatically saved to SQLite database with view, delete, and reload capabilities
  **评估历史**：所有评估自动保存到 SQLite 数据库，支持查看、删除和重新加载

- **Slash Commands**: Support `/new` to start a new assessment, `/quit` to exit
  **斜杠命令**：支持 `/new` 开始新评估，`/quit` 退出

## Architecture / 架构

```
saa/
├── __init__.py
├── __main__.py          # CLI entry point / CLI 入口点
├── core/
│   ├── __init__.py
│   ├── rag.py           # RAG pipeline: document loading, vector store, retrieval
│   │                    # RAG 流水线：文档加载、向量存储、检索
│   ├── agent.py         # Assessment agent: question generation, answer collection
│   │                    # 评估智能体：问题生成、答案收集
│   ├── report.py        # Report generator using rich
│   │                    # 使用 rich 的报告生成器
│   └── history.py       # Assessment history management with SQLite
│                        # 基于 SQLite 的评估历史管理
└── tui/
    ├── __init__.py
    ├── app.py           # Main TUI application with Textual
    │                    # 基于 Textual 的主 TUI 应用程序
    └── screens.py       # Input, Question, Report, Details, History screens
                         # 输入、问题、报告、详情、历史屏幕

data/
└── assessments.db       # SQLite database for assessment history
                         # 评估历史的 SQLite 数据库
```

## Installation / 安装

```bash
# Clone or navigate to the project directory
# 克隆或导航到项目目录
cd publish/self-assessment-agent

# Create virtual environment and install dependencies
# 创建虚拟环境并安装依赖
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

# Or use Tsinghua mirror for faster installation in China
# 或使用清华镜像源加速国内安装
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -e .
```

## Usage / 使用

### Start the TUI Application / 启动 TUI 应用程序

```bash
# Activate virtual environment
# 激活虚拟环境
source .venv/bin/activate

# Run the application
# 运行应用程序
python -m saa

# Or use the CLI entry point
# 或使用 CLI 入口点
saa
```

### CLI Options / CLI 选项

```bash
# Start with pre-filled sources
# 使用预填源启动
saa --sources ./docs/readme.md https://example.com/doc

saa --sources https://docs.langchain.com/oss/python/langchain/multi-agent/handoffs-customer-support --language zh

# Customize question count
# 自定义问题数量
saa -q 15

# Use custom LLM URL
# 使用自定义 LLM URL
saa --llm-url http://your-llm-server:1234/v1

# Use custom model
# 使用自定义模型
saa --model qwen2.5-7b-instruct --embedding-model text-embedding-nomic-embed-text-v1.5

# Set topic and focus areas for targeted questions
# 设置主题和聚焦领域以生成有针对性的问题
saa --topic "Machine Learning" --focus-areas "neural networks" "backpropagation"

# Set display language (en or zh)
# 设置显示语言（英文或中文）
saa --language zh
```

### Environment Variables / 环境变量

| Variable | Default | Description |
|----------|---------|-------------|
| `LLM_BASE_URL` | `http://127.0.0.1:1234/v1` | LLM API base URL / LLM API 基础 URL |
| `LLM_API_KEY` | `lm-studio` | LLM API key / LLM API 密钥 |
| `LLM_MODEL` | `qwen2.5-7b-instruct` | LLM model name / LLM 模型名称 |
| `EMBEDDING_MODEL` | `text-embedding-nomic-embed-text-v1.5` | Embedding model / 嵌入模型 |
| `DEFAULT_QUESTION_COUNT` | `10` | Default questions per session / 每次会话默认问题数 |
| `VECTOR_STORE_DIR` | `.vector_store` | Vector store persistence directory / 向量存储持久化目录 |

## Workflow / 工作流程

1. **Input Sources**: Enter file paths or URLs (comma-separated for multiple), optionally set topic and focus areas
   **输入源**：输入文件路径或 URL（多个用逗号分隔），可选设置主题和聚焦领域

2. **Document Processing**: The RAG pipeline loads documents, splits them into chunks, and builds a vector store
   **文档处理**：RAG 流水线加载文档，将其分割为块，并构建向量存储

3. **Question Generation**: The agent generates ~10 questions based on the document context and topic
   **问题生成**：智能体基于文档上下文和主题生成约 10 个问题

4. **Self-Assessment**: For each question, select your confidence level:
   **自我评估**：对每个问题，选择你的信心级别：
   - ✓ **Known (知道)**: You understand this concept well
     你很好地理解这个概念
   - ~ **Vague (模糊)**: You have a rough idea but not confident
     你有大致了解但不够自信
   - ✗ **Unknown (不知道)**: This is new to you
     这对你来说是新的

5. **Report Generation**: After completing all questions, view your assessment report with:
   **报告生成**：完成所有问题后，查看你的评估报告，包括：
   - Mastery percentage (Known / Total)
     掌握百分比（知道 / 总数）
   - Familiarity percentage ((Known + Vague) / Total)
     熟悉度百分比（（知道 + 模糊）/ 总数）
   - Knowledge level assessment (Expert, Proficient, Intermediate, Beginner, Novice)
     知识水平评估（专家、熟练、中级、初学者、新手）
   - Detailed review of each question grouped by confidence level
     按信心级别分组的每个问题的详细回顾

6. **History Management**: All assessments are automatically saved to SQLite database. You can:
   **历史管理**：所有评估自动保存到 SQLite 数据库。你可以：
   - View past assessments and their scores
     查看过往评估及其分数
   - View detailed Q&A from any past assessment
     查看任何过往评估的详细问答
   - Delete outdated assessments
     删除过时的评估

## Keyboard Shortcuts / 键盘快捷键

### Global Shortcuts / 全局快捷键

| Key | Action | 操作 |
|-----|--------|------|
| `q` | Quit application | 退出应用 |
| `h` | View assessment history | 查看评估历史 |

### Input Screen / 输入页面

| Key | Action | 操作 |
|-----|--------|------|
| `h` | View history | 查看历史 |
| `Enter` | Start assessment | 开始评估 |

### Question Screen / 答题页面

| Key | Action | 操作 |
|-----|--------|------|
| `n` | Next question | 下一个问题 |
| `p` | Previous question | 上一个问题 |
| `space` | Show/hide answer | 显示/隐藏答案 |
| `r` | View report | 查看报告 |
| `d` | View details | 查看详情 |
| `h` | View history | 查看历史 |

### Report Screen / 报告页面

| Key | Action | 操作 |
|-----|--------|------|
| `n` | New assessment | 新评估 |
| `d` | View details | 查看详情 |
| `h` | View history | 查看历史 |

### Details Screen / 详情页面

| Key | Action | 操作 |
|-----|--------|------|
| `n` | Next Q&A | 下一个问答 |
| `p` | Previous Q&A | 上一个问答 |
| `r` | Back to report | 返回报告 |
| `h` | View history | 查看历史 |

### History Screen / 历史页面

| Key | Action | 操作 |
|-----|--------|------|
| `v` | View selected assessment | 查看选中的评估 |
| `d` | Delete selected assessment | 删除选中的评估 |
| `n` | New assessment | 新评估 |
| `q` / `esc` | Back | 返回 |

## Dependencies / 依赖

- **textual**: TUI framework / 终端用户界面框架
- **rich**: Rich text and beautiful formatting / 富文本和漂亮的格式化
- **langchain**: LLM application framework / LLM 应用程序框架
- **langchain-chroma**: Vector store integration / 向量存储集成
- **langchain-openai**: OpenAI-compatible LLM client (works with LM Studio) / OpenAI 兼容的 LLM 客户端（与 LM Studio 兼容）
- **chromadb**: Vector database / 向量数据库
- **beautifulsoup4**: HTML parsing for URL loading / 用于 URL 加载的 HTML 解析
- **tiktoken**: Token counting / Token 计数

## Local LLM Setup / 本地 LLM 设置

This project is designed to work with **LM Studio** running locally:
本项目设计为与本地运行的 **LM Studio** 配合使用：

1. Install and start LM Studio
   安装并启动 LM Studio

2. Download a compatible model (e.g., Qwen2.5-7B-Instruct)
   下载兼容的模型（如 Qwen2.5-7B-Instruct）

3. Start the local server at `http://127.0.0.1:1234`
   在 `http://127.0.0.1:1234` 启动本地服务器

4. The application will automatically connect to LM Studio
   应用程序将自动连接到 LM Studio

## License / 许可证

MIT License