File size: 8,694 Bytes
2077d8b 970f1a9 2bc1f40 2077d8b 729864f edb3b14 aee77fd edb3b14 2077d8b 970f1a9 edb3b14 970f1a9 edb3b14 2bc1f40 970f1a9 0ffe7cd d09f6aa 970f1a9 d09f6aa 970f1a9 d09f6aa 970f1a9 d09f6aa 970f1a9 d09f6aa edb3b14 970f1a9 d09f6aa 970f1a9 d09f6aa 970f1a9 d09f6aa 970f1a9 d09f6aa 970f1a9 d09f6aa 970f1a9 d09f6aa edb3b14 d09f6aa edb3b14 d09f6aa edb3b14 d09f6aa 970f1a9 edb3b14 970f1a9 d09f6aa 970f1a9 d09f6aa 970f1a9 ee05e09 edb3b14 ee05e09 970f1a9 d09f6aa 970f1a9 d09f6aa da741a9 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 |
---
title: AnkiGen
emoji: π
app_file: app.py
requirements: requirements.txt
python: 3.10
sdk: gradio
sdk_version: 5.34.2
---
# AnkiGen - Anki Card Generator
AnkiGen is a Gradio-based web application that generates high-quality Anki-compatible CSV and `.apkg` deck files using an advanced multi-agent system powered by OpenAI Agents. The system employs specialized generator agents, quality assessment judges, and enhancement agents to create superior flashcards.
## Features
- **Multi-Agent Card Generation**: Utilizes specialized agents for subject expertise, pedagogical guidance, and content structuring
- **Quality Assurance System**: Multiple judge agents evaluate cards for accuracy, clarity, pedagogical value, and completeness
- **Adaptive Enhancement**: Revision and enhancement agents improve cards based on judge feedback
- Generate Anki cards for various subjects or from provided text/URLs
- Generate a structured learning path for a complex topic
- Customizable number of topics and cards per topic
- User-friendly interface powered by Gradio
- Exports to CSV for manual import or `.apkg` format with default styling
- Advanced OpenAI Agents SDK integration with structured outputs
## How It Works
```mermaid
graph TD
A[User Input] --> B[Generation Coordinator]
B --> C[Subject Expert Agent]
B --> D[Pedagogical Agent]
B --> E[Content Structuring Agent]
C --> F[Generated Cards]
D --> F
E --> F
F --> G[Judge Coordinator]
G --> H[Content Accuracy Judge]
G --> I[Pedagogical Judge]
G --> J[Clarity Judge]
G --> K[Technical Judge]
G --> L[Completeness Judge]
H --> M{All Judges Pass?}
I --> M
J --> M
K --> M
L --> M
M -->|No| N[Revision Agent]
N --> O[Enhancement Agent]
O --> B
M -->|Yes| P[Final High-Quality Cards]
P --> Q[Export to CSV/APKG]
```
## Installation for Local Use
Preferred usage: [uv](https://github.com/astral-sh/uv)
1. Clone this repository:
```bash
git clone https://github.com/brickfrog/ankigen.git
cd ankigen
uv venv
source .venv/bin/activate # Activate the virtual environment
```
2. Install the required dependencies:
```bash
uv pip install -e . # Install the package in editable mode
```
3. Set up your OpenAI API key:
- Create a `.env` file in the project root (`ankigen/`).
- Add your key like this: `OPENAI_API_KEY="your_sk-xxxxxxxx_key_here"`
- The application will load this key automatically.
- **Note**: This application requires OpenAI API access and uses the `openai-agents` SDK for advanced multi-agent functionality.
## Usage
1. Ensure your virtual environment is active (`source .venv/bin/activate`).
2. Run the application:
```bash
uv run python app.py
```
*(Note: The `gradio app.py` command might also work but using `python app.py` within the `uv run` context is recommended.)*
3. Open your web browser and navigate to the provided local URL (typically `http://127.0.0.1:7860`).
4. In the application interface:
- Your API key should be loaded automatically if using a `.env` file, otherwise enter it.
- Select the desired generation mode ("Single Subject", "Learning Path", "From Text", "From Web").
- Fill in the relevant inputs for the chosen mode.
- Adjust generation parameters (model, number of topics/cards, preferences).
- Click "Generate Cards" or "Analyze Learning Path".
5. Review the generated output.
6. For card generation, click "Export to CSV" or "Export to Anki Deck (.apkg)" to download the results.
## Project Structure
The codebase uses a sophisticated multi-agent architecture powered by the OpenAI Agents SDK:
- `app.py`: Main Gradio application interface and event handling.
- `ankigen_core/`: Directory containing the core logic modules:
- `agents/`: **OpenAI Agents system implementation**:
- `base.py`: Base agent wrapper and configuration classes
- `generators.py`: Specialized generator agents (SubjectExpertAgent, PedagogicalAgent, ContentStructuringAgent)
- `judges.py`: Quality assessment agents (ContentAccuracyJudge, PedagogicalJudge, ClarityJudge, etc.)
- `enhancers.py`: Revision and enhancement agents for card improvement
- `integration.py`: AgentOrchestrator for coordinating the entire agent system
- `config.py`: Agent configuration management
- `schemas.py`: Pydantic schemas for structured agent outputs
- `templates/`: Jinja2 templates for agent prompts
- `models.py`: Pydantic models for data structures.
- `utils.py`: Logging, caching, web fetching utilities.
- `llm_interface.py`: OpenAI API client management.
- `card_generator.py`: Integration layer for agent-based card generation.
- `learning_path.py`: Logic for the learning path analysis feature.
- `exporters.py`: Functions for exporting data to CSV and `.apkg`.
- `ui_logic.py`: Functions handling UI component updates and visibility.
- `tests/`: Contains unit and integration tests.
- `unit/`: Tests for individual modules in `ankigen_core`.
- `integration/`: Tests for interactions between modules and the app.
- `pyproject.toml`: Defines project metadata, dependencies, and build system configuration.
- `README.md`: This file.
## Agent System Architecture
AnkiGen employs a sophisticated multi-agent system built on the OpenAI Agents SDK that ensures high-quality flashcard generation through specialized roles and quality control:
### Generator Agents
- **SubjectExpertAgent**: Provides domain-specific expertise for accurate content creation
- **PedagogicalAgent**: Ensures cards follow effective learning principles and memory techniques
- **ContentStructuringAgent**: Optimizes card structure, formatting, and information hierarchy
### Quality Assurance Judges
- **ContentAccuracyJudge**: Verifies factual correctness and subject matter accuracy
- **PedagogicalJudge**: Evaluates learning effectiveness and educational value
- **ClarityJudge**: Assesses readability, comprehension, and clear communication
- **TechnicalJudge**: Reviews technical accuracy for specialized subjects
- **CompletenessJudge**: Ensures comprehensive coverage without information gaps
### Enhancement Agents
- **RevisionAgent**: Identifies areas for improvement based on judge feedback
- **EnhancementAgent**: Implements refinements and optimizations to failed cards
### Orchestration
- **GenerationCoordinator**: Manages the card generation workflow and agent handoffs
- **JudgeCoordinator**: Coordinates quality assessment across all judge agents
- **AgentOrchestrator**: Main system controller that initializes and manages the entire agent ecosystem
This architecture ensures that every generated flashcard undergoes rigorous quality control and iterative improvement, resulting in superior learning materials.
## Development
This project uses `uv` for environment and package management and `pytest` for testing.
1. **Setup:** Follow the Installation steps above.
2. **Install Development Dependencies:**
```bash
uv pip install -e ".[dev]"
```
3. **Running Tests:**
- To run all tests:
```bash
uv run pytest tests/
```
- To run with coverage:
```bash
uv run pytest --cov=ankigen_core tests/
```
*(Current test coverage target is >= 80%. As of the last run, coverage was ~89%.)*
4. **Code Style:** Please use `black` and `ruff` for formatting and linting (configured in `pyproject.toml` implicitly via dev dependencies, can be run manually).
5. **Making Changes:**
- Core logic changes should primarily be made within the `ankigen_core` modules.
- UI layout and event wiring are in `app.py`.
- Add or update tests in the `tests/` directory for any new or modified functionality.
## TODO
- [ ] Edit columns /fields
- [ ] Improve crawler / RAG integration with agents
- [ ] Add agent performance metrics and monitoring
- [ ] Implement agent conversation history and context persistence
- [ ] Add custom agent configuration UI
- [ ] Expand subject-specific agent templates
## License
BSD 2-Clause License
## Acknowledgments
- This project uses the Gradio library (https://gradio.app/) for the web interface.
- Card generation is powered by OpenAI's language models.
- Card generation principles inspired by ["An Opinionated Guide to Using Anki Correctly"](https://www.lesswrong.com/posts/7Q7DPSk4iGFJd8DRk/an-opinionated-guide-to-using-anki-correctly) by Luise, which emphasizes atomic card design, standardized prompts, and effective spaced repetition practices.
|