🎨 Napkin AI API Playground

🛠️ Tech Stack

📊 Project Stats

🔧 Code Quality

🌟 Features

Transform text into stunning visuals with the power of AI ✨

🚀 Quick Start • ✨ Features • 📚 Documentation • 🎮 Demo • 🤝 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

# 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

# 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)

# 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

# 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:

# 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:

napkin generate "Neural Network" \
  --context-before "Introduction to" \
  --context-after "for beginners"

🔄 Visual Regeneration

Update existing visuals or search for specific types:

# 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:

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:

# 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 SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }}	Discord Integration DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
Email Alerts EMAIL_USERNAME: ${{ secrets.EMAIL_USERNAME }} EMAIL_PASSWORD: ${{ secrets.EMAIL_PASSWORD }}	GitHub Issues CREATE_GITHUB_ISSUE: true GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

📚 Documentation

Document	Description	Badge
📘 API Guide	Complete API reference & usage
📗 Project Guide	Development, testing & contributing
📙 Official API Docs	Napkin's official API documentation

🏗️ Architecture

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

Loading

📁 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

# 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:

# 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

📊 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 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

• Core API integration
• CLI with all parameters
• 16 styles support
• Async operations
• Comprehensive testing

✅ Phase 2: Web Interface

• Streamlit web application
• Interactive style browser
• Real-time generation
• Download functionality
• Multi-language support
• 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 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 file for details.

🙏 Acknowledgments

Napkin AI API	Poetry
Streamlit	Typer

📞 Support

📧 Email api@napkin.ai

🐛 Issues GitHub Issues

💬 Discussions GitHub Discussions

---

🌟 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