Metadata-Version: 2.4
Name: raven-agent
Version: 0.1.1
Summary: Raven — AI-assisted learning companion. Auto-detect materials, split by chapters, generate quizzes, organize notes.
Project-URL: Repository, https://github.com/JIANGXIADADAO/raven-agent
License-Expression: MIT
Requires-Python: >=3.10
Requires-Dist: httpx>=0.28.0
Requires-Dist: pdfplumber>=0.10.0
Requires-Dist: pypdf>=4.0.0
Requires-Dist: python-docx>=1.0.0
Requires-Dist: python-pptx>=0.6.0
Requires-Dist: reportlab>=4.0.0
Description-Content-Type: text/markdown

# 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

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

```bash
pip install raven-agent
```

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

## API Key 配置

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

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

```bash
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，以后无需再配。
```

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

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

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

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

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

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

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

## Quick Start

```bash
# 进入学习目录
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

```bash
# 拆分教材
> 帮我把机器学习入门.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](https://platform.deepseek.com/api_keys))

## License

MIT
