mindquest 0.1.0__tar.gz

mindquest-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dima Statz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mindquest-0.1.0/PKG-INFO

@@ -0,0 +1,468 @@
+Metadata-Version: 2.1
+Name: mindquest
+Version: 0.1.0
+Summary: mindquest: An AI-powered platform that creates fun, educational podcasts for children aged 6–12 by turning verified facts into engaging audio stories using LLMs and high-quality text-to-speech technology
+Home-page: https://github.com/dimastatz/whisper-flow
+Author: Dima Statz
+Author-email: dima.statz@gmail.com
+License: UNKNOWN
+Platform: UNKNOWN
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+<div align="center">
+<h1 align="center">🎙️ MindQuest</h1> 
+<h3>Automated AI-Powered Educational Content Studio for Kids (Ages 8–12)</h3>
+<img src="https://img.shields.io/badge/Status-Active-green"> <img src="https://img.shields.io/badge/Coverage-95.04%25-brightgreen"> <img src="https://img.shields.io/badge/Pylint-9.93%2F10-brightgreen">
+<br><br>
+<img src="https://github.com/dimastatz/mindquest/blob/main/docs/imgs/mindquest.png?raw=true" width="256px"> 
+</div>
+
+---
+
+## Overview
+
+**MindQuest** is a Python-based AI platform that automatically generates engaging, educational content for children aged 8–12. It combines:
+
+- **Educational Content** from WikiKids (age-appropriate information)
+- **AI Script Generation** using ChatGPT-4 to create engaging dialogues
+- **Podcast Production** with natural voice synthesis via OpenAI's TTS API
+- **Mini-Book Generation** in EPUB/PDF formats with structured chapters
+- **Character-Based Storytelling** featuring two distinct personalities:
+  - **Plato**: A wise, calm professor who explains concepts
+  - **Pixel**: A curious, energetic 10-year-old asking questions
+
+The entire system is built with **pure functional programming**, comprehensive testing (95%+ coverage), and production-grade code quality.
+
+---
+
+## Quick Start
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/mindquest.git
+cd mindquest
+
+# Create virtual environment
+python3 -m venv .venv
+source .venv/bin/activate
+
+# Install dependencies
+pip install -r requirements.txt
+```
+
+### Generate Your First Podcast
+
+```python
+import os
+from mindquest import generate_podcast, create_minibook
+
+api_key = os.getenv("OPENAI_API_KEY")
+
+# Generate a 5-minute English podcast about Solar System
+generate_podcast(
+    topic="Solar System",
+    api_key=api_key,
+    output_file="podcast.mp3",
+    word_count=700,
+    languages="en"
+)
+
+# OR generate an educational mini-book (EPUB format)
+ebook_path = create_minibook(
+    api_key=api_key,
+    topic="Solar System",
+    language="en",
+    output_format="epub"
+)
+```
+
+**Results:** 
+- Podcast: A professional 2.5 MB MP3 file ready to listen
+- Mini-Book: An EPUB file with chapters and assessment questions
+
+### Generate in Different Languages
+
+```python
+# Hebrew podcast about Drones
+generate_podcast("Drones", api_key, "podcast_he.mp3", languages="he")
+
+# Spanish mini-book about Ancient Egypt
+create_minibook(api_key, "Ancient Egypt", language="es", output_format="epub")
+
+# French podcast about Dinosaurs
+generate_podcast("Dinosaurs", api_key, "podcast_fr.mp3", languages="fr")
+
+# Multilingual podcast (English, Spanish, French)
+generate_podcast("Space Exploration", api_key, languages="en,es,fr")
+```
+
+---
+
+## Architecture
+
+### Core Modules
+
+**[mindquest/studio.py](mindquest/studio.py)** - Main production engine with:
+
+```python
+create_script()             # Generate educational scripts from WikiKids
+parse_script_segments()     # Extract character dialogues
+voice_over()                # Synthesize audio from scripts
+extract_character_audio()   # Generate audio for specific characters
+generate_podcast()          # Complete end-to-end podcast production
+create_minibook()           # Generate EPUB/PDF mini-books with chapters
+_parse_minibook_markdown()  # Parse markdown into structured chapters
+_create_epub_file()         # Generate EPUB files
+_create_pdf_file()          # Generate PDF files
+```
+
+**[mindquest/utils/chatgpt.py](mindquest/utils/chatgpt.py)** - OpenAI integration:
+- Script generation via ChatGPT-4
+- Audio synthesis via OpenAI TTS API
+- Mini-book content generation via ChatGPT-4
+
+**[mindquest/utils/wikikids.py](mindquest/utils/wikikids.py)** - Content sourcing:
+- WikiKids API integration for age-appropriate facts
+- Information gathering and summarization
+
+**[mindquest/types.py](mindquest/types.py)** - Character profiles:
+- PLATO: Wise Professor (onyx voice - deep, calm)
+- PIXEL: Curious Child (shimmer voice - bright, energetic)
+
+---
+
+## API Reference
+
+### `generate_podcast()`
+
+Generate a complete educational podcast.
+
+```python
+generate_podcast(
+    topic: str,           # Educational topic (e.g., "Dinosaurs")
+    api_key: str,        # OpenAI API key
+    output_file: str = "podcast.mp3",  # Output MP3 file path
+    word_count: int = 700,              # Script length (700 ≈ 5 mins)
+    languages: str = "en"               # Language code(s)
+) -> str                 # Returns path to generated podcast
+```
+
+**Example:**
+```python
+path = generate_podcast("Space Exploration", api_key, "my_podcast.mp3")
+print(f"Podcast saved to: {path}")
+```
+
+### `create_script()`
+
+Generate just the podcast script (without audio).
+
+```python
+create_script(
+    api_key: str,
+    topic: str,
+    number_of_words: int = 500
+) -> str
+```
+
+### `voice_over()`
+
+Convert script to audio with character voices.
+
+```python
+voice_over(
+    api_key: str,
+    script: str,
+    languages: str = "en"
+) -> bytes
+```
+
+### `create_minibook()`
+
+Generate an educational mini-book in EPUB or PDF format.
+
+```python
+create_minibook(
+    api_key: str,                    # OpenAI API key
+    topic: str,                      # Educational topic
+    language: str = "en",            # Language code (e.g., "he", "es", "fr")
+    number_of_words: int = 2000,     # Target word count
+    output_format: str = "epub"      # Format: "epub" or "pdf"
+) -> str                             # Returns path to generated file
+```
+
+**Example:**
+```python
+# Generate Hebrew EPUB about FPV Drones
+file_path = create_minibook(
+    api_key=api_key,
+    topic="FPV Drones",
+    language="he",
+    output_format="epub"
+)
+print(f"Mini-book saved to: {file_path}")  # fpv_drones_he.epub
+```
+
+---
+
+## Quality Metrics
+
+✅ **Test Coverage:** 95.04% (57 comprehensive tests)  
+✅ **Code Quality:** 9.93/10 Pylint score  
+✅ **Testing Framework:** pytest with pure function tests  
+✅ **Type Hints:** Full type annotation coverage  
+✅ **Error Handling:** Comprehensive exception handling with descriptive messages  
+✅ **Pure Functions:** 90%+ pure functional code (no side effects)
+
+### Running Tests
+
+```bash
+# Run all tests
+python -m pytest tests/test_all.py -v
+
+# Run with coverage report
+python -m pytest tests/test_all.py --cov=mindquest --cov-report=term-missing
+
+# Full validation (formatting, linting, tests)
+./run.sh -local
+```
+
+---
+
+## Example Workflows
+
+### Workflow 1: Generate English Podcast
+
+```python
+from mindquest import generate_podcast
+import os
+
+api_key = os.getenv("OPENAI_API_KEY")
+generate_podcast("The Water Cycle", api_key, "water_cycle.mp3")
+```
+
+### Workflow 2: Extract Character Audio
+
+```python
+from mindquest import create_script, extract_character_audio
+import os
+
+api_key = os.getenv("OPENAI_API_KEY")
+
+# Create script
+script = create_script(api_key, "Ancient Rome", 600)
+
+# Generate only Plato's audio
+plato_audio = extract_character_audio(script, "Plato", api_key)
+
+with open("plato_only.mp3", "wb") as f:
+    f.write(plato_audio)
+```
+
+### Workflow 3: Custom Language with Specific Word Count
+
+```python
+from mindquest import generate_podcast
+import os
+
+api_key = os.getenv("OPENAI_API_KEY")
+
+# 3-minute French podcast (~420 words at 140 wpm)
+generate_podcast(
+    topic="Marie Curie",
+    api_key=api_key,
+    output_file="marie_curie_fr.mp3",
+    word_count=420,
+    languages="fr"
+)
+```
+
+### Workflow 4: Generate Multi-Format Educational Content
+
+```python
+from mindquest import generate_podcast, create_minibook
+import os
+
+api_key = os.getenv("OPENAI_API_KEY")
+topic = "The Water Cycle"
+language = "es"  # Spanish
+
+# Generate podcast for listening
+podcast_path = generate_podcast(
+    topic=topic,
+    api_key=api_key,
+    output_file="water_cycle_podcast.mp3",
+    languages=language
+)
+
+# Generate mini-book for reading
+ebook_path = create_minibook(
+    api_key=api_key,
+    topic=topic,
+    language=language,
+    output_format="epub"
+)
+
+print(f"Podcast: {podcast_path}")
+print(f"E-Book: {ebook_path}")
+```
+
+---
+
+## Technology Stack
+
+| Component | Technology |
+|-----------|-----------|
+| **Language** | Python 3.9+ |
+| **LLM** | OpenAI ChatGPT-4 |
+| **TTS** | OpenAI TTS API |
+| **Content** | WikiKids |
+| **Testing** | pytest, pytest-cov |
+| **Code Quality** | pylint, black, type hints |
+| **E-Book Format** | ebooklib, EPUB/PDF |
+| **Package Manager** | pip |
+
+---
+
+## File Structure
+
+```
+mindquest/
+├── __init__.py              # Package exports
+├── studio.py               # Main production engine (all functionality)
+├── types.py                # Character profile definitions
+└── utils/
+    ├── __init__.py
+    ├── chatgpt.py          # OpenAI API integration
+    └── wikikids.py         # WikiKids content sourcing
+
+tests/
+└── test_all.py             # 37 comprehensive tests
+
+docs/
+├── requirements.md         # Original requirements
+└── series/                 # Example podcast content
+
+requirements.txt            # Project dependencies
+README.md                   # This file
+```
+
+---
+
+## Dependencies
+
+- **openai** ≥1.0.0 - OpenAI API client
+- **requests** ≥2.31.0 - HTTP library for WikiKids
+- **beautifulsoup4** ≥4.12.0 - HTML parsing for content extraction
+- **ebooklib** ≥0.18 - EPUB file generation
+- **pypub** ≥1.1.0 - Additional EPUB support
+- **pytest** ≥7.4.0 - Testing framework
+- **pytest-cov** ≥4.1.0 - Coverage reporting
+- **black** - Code formatting
+- **pylint** - Code linting
+
+---
+
+## Environment Setup
+
+### Set OpenAI API Key
+
+```bash
+# macOS/Linux
+export OPENAI_API_KEY=your_actual_key_here
+
+# Windows (PowerShell)
+$env:OPENAI_API_KEY="your_actual_key_here"
+```
+
+### Verify Installation
+
+```bash
+python -c "from mindquest import generate_podcast; print('✅ MindQuest ready!')"
+```
+
+---
+
+## Features
+
+✨ **Automatic Content Generation**
+- End-to-end pipeline from topic to podcast MP3 or e-book
+- No manual script writing required
+- Real-time progress feedback
+
+🎙️ **Podcast Production**
+- Character-based dialogue generation
+- Natural voice synthesis with distinct voices
+- Multi-segment audio composition
+- Export to MP3 format
+
+📖 **Mini-Book Generation**
+- Structured chapters (7-10 per book)
+- Assessment questions (3 per chapter)
+- EPUB and PDF format support
+- Table of contents with chapter organization
+
+🎭 **Character-Based Learning**
+- Two distinct characters with different personalities
+- Natural dialogue flow for engagement
+- Character-specific voices (Plato: calm/explanatory, Pixel: energetic/curious)
+
+🌍 **Multilingual Support**
+- English, Spanish, French, German, Hebrew, Arabic, and more
+- Language parameter for both podcasts and mini-books
+- Compatible with OpenAI's TTS and GPT language support
+
+📚 **Educational Content**
+- WikiKids integration for age-appropriate information
+- Factual, verified content sources
+- Context-aware script and mini-book generation
+
+🔧 **Production-Grade Quality**
+- 95%+ test coverage (57 tests)
+- 9.93/10 code quality score
+- Full error handling and validation
+- Type hints throughout codebase
+- Pure functional programming paradigm
+
+---
+
+## Roadmap
+
+- [ ] Add support for multiple voice options per character
+- [ ] Implement audio concatenation for proper multi-segment synthesis
+- [ ] Add subtitle/transcript generation
+- [ ] Support for custom character profiles
+- [ ] Batch podcast generation API
+- [ ] Web UI for podcast creation
+- [ ] Distribution to podcast platforms (Spotify, Apple Podcasts)
+
+---
+
+## Contributing
+
+Contributions welcome! Please ensure:
+
+1. All tests pass: `python -m pytest tests/test_all.py`
+2. Coverage maintained: >95%
+3. Code formatted: `black mindquest/`
+4. Linting passes: `pylint mindquest/`
+
+---
+
+## License
+
+MIT License - See LICENSE file for details
+
+---
+
+## Acknowledgments
+
+- **WikiKids API** - Educational content source
+- **OpenAI** - ChatGPT and TTS APIs
+- **Children's Learning Research** - Pedagogical principles
+
+