raven-agent 0.1.2

Raven — AI-assisted learning companion. Auto-detect materials, split by chapters, generate quizzes, organize notes.

Raven — AI Learning Companion

Huginn (思索) & Muninn (记忆) — the two ravens of Odin, now your study partners.

Raven is a CLI agent that helps you study. Drop it into any directory with learning materials, and it:

• Reads PDFs, Word docs, PowerPoints
• Splits materials into chapters (PDF slices or Markdown)
• Summarizes content with AI
• Quizzes you on what you've learned (✓/△/✗ grading)
• Organizes your rough notes into polished documents

Installation

全局安装（推荐，所有目录都能用）：

pip install raven-agent

安装后 Raven 命令全局可用。在任何包含学习资料的目录下直接运行即可。

API Key 配置

Raven 使用 DeepSeek API，三种配置方式任选：

方式一：什么都不做，首次运行自动引导（推荐）

Raven
# 首次运行没有 key 时，会自动提示：
#
#   DeepSeek API key not found. Set it now (one-time):
#     Or: $env:DEEPSEEK_API_KEY = "sk-..."
#     Paste your API key: █
#
# 粘贴一次，自动保存到 ~/.raven/config.toml，以后无需再配。

方式二：环境变量（临时会话）

# Windows PowerShell
$env:DEEPSEEK_API_KEY = "sk-..."

# macOS / Linux
export DEEPSEEK_API_KEY="sk-..."

方式三：手动写入配置文件

# ~/.raven/config.toml
api_key = "sk-..."

优先级：环境变量 > 配置文件 > 交互提示

获取 API key：https://platform.deepseek.com/api_keys

Quick Start

# 进入学习目录
cd ~/my-study-materials

# 启动 Raven
Raven

# Raven 自动：
# 1. 创建 huginn/（思索）和 muninn/（记忆）目录
# 2. 扫描当前目录中的 PDF、DOCX、PPTX、MD 文件
# 3. 列出找到的学习材料，等待你的指令

Directory Structure

Raven creates two directories in your working folder:

./
├── muninn/                  # Memory — structured knowledge
│   ├── chapters/            #   Chapter splits
│   ├── summaries/           #   AI-generated summaries
│   └── knowledge/           #   Extracted terminology
└── huginn/                  # Thought — active learning
    ├── 章节检测/             #   Chapter quizzes
    └── 学习笔记/             #   Study notes

Usage Examples

# 拆分教材
> 帮我把机器学习入门.pdf 拆分到 muninn

# 生成摘要
> 给第三章生成一个摘要

# 自测
> 考考我关于线性回归的知识

# 整理笔记
> 帮我整理 huginn/学习笔记/rough.md

Commands

Command	Action
/help	Show help
/mode read|yn|auto	Change permission mode
/clear	Reset conversation
/exit	Quit
Ctrl+C	Interrupt agent (then Continue/Discard/Quit)

Requirements

• Python >= 3.10
• DeepSeek API key (get one here)

License

MIT