265 lines
9.0 KiB
Markdown
265 lines
9.0 KiB
Markdown
# Asset Tracking Implementation Guide
|
|
|
|
## Overview
|
|
|
|
This document describes the production-ready implementation of asset tracking across all ALwrity modules. The unified Content Asset Library automatically tracks all AI-generated content (images, videos, audio, text) for easy management and organization.
|
|
|
|
## Architecture
|
|
|
|
### Core Components
|
|
|
|
1. **Database Models** (`backend/models/content_asset_models.py`)
|
|
- `ContentAsset`: Main model for tracking assets
|
|
- `AssetCollection`: Collections/albums for organizing assets
|
|
- `AssetType`: Enum (text, image, video, audio)
|
|
- `AssetSource`: Enum (all ALwrity modules)
|
|
|
|
2. **Service Layer** (`backend/services/content_asset_service.py`)
|
|
- CRUD operations for assets
|
|
- Search, filter, pagination
|
|
- Usage tracking
|
|
|
|
3. **Utility Functions**
|
|
- `backend/utils/asset_tracker.py`: `save_asset_to_library()` helper
|
|
- `backend/utils/file_storage.py`: Robust file saving utilities
|
|
|
|
## Implementation Status
|
|
|
|
### ✅ Completed Integrations
|
|
|
|
#### 1. Story Writer (`backend/api/story_writer/router.py`)
|
|
- **Images**: Tracks all scene images with metadata
|
|
- **Audio**: Tracks all scene audio files with narration details
|
|
- **Videos**: Tracks individual scene videos and complete story videos
|
|
- **Location**: After generation in `/generate-images`, `/generate-audio`, `/generate-video`, `/generate-complete-video`
|
|
- **Metadata**: Includes prompts, scene numbers, providers, models, costs, status
|
|
|
|
#### 2. Image Studio (`backend/api/images.py`)
|
|
- **Image Generation**: Tracks all generated images
|
|
- **Image Editing**: Tracks all edited images
|
|
- **Location**: After generation in `/api/images/generate` and `/api/images/edit`
|
|
- **Features**:
|
|
- Robust file saving with validation
|
|
- Atomic file writes
|
|
- Proper error handling (non-blocking)
|
|
- File serving endpoint at `/api/images/image-studio/images/{filename}`
|
|
|
|
### 📝 Notes on Other Modules
|
|
|
|
#### Main Generation Services
|
|
- **Text Generation** (`main_text_generation.py`): Returns strings, not files. If text content needs tracking, save to `.txt` or `.md` files first.
|
|
- **Video Generation** (`main_video_generation.py`): Already integrated via Story Writer
|
|
- **Audio Generation** (`main_audio_generation.py`): Already integrated via Story Writer
|
|
|
|
#### Social Writers
|
|
- **LinkedIn Writer**: Generates text content (posts, articles). No file generation currently.
|
|
- **Facebook Writer**: Generates text content (posts, stories, reels). No file generation currently.
|
|
- **Blog Writer**: Generates blog content. May generate images in future.
|
|
|
|
**Note**: If these modules generate files in the future, follow the integration pattern below.
|
|
|
|
## Integration Pattern
|
|
|
|
### For Image Generation
|
|
|
|
```python
|
|
from utils.asset_tracker import save_asset_to_library
|
|
from utils.file_storage import save_file_safely, generate_unique_filename
|
|
from sqlalchemy.orm import Session
|
|
from pathlib import Path
|
|
|
|
# After successful image generation
|
|
try:
|
|
base_dir = Path(__file__).parent.parent
|
|
output_dir = base_dir / "module_images"
|
|
|
|
image_filename = generate_unique_filename(
|
|
prefix="img_prompt",
|
|
extension=".png",
|
|
include_uuid=True
|
|
)
|
|
|
|
# Save file safely
|
|
image_path, save_error = save_file_safely(
|
|
content=result.image_bytes,
|
|
directory=output_dir,
|
|
filename=image_filename,
|
|
max_file_size=50 * 1024 * 1024 # 50MB
|
|
)
|
|
|
|
if image_path and not save_error:
|
|
image_url = f"/api/module/images/{image_path.name}"
|
|
|
|
# Track in asset library (non-blocking)
|
|
try:
|
|
asset_id = save_asset_to_library(
|
|
db=db,
|
|
user_id=user_id,
|
|
asset_type="image",
|
|
source_module="module_name",
|
|
filename=image_path.name,
|
|
file_url=image_url,
|
|
file_path=str(image_path),
|
|
file_size=len(result.image_bytes),
|
|
mime_type="image/png",
|
|
title="Image Title",
|
|
description="Image description",
|
|
prompt=prompt,
|
|
tags=["tag1", "tag2"],
|
|
provider=result.provider,
|
|
model=result.model,
|
|
metadata={"status": "completed"}
|
|
)
|
|
logger.info(f"✅ Asset saved: ID={asset_id}")
|
|
except Exception as e:
|
|
logger.error(f"Asset tracking failed: {e}", exc_info=True)
|
|
# Don't fail the request
|
|
except Exception as e:
|
|
logger.error(f"File save failed: {e}", exc_info=True)
|
|
# Continue - base64 is still available
|
|
```
|
|
|
|
### For Video Generation
|
|
|
|
```python
|
|
# After successful video generation
|
|
try:
|
|
asset_id = save_asset_to_library(
|
|
db=db,
|
|
user_id=user_id,
|
|
asset_type="video",
|
|
source_module="module_name",
|
|
filename=video_filename,
|
|
file_url=video_url,
|
|
file_path=str(video_path),
|
|
file_size=file_size,
|
|
mime_type="video/mp4",
|
|
title="Video Title",
|
|
description="Video description",
|
|
prompt=prompt,
|
|
tags=["video", "tag"],
|
|
provider=provider,
|
|
model=model,
|
|
cost=cost,
|
|
metadata={"duration": duration, "status": "completed"}
|
|
)
|
|
except Exception as e:
|
|
logger.error(f"Asset tracking failed: {e}", exc_info=True)
|
|
```
|
|
|
|
### For Audio Generation
|
|
|
|
```python
|
|
# After successful audio generation
|
|
try:
|
|
asset_id = save_asset_to_library(
|
|
db=db,
|
|
user_id=user_id,
|
|
asset_type="audio",
|
|
source_module="module_name",
|
|
filename=audio_filename,
|
|
file_url=audio_url,
|
|
file_path=str(audio_path),
|
|
file_size=file_size,
|
|
mime_type="audio/mpeg",
|
|
title="Audio Title",
|
|
description="Audio description",
|
|
prompt=text,
|
|
tags=["audio", "tag"],
|
|
provider=provider,
|
|
model=model,
|
|
cost=cost,
|
|
metadata={"status": "completed"}
|
|
)
|
|
except Exception as e:
|
|
logger.error(f"Asset tracking failed: {e}", exc_info=True)
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
### 1. Error Handling
|
|
- **Always non-blocking**: Asset tracking failures should never break the main request
|
|
- **Log errors**: Use `logger.error()` with `exc_info=True` for debugging
|
|
- **Graceful degradation**: Continue with base64/file response even if tracking fails
|
|
|
|
### 2. File Management
|
|
- **Use `save_file_safely()`**: Handles validation, atomic writes, directory creation
|
|
- **Sanitize filenames**: Use `sanitize_filename()` to prevent path traversal
|
|
- **Unique filenames**: Use `generate_unique_filename()` with UUIDs
|
|
- **File size limits**: Enforce reasonable limits (50MB for images, 100MB for videos)
|
|
|
|
### 3. Database Sessions
|
|
- **Pass session explicitly**: Use `db: Session = Depends(get_db)` in endpoints
|
|
- **Handle session lifecycle**: Let FastAPI manage session cleanup
|
|
- **Background tasks**: Get new session in background tasks
|
|
|
|
### 4. Metadata
|
|
- **Rich metadata**: Include provider, model, dimensions, cost, status
|
|
- **Searchable tags**: Use consistent tag naming (e.g., "image_studio", "generated")
|
|
- **Status tracking**: Always include `"status": "completed"` in metadata
|
|
|
|
### 5. File URLs
|
|
- **Consistent patterns**: Use `/api/{module}/images/{filename}` format
|
|
- **Serving endpoints**: Create corresponding GET endpoints to serve files
|
|
- **Authentication**: Protect file serving endpoints with `get_current_user`
|
|
|
|
## File Storage Utilities
|
|
|
|
### `save_file_safely()`
|
|
- Validates file size
|
|
- Creates directories automatically
|
|
- Atomic writes (temp file + rename)
|
|
- Returns `(file_path, error_message)` tuple
|
|
|
|
### `sanitize_filename()`
|
|
- Removes dangerous characters
|
|
- Prevents path traversal
|
|
- Limits filename length
|
|
- Handles empty filenames
|
|
|
|
### `generate_unique_filename()`
|
|
- Creates unique filenames with UUIDs
|
|
- Sanitizes prefix
|
|
- Handles extensions properly
|
|
|
|
## Testing Checklist
|
|
|
|
- [ ] Images are saved to disk correctly
|
|
- [ ] Files are accessible via serving endpoints
|
|
- [ ] Asset tracking works (check database)
|
|
- [ ] Errors don't break main requests
|
|
- [ ] File size limits are enforced
|
|
- [ ] Filenames are sanitized properly
|
|
- [ ] Metadata is complete and accurate
|
|
- [ ] Asset Library UI displays assets correctly
|
|
|
|
## Future Enhancements
|
|
|
|
1. **Text Content Tracking**: Save text content as files when needed
|
|
2. **Batch Operations**: Track multiple assets in single transaction
|
|
3. **File Cleanup**: Automatic cleanup of orphaned files
|
|
4. **Storage Backends**: Support S3, GCS for production
|
|
5. **Thumbnail Generation**: Auto-generate thumbnails for videos/images
|
|
6. **Compression**: Compress large files before storage
|
|
|
|
## Troubleshooting
|
|
|
|
### Assets not appearing in library
|
|
1. Check database: `SELECT * FROM content_assets WHERE user_id = '...'`
|
|
2. Check logs for asset tracking errors
|
|
3. Verify `save_asset_to_library()` returns asset ID
|
|
4. Check file URLs are correct
|
|
|
|
### File serving fails
|
|
1. Verify file exists on disk
|
|
2. Check serving endpoint is registered
|
|
3. Verify authentication is working
|
|
4. Check file permissions
|
|
|
|
### Performance issues
|
|
1. Use background tasks for heavy operations
|
|
2. Batch database operations
|
|
3. Consider async file I/O for large files
|
|
4. Monitor database query performance
|
|
|