# ๐จ Napkin AI API Playground
### ๐ ๏ธ Tech Stack
### ๐ Project Stats
### ๐ง Code Quality
### ๐ Features
**Transform text into stunning visuals with the power of AI** โจ
[๐ Quick Start](#-quick-start) โข [โจ Features](#-features) โข [๐ Documentation](#-documentation) โข [๐ฎ Demo](#-demo) โข [๐ค Contributing](#-contributing)
---
## ๐ฏ What is Napkin AI API Playground?
A **production-ready** Python toolkit featuring both a **๐ Streamlit web interface** and **๐ป powerful CLI** that seamlessly transforms your text into professional-grade visuals using the Napkin AI API. Built with modern Python practices, robust error handling, intelligent retries, and comprehensive monitoring.
Interactive Web UI
|
Command Line Tool
|
Async Operations
|
Automated Testing
|
### ๐ฏ Perfect for:
- ๐ **Data Scientists** - Visualize complex concepts instantly
- ๐ฉโ๐ป **Developers** - Generate architecture diagrams from descriptions
- ๐ **Educators** - Create engaging visual content for teaching
- ๐ผ **Product Managers** - Quickly sketch out ideas and workflows
- ๐จ **Content Creators** - Transform text into beautiful graphics
## โจ Features
|
### ๐ Streamlit Web Interface
- **Interactive UI** with real-time generation
- **Live preview** of all visual styles
- **Multi-language support** (38 languages)
- **Advanced options** panel
- **Download manager** for all formats
- **Mobile-responsive** design
|
### ๐ป Powerful CLI
- **Full-featured** command line tool
- **Single visual generation**
- **JSON export** options
- **Rich terminal** output
- **Progress tracking** with spinners
- **Configuration management**
|
|
### ๐จ 16 Visual Styles
- **Vibrant** - Bold, energetic visuals
- **Sketch** - Hand-drawn aesthetics
- **Corporate** - Professional graphics
- **Minimalist** - Clean, simple designs
- **Comic** - Fun, playful style
- **And many more!**
|
### โก Advanced Features
- **Async API** with retry logic
- **Rate limiting** (60 req/min)
- **Error monitoring** dashboard
- **GitHub Actions** integration
- **Docker support**
- **Type-safe** with Pydantic v2
|
## ๐ Quick Start
### ๐ฆ Installation
```bash
# Clone the repository
git clone https://github.com/moshehbenavraham/Napkin-AI-API.git
cd Napkin-AI-API
# Install with Poetry (recommended)
poetry install
# Or use pip
pip install -r requirements.txt
```
### ๐ Configuration
```bash
# Copy example config
cp .env.example .env
# Add your API token (get one at https://napkin.ai)
echo "NAPKIN_API_TOKEN=your_token_here" >> .env
# Optional: Add GitHub token for error monitoring
echo "GITHUB_TOKEN=ghp_your_github_token" >> .env
```
### ๐ฎ Demo
#### ๐ Web Interface (Streamlit)
```bash
# Launch the web app
poetry run streamlit run streamlit_app.py
# Or with custom port
poetry run streamlit run streamlit_app.py --server.port 8080
# Access at http://localhost:8501
```
๐ธ Web Interface Screenshots
- Main generation interface
- Style browser with categories
- Multi-language support
- Advanced options panel
- Real-time generation
- Download manager
#### ๐ป Command Line Interface
```bash
# Generate your first visual
poetry run napkin generate "Machine Learning Pipeline"
# With specific style and format
poetry run napkin generate "Data Flow" --style sketch-notes --format png
# Multiple variations
poetry run napkin generate "System Architecture" --variations 4
# Export to JSON
poetry run napkin generate "Workflow" --json output.json
```
## ๐ ๏ธ Advanced Usage
### ๐ Multi-Language Support
Generate visuals in 38 languages using BCP 47 language tags:
```bash
# Spanish
napkin generate "Flujo de datos" --language es-ES
# Japanese
napkin generate "ใใผใฟใใญใผ" --language ja-JP
# Arabic
napkin generate "ุชุฏูู ุงูุจูุงูุงุช" --language ar
```
### ๐ฏ Context Options
Add context for more meaningful visuals:
```bash
napkin generate "Neural Network" \
--context-before "Introduction to" \
--context-after "for beginners"
```
### ๐ Visual Regeneration
Update existing visuals or search for specific types:
```bash
# Regenerate existing visual
napkin generate "Updated Content" --visual-id "5UCQJLAV5S6NXEWS2PBJF54UYPW5NZ4G"
# Search for specific visual type
napkin generate "Project Timeline" --visual-query "timeline"
```
### ๐ Custom Dimensions
For PNG format with specific dimensions:
```bash
napkin generate "Architecture" \
--format png \
--width 1920 \
--height 1080 \
--transparent \
--inverted-color
```
## ๐ CI/CD & Monitoring
### ๐ GitHub Actions Integration
Our project uses GitHub Actions for continuous integration with automated testing, linting, and deployment:
- **Python 3.10, 3.11, 3.12** matrix testing
- **Automated linting** with Ruff
- **Type checking** with MyPy
- **Security scanning** with Bandit
- **Coverage reporting** with Codecov
- **Automated notifications** on failure
### ๐ ๏ธ Built-in Monitoring Tool
Monitor your CI/CD pipeline with the unified `gh-monitor` tool:
```bash
# Monitor recent failures
bin/gh-monitor # Show last 5 failures
bin/gh-monitor 10 # Show last 10 failures
# Analyze failures in detail
bin/gh-monitor analyze # Detailed analysis with error messages
# Generate CI error reports
bin/gh-monitor report # JSON report with context
# Export and format options
bin/gh-monitor 20 --json failures.json # Export to JSON
bin/gh-monitor 10 --simple # Simple one-line format
```
### ๐ Automated Notifications
Configure automatic notifications for CI/CD failures:
|
**Slack Integration**
```yaml
SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }}
```
|
**Discord Integration**
```yaml
DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
```
|
|
**Email Alerts**
```yaml
EMAIL_USERNAME: ${{ secrets.EMAIL_USERNAME }}
EMAIL_PASSWORD: ${{ secrets.EMAIL_PASSWORD }}
```
|
**GitHub Issues**
```yaml
CREATE_GITHUB_ISSUE: true
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```
|
## ๐ Documentation
| Document | Description | Badge |
|----------|-------------|-------|
| ๐ [API Guide](docs/API_GUIDE.md) | Complete API reference & usage |  |
| ๐ [Project Guide](docs/PROJECT_GUIDE.md) | Development, testing & contributing |  |
| ๐ [Official API Docs](docs/napkin_official/NAPKIN_AI_API.md) | Napkin's official API documentation |  |
## ๐๏ธ Architecture
```mermaid
graph TD
A[๐ Web UI / ๐ป CLI] -->|Streamlit / Typer| B[โ๏ธ Core Generator]
B --> C[๐ API Client]
C -->|httpx + tenacity| D[โ๏ธ Napkin API]
B --> E[๐ Pydantic Models]
E --> F[โ
Type Validation]
B --> G[๐ Error Monitor]
G --> H[๐ GitHub Actions]
style A fill:#FF4B4B,stroke:#333,stroke-width:2px
style D fill:#4285F4,stroke:#333,stroke-width:2px
style H fill:#2088FF,stroke:#333,stroke-width:2px
```
๐ Project Structure
```
napkin-api-playground/
โโโ ๐ฑ streamlit_app.py # Web interface (650 lines)
โโโ ๐ main.py # CLI entry point
โโโ ๐ง bin/
โ โโโ gh-monitor # GitHub Actions monitoring tool
โโโ ๐ src/
โ โโโ ๐ api/ # Async API client & models
โ โโโ ๐ป cli/ # CLI commands & display
โ โโโ โ๏ธ core/ # Generation orchestration
โ โโโ ๐ง utils/ # Config & helpers
โโโ ๐งช tests/ # Test suite
โโโ ๐ docs/ # Complete documentation
โโโ ๐ scripts/ # Monitoring & utilities
โโโ ๐จ data/ # Generated visuals
```
## ๐งช Development
### ๐ฌ Testing & Quality
```bash
# Run all tests
poetry run pytest
# With coverage report
poetry run pytest --cov=src --cov-report=html
# Type checking
poetry run mypy src/
# Linting
poetry run ruff check src/
# Security scan
poetry run bandit -r src/
```
### ๐ GitHub Actions Monitoring
Monitor and analyze CI/CD failures with the unified monitoring tool:
```bash
# Show recent failures
bin/gh-monitor # Last 5 failures
bin/gh-monitor 10 # Last 10 failures
# Analyze failures in detail
bin/gh-monitor analyze
# Generate CI error report
bin/gh-monitor report
# Export to JSON
bin/gh-monitor 5 --json failures.json
# Simple one-line format
bin/gh-monitor 10 --simple
# See all options
bin/gh-monitor --help
```
๐ [Full documentation](docs/GH_MONITOR.md)
### ๐ Code Quality Metrics
Tests
|
Coverage
|
Type Safety
|
Linting
|
Security
|
## ๐ What's New in v0.3.2
### โจ Latest Features
- โ
**Production-ready** status with all tests passing
- โ
**Unified error monitoring** system
- โ
**Enhanced CI/CD** with automatic notifications
- โ
**Improved documentation** with badges
- โ
**Fixed all deprecation** warnings
- โ
**Python 3.10+** compatibility
### ๐จ Web Interface (v0.3.0)
- ๐ **38 languages** with BCP 47 tags
- ๐ **Context options** for better visuals
- ๐ฏ **Advanced settings** panel
- ๐ **Visual regeneration** feature
- ๐ **Visual type search**
- ๐ฑ **Mobile-responsive** design
## ๐ค Contributing
We love contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## ๐ Project Roadmap
### โ
Completed Phases
โ
Phase 1: Core MVP
- [x] Core API integration
- [x] CLI with all parameters
- [x] 16 styles support
- [x] Async operations
- [x] Comprehensive testing
โ
Phase 2: Web Interface
- [x] Streamlit web application
- [x] Interactive style browser
- [x] Real-time generation
- [x] Download functionality
- [x] Multi-language support
- [x] Advanced options panel
### ๐ง Upcoming Features
- [ ] **Phase 3: Batch Processing** - Process multiple visuals from CSV/JSON
- [ ] **Phase 4: Gallery Mode** - Local SQLite gallery with search
- [ ] **Phase 5: Custom Styles** - Create and save custom visual styles
- [ ] **Team Collaboration** - Share visuals with team members
- [ ] **Cloud Integration** - S3/GCS storage support
- [ ] **API Webhooks** - Real-time generation notifications
## ๐ Security
| ๐ Tokens Never Logged |
๐ก๏ธ .env Gitignored |
โ
Input Validation |
| ๐ HTTPS Only |
๐ Bearer Auth |
๐ Secure Headers |
See [SECURITY.md](docs/SECURITY.md) for full security practices.
## ๐ Troubleshooting
๐ป CLI Issues
| Issue | Solution |
|-------|----------|
| Rate limit errors | Client auto-retries with backoff (60 req/min limit) |
| File not found | Ensure output directory exists or use default `./data/visuals` |
| Token errors | Check `NAPKIN_API_TOKEN` in `.env` file |
๐ Web Interface Issues
| Issue | Solution |
|-------|----------|
| 403 Forbidden | Update to latest version (fixed in v0.2.1) |
| Pydantic errors | Update to latest version (fixed in v0.2.2) |
| Auth header required | Ensure API token is set correctly |
๐ง Development Issues
| Issue | Solution |
|-------|----------|
| Poetry lock errors | Run `poetry lock` to update |
| Type check failures | Run `poetry run mypy src/` |
| Test failures | Ensure `.env` has valid token |
## ๐ License
This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.
## ๐ Acknowledgments
## ๐ Support
---
### ๐ Star us on GitHub!
If you find this project useful, please consider giving it a star โญ
**Made with ๐จ and Python by the Napkin AI Community**
[โฌ Back to top](#-napkin-ai-api-playground)
