Skip to content

Commit d831727

Browse files
moshehbenavrahammoshehbenavraham
committed
.
1 parent ed776c8 commit d831727

6 files changed

Lines changed: 735 additions & 78 deletions

File tree

‎README.md‎

Lines changed: 32 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
![Python](https://img.shields.io/badge/python-3.10%2B-blue?style=for-the-badge&logo=python&logoColor=white)
66
![Poetry](https://img.shields.io/badge/Poetry-2.0%2B-60A5FA?style=for-the-badge&logo=poetry&logoColor=white)
77
![License](https://img.shields.io/badge/license-MIT-green?style=for-the-badge)
8-
![Version](https://img.shields.io/badge/version-0.1.3-purple?style=for-the-badge)
8+
![Version](https://img.shields.io/badge/version-0.2.1-purple?style=for-the-badge)
99
![Status](https://img.shields.io/badge/status-MVP%20Complete-success?style=for-the-badge)
1010

1111
**Transform text into stunning visuals with the power of AI** ✨
@@ -302,11 +302,13 @@ We love contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guideli
302302
- [x] Async operations
303303
- [x] Comprehensive testing
304304

305-
### ✅ Phase 2: Web Interface (Complete)
305+
### ✅ Phase 2: Web Interface (Complete - v0.2.1)
306306
- [x] Streamlit web application
307307
- [x] Interactive style browser
308308
- [x] Real-time visual generation
309309
- [x] Download functionality
310+
- [x] Authenticated file downloads
311+
- [x] Error handling and recovery
310312

311313
### 🚧 Phase 3: Enhanced Features (Coming Soon)
312314
- [ ] Batch processing
@@ -324,9 +326,37 @@ We love contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guideli
324326
- 🛡️ `.env` files are gitignored by default
325327
- ✅ Input validation on all parameters
326328
- 🔄 Secure HTTPS communication only
329+
- 🔑 Authenticated file downloads with Bearer tokens
330+
- 🌐 Web interface supports environment-based token configuration
327331

328332
See [SECURITY.md](docs/SECURITY.md) for full security practices.
329333

334+
## 🐛 Troubleshooting
335+
336+
### Web Interface Issues
337+
338+
**403 Forbidden errors when viewing generated images**
339+
- Fixed in v0.2.1 - update to latest version
340+
- The app now properly authenticates file download requests
341+
342+
**"Authorization header is required" error**
343+
- Ensure your API token is correctly set
344+
- Check that NAPKIN_API_TOKEN environment variable is exported
345+
346+
**Dependabot Python version errors**
347+
- Fixed in v0.2.1 - Python requirement simplified to ^3.10
348+
- Dependabot now properly parses the version constraint
349+
350+
### CLI Issues
351+
352+
**Rate limit errors**
353+
- The client automatically retries with exponential backoff
354+
- Default: 60 requests/minute limit
355+
356+
**File not found errors**
357+
- Ensure output directory exists or use default `./data/visuals`
358+
- Check file permissions
359+
330360
## 📄 License
331361

332362
This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.

‎docs/CHANGELOG.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,24 @@
33
All notable changes to this project are documented in this file.
44
The format follows Keep a Changelog, and the project aims to follow Semantic Versioning.
55

6+
## [0.2.1] - 2025-08-07
7+
8+
### Fixed
9+
- 🔐 **Fixed Authorization Issue** - Resolved 403 Forbidden errors when fetching generated visuals
10+
- Added Bearer token authentication to image fetch requests
11+
- Implemented pre-download mechanism in worker thread for API endpoints
12+
- Properly parse and handle file download URLs that require authentication
13+
- Added fallback handling for both direct CDN URLs and authenticated API endpoints
14+
- Fixed duplicate import statements and moved all imports to top of file
15+
- Fixed bare except clause to use specific Exception handling
16+
- Applied proper code formatting with ruff
17+
18+
### Improved
19+
- Enhanced error handling with try-catch blocks for file downloads
20+
- Better file URL extraction with support for multiple response formats
21+
- Added version info display with git commit hash in footer
22+
- Improved file_id parsing to handle suffixes properly
23+
624
## [0.2.0] - 2025-08-07
725

826
### Added

‎docs/STREAMLIT_DEPLOYMENT.md‎

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
# Streamlit Cloud Deployment Guide
2+
3+
This guide covers deploying the Napkin AI Visual Generator web interface to Streamlit Cloud.
4+
5+
## Prerequisites
6+
7+
- GitHub account with repository access
8+
- Napkin AI API token
9+
- Python 3.10+ locally for testing
10+
11+
## Local Testing
12+
13+
Before deploying, test the app locally:
14+
15+
```bash
16+
# Install dependencies
17+
poetry install
18+
19+
# Set environment variable (optional, can use UI input)
20+
export NAPKIN_API_TOKEN="your-token-here"
21+
22+
# Run the app
23+
poetry run streamlit run streamlit_app.py
24+
25+
# Open in browser
26+
# http://localhost:8501
27+
```
28+
29+
## Deployment Steps
30+
31+
### 1. Prepare Your Repository
32+
33+
Ensure these files are in your repository:
34+
- `streamlit_app.py` - Main application file
35+
- `pyproject.toml` - Poetry dependencies (Streamlit Cloud supports Poetry)
36+
- `.streamlit/config.toml` - App configuration
37+
38+
### 2. Create Streamlit Cloud Account
39+
40+
1. Go to [share.streamlit.io](https://share.streamlit.io)
41+
2. Sign up with GitHub
42+
3. Authorize Streamlit to access your repositories
43+
44+
### 3. Deploy Your App
45+
46+
1. Click **"New app"** in Streamlit Cloud dashboard
47+
2. Select your repository and branch
48+
3. Set **Main file path**: `streamlit_app.py`
49+
4. Open **Advanced settings**
50+
51+
### 4. Configure Secrets
52+
53+
In Advanced settings, add your secrets in TOML format:
54+
55+
```toml
56+
# Required
57+
NAPKIN_API_TOKEN = "your-actual-napkin-api-token"
58+
59+
# Optional defaults
60+
[defaults]
61+
style = "vibrant-strokes"
62+
format = "svg"
63+
variations = 1
64+
```
65+
66+
**Important**: Never commit secrets to your repository!
67+
68+
### 5. Python Version
69+
70+
In Advanced settings, set:
71+
- **Python version**: `3.10`
72+
73+
### 6. Deploy
74+
75+
Click **Deploy!** Your app will be available at:
76+
```
77+
https://[your-app-name].streamlit.app
78+
```
79+
80+
## Post-Deployment
81+
82+
### Viewing Logs
83+
84+
1. Go to your app in Streamlit Cloud dashboard
85+
2. Click **"Manage app"**
86+
3. Select **"Logs"** to view deployment and runtime logs
87+
88+
### Updating the App
89+
90+
The app auto-deploys when you push to the configured branch:
91+
92+
```bash
93+
# Make changes locally
94+
git add .
95+
git commit -m "Update streamlit app"
96+
git push origin main
97+
```
98+
99+
### Monitoring
100+
101+
Check the footer of your deployed app for:
102+
- Version number (currently v0.2.1)
103+
- Git commit hash
104+
- Last update timestamp
105+
106+
## Configuration
107+
108+
### Environment Variables
109+
110+
The app supports these environment variables:
111+
112+
| Variable | Description | Required |
113+
|----------|-------------|----------|
114+
| `NAPKIN_API_TOKEN` | Your Napkin AI API token | Yes* |
115+
116+
*Can be entered via UI if not set in environment
117+
118+
### Custom Theme
119+
120+
Edit `.streamlit/config.toml` to customize appearance:
121+
122+
```toml
123+
[theme]
124+
primaryColor = "#FF6B6B"
125+
backgroundColor = "#FFFFFF"
126+
secondaryBackgroundColor = "#F0F2F6"
127+
textColor = "#262730"
128+
font = "sans serif"
129+
```
130+
131+
## Troubleshooting
132+
133+
### App Won't Start
134+
135+
1. Check Python version is 3.10+
136+
2. Verify all dependencies in `pyproject.toml`
137+
3. Check logs for import errors
138+
139+
### 403 Forbidden Errors
140+
141+
This was fixed in v0.2.1. The app now:
142+
- Adds Bearer token authentication to API requests
143+
- Pre-downloads files in worker thread
144+
- Handles both CDN URLs and authenticated endpoints
145+
146+
### Memory Issues
147+
148+
If you encounter memory errors:
149+
1. Reduce image dimensions (PNG)
150+
2. Generate fewer variations
151+
3. Use SVG format when possible
152+
153+
### Slow Generation
154+
155+
- Check Napkin AI service status
156+
- Verify network connectivity
157+
- Consider reducing variations
158+
159+
## Security Best Practices
160+
161+
1. **Never commit API tokens** to your repository
162+
2. **Use Streamlit secrets** for sensitive data
163+
3. **Rotate tokens regularly**
164+
4. **Monitor usage** in your Napkin AI dashboard
165+
5. **Set spending limits** if available
166+
167+
## Advanced Configuration
168+
169+
### Custom Domain
170+
171+
Streamlit Cloud supports custom domains (Pro plan):
172+
1. Go to app settings
173+
2. Add your domain
174+
3. Configure DNS CNAME
175+
176+
### Analytics
177+
178+
Add analytics by modifying `streamlit_app.py`:
179+
180+
```python
181+
# Google Analytics example
182+
st.markdown('''
183+
<script async src="https://www.googletagmanager.com/gtag/js?id=GA_ID"></script>
184+
<script>
185+
window.dataLayer = window.dataLayer || [];
186+
function gtag(){dataLayer.push(arguments);}
187+
gtag('js', new Date());
188+
gtag('config', 'GA_ID');
189+
</script>
190+
''', unsafe_allow_html=True)
191+
```
192+
193+
### Caching
194+
195+
Implement caching for better performance:
196+
197+
```python
198+
@st.cache_data(ttl=3600)
199+
def get_cached_styles():
200+
return STYLES
201+
```
202+
203+
## Support
204+
205+
- **Streamlit Issues**: [Streamlit Community](https://discuss.streamlit.io)
206+
- **Napkin AI Issues**: api@napkin.ai
207+
- **App Issues**: [GitHub Issues](https://github.com/yourusername/napkin-api-playground/issues)
208+
209+
## Version History
210+
211+
- **v0.2.1** - Fixed authentication issues, improved error handling
212+
- **v0.2.0** - Initial Streamlit web interface
213+
- **v0.1.x** - CLI only versions
214+
215+
---
216+
217+
Last updated: 2025-08-07

0 commit comments

Comments
 (0)