metaai-sdk 2.1.1__tar.gz → 2.2.1__tar.gz

{metaai_sdk-2.1.1 → metaai_sdk-2.2.1}/CHANGELOG.md

@@ -5,6 +5,85 @@ All notable changes to Meta AI Python SDK will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.1.0] - 2026-01-16
+
+### 🎉 Image Upload & Enhanced Features
+
+Major update adding comprehensive image upload support with analysis, generation, and video creation capabilities.
+
+### Added
+
+- 📤 **Image Upload Support** - Upload images for AI processing
+
+  - New `upload_image()` method in `MetaAI` class
+  - `ImageUploader` class using Meta's rupload protocol
+  - UUID-based upload session management
+  - Automatic MIME type detection and file size tracking
+  - Returns `media_id` for use in subsequent operations
+
+- 🔍 **Image Analysis** - Analyze and describe uploaded images
+
+  - Chat endpoint now accepts `media_ids` parameter
+  - Support for `attachment_metadata` (file_size, mime_type)
+  - Multi-step agent response parsing for detailed descriptions
+  - Entrypoint routing (KADABRA**DISCOVER**UNIFIED_INPUT_BAR)
+
+- 🎨 **Similar Image Generation** - Create variations of uploaded images
+
+  - Generate similar images in different styles
+  - Extract URLs from `content.imagine.session.media_sets`
+  - Support for 4 simultaneous image generations
+  - Fallback URL field checking (uri, image_uri, maybe_image_uri, url)
+
+- 🎬 **Video from Images** - Animate uploaded static images
+
+  - Video generation now accepts uploaded image media_ids
+  - Full `attachment_metadata` support
+  - Integration with existing `VideoGenerator` class
+
+- 🔧 **Response Parser Enhancements**
+
+  - Enhanced `format_response()` for multi-step agent responses
+  - Updated `extract_media()` with primary/fallback location checking
+  - Improved `extract_data()` with Kadabra structure support
+  - Added support for `XFBAbraMessageMultiStepResponseContent`
+
+- 📚 **Comprehensive Documentation**
+
+  - Complete image upload guide (`IMAGE_UPLOAD_README.md`)
+  - Updated quick usage guide (`QUICK_USAGE.md`)
+  - New complete workflow example (`examples/image_workflow_complete.py`)
+  - API reference with all three use cases
+  - Working curl and Python examples
+
+- 🧪 **Testing & Validation**
+  - Comprehensive test suite (`test_endpoints.py`)
+  - End-to-end workflow validation
+  - All features tested and confirmed working
+
+### Changed
+
+- ♻️ Enhanced `MetaAI.prompt()` to support image attachments
+- 🔄 Updated `MetaAI.generate_video()` with image support
+- 📖 Updated main README with image upload section
+- 🏗️ Refactored response parsing for better structure handling
+- 🎯 Improved entrypoint selection logic (ABRA vs KADABRA)
+
+### Fixed
+
+- 🐛 Fixed empty responses for chat with uploaded images
+- 🐛 Fixed None URLs in image generation responses
+- 🐛 Fixed response parsing for Kadabra structures
+- 🐛 Fixed media extraction from nested content structures
+
+### Technical Details
+
+- Uses Meta's rupload protocol for image uploads
+- Proper GraphQL mutation selection (useKadabraSendMessageMutation)
+- Correct doc_id routing (34429318783334028 for Kadabra)
+- messagePersistentInput with attachment_size (bytes) and attachment_type (MIME)
+- Multi-path response parsing (Abra and Kadabra structures)
+
 ## [2.0.0] - 2025-11-22
 
 ### 🎉 Initial Release

{metaai_sdk-2.1.1/src/metaai_sdk.egg-info → metaai_sdk-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metaai-sdk
-Version: 2.1.1
+Version: 2.2.1
 Summary: Feature-rich Python SDK for Meta AI - Chat, Image & Video Generation powered by Llama 3
 Home-page: https://github.com/mir-ashiq/metaai-api
 Author: Ashiq Hussain Mir
@@ -27,6 +27,7 @@ Requires-Dist: requests>=2.31.0
 Requires-Dist: requests-html>=0.10.0
 Requires-Dist: lxml-html-clean>=0.1.1
 Requires-Dist: beautifulsoup4>=4.9.0
+Requires-Dist: python-multipart>=0.0.21
 Provides-Extra: api
 Requires-Dist: fastapi<0.96.0,>=0.95.2; extra == "api"
 Requires-Dist: uvicorn[standard]<0.24.0,>=0.22.0; extra == "api"
@@ -95,16 +96,18 @@ All in one SDK
 
 ### 🌟 Core Capabilities
 
-| Feature                      | Description                                  | Status   |
-| ---------------------------- | -------------------------------------------- | -------- |
-| 💬 **Intelligent Chat**      | Powered by Llama 3 with internet access      | ✅ Ready |
-| 🎨 **Image Generation**      | Create stunning AI-generated images          | ✅ Ready |
-| 🎬 **Video Generation**      | Generate videos from text prompts            | ✅ Ready |
-| 🌐 **Real-time Data**        | Get current information via Bing integration | ✅ Ready |
-| 📚 **Source Citations**      | Responses include verifiable sources         | ✅ Ready |
-| 🔄 **Streaming Support**     | Real-time response streaming                 | ✅ Ready |
-| 🔐 **Auto Token Management** | Automatic authentication handling            | ✅ Ready |
-| 🌍 **Proxy Support**         | Route requests through proxies               | ✅ Ready |
+| Feature                      | Description                                      | Status   |
+| ---------------------------- | ------------------------------------------------ | -------- |
+| 💬 **Intelligent Chat**      | Powered by Llama 3 with internet access          | ✅ Ready |
+| 📤 **Image Upload**          | Upload & analyze images, generate similar images | ✅ Ready |
+| 🎨 **Image Generation**      | Create stunning AI-generated images              | ✅ Ready |
+| 🎬 **Video Generation**      | Generate videos from text or uploaded images     | ✅ Ready |
+| 🔍 **Image Analysis**        | Describe, analyze, and extract info from images  | ✅ Ready |
+| 🌐 **Real-time Data**        | Get current information via Bing integration     | ✅ Ready |
+| 📚 **Source Citations**      | Responses include verifiable sources             | ✅ Ready |
+| 🔄 **Streaming Support**     | Real-time response streaming                     | ✅ Ready |
+| 🔐 **Auto Token Management** | Automatic authentication handling                | ✅ Ready |
+| 🌍 **Proxy Support**         | Route requests through proxies                   | ✅ Ready |
 
 ---
 
@@ -333,8 +336,9 @@ uvicorn metaai_api.api_server:app --host 0.0.0.0 --port 8000
 
 | Endpoint               | Method | Description                            |
 | ---------------------- | ------ | -------------------------------------- |
-| `/chat`                | POST   | Send chat messages                     |
-| `/image`               | POST   | Generate images                        |
+| `/upload`              | POST   | Upload images for analysis/generation  |
+| `/chat`                | POST   | Send chat messages (with/without imgs) |
+| `/image`               | POST   | Generate images (from text or imgs)    |
 | `/video`               | POST   | Generate video (blocks until complete) |
 | `/video/async`         | POST   | Start async video generation           |
 | `/video/jobs/{job_id}` | GET    | Poll async job status                  |
@@ -516,6 +520,72 @@ if result["success"]:
 
 ---
 
+## 📤 Image Upload & Analysis
+
+Upload images to Meta AI for analysis, similar image generation, and video creation:
+
+### Upload & Analyze Images
+
+```python
+from metaai_api import MetaAI
+
+# Initialize with Facebook cookies (required for image operations)
+ai = MetaAI(cookies={
+    "datr": "your_datr_cookie",
+    "abra_sess": "your_abra_sess_cookie"
+})
+
+# Step 1: Upload an image
+result = ai.upload_image("path/to/image.jpg")
+
+if result["success"]:
+    media_id = result["media_id"]
+    metadata = {
+        'file_size': result['file_size'],
+        'mime_type': result['mime_type']
+    }
+
+    # Step 2: Analyze the image
+    response = ai.prompt(
+        message="What do you see in this image? Describe it in detail.",
+        media_ids=[media_id],
+        attachment_metadata=metadata
+    )
+    print(f"🔍 Analysis: {response['message']}")
+
+    # Step 3: Generate similar images
+    response = ai.prompt(
+        message="Create a similar image in watercolor painting style",
+        media_ids=[media_id],
+        attachment_metadata=metadata,
+        is_image_generation=True
+    )
+    print(f"🎨 Generated {len(response['media'])} similar images")
+
+    # Step 4: Generate video from image
+    video = ai.generate_video(
+        prompt="generate a video with zoom in effect on this image",
+        media_ids=[media_id],
+        attachment_metadata=metadata
+    )
+    if video["success"]:
+        print(f"🎬 Video: {video['video_urls'][0]}")
+```
+
+**Output:**
+
+```
+🔍 Analysis: The image captures a serene lake scene set against a majestic mountain backdrop. In the foreground, there's a small, golden-yellow wooden boat with a bright yellow canopy floating on calm, glass‑like water...
+
+🎨 Generated 4 similar images
+
+🎬 Video: https://scontent.fsxr1-2.fna.fbcdn.net/o1/v/t6/f2/m421/video.mp4
+```
+
+📖 **Full Image Upload Guide:** See [IMAGE_UPLOAD_README.md](IMAGE_UPLOAD_README.md) for complete documentation!
+
+---
+
 ## 🎨 Image Generation
 
 Generate AI-powered images (requires Facebook authentication):
@@ -559,11 +629,12 @@ for i, image in enumerate(response['media'], 1):
 
 Explore working examples in the `examples/` directory:
 
-| File                                                       | Description       | Features                          |
-| ---------------------------------------------------------- | ----------------- | --------------------------------- |
-| 📄 **[simple_example.py](examples/simple_example.py)**     | Quick start guide | Basic chat + video generation     |
-| 📄 **[video_generation.py](examples/video_generation.py)** | Video generation  | Multiple examples, error handling |
-| 📄 **[test_example.py](examples/test_example.py)**         | Testing suite     | Validation and testing            |
+| File                                                                     | Description             | Features                               |
+| ------------------------------------------------------------------------ | ----------------------- | -------------------------------------- |
+| 📄 **[image_workflow_complete.py](examples/image_workflow_complete.py)** | Complete image workflow | Upload, analyze, generate images/video |
+| 📄 **[simple_example.py](examples/simple_example.py)**                   | Quick start guide       | Basic chat + video generation          |
+| 📄 **[video_generation.py](examples/video_generation.py)**               | Video generation        | Multiple examples, error handling      |
+| 📄 **[test_example.py](examples/test_example.py)**                       | Testing suite           | Validation and testing                 |
 
 ### Run an Example
 
@@ -587,8 +658,10 @@ python examples/video_generation.py
 
 | Document                                                    | Description                             |
 | ----------------------------------------------------------- | --------------------------------------- |
+| 📘 **[Image Upload Guide](IMAGE_UPLOAD_README.md)**         | Complete image upload documentation     |
 | 📘 **[Video Generation Guide](VIDEO_GENERATION_README.md)** | Complete video generation documentation |
 | 📙 **[Quick Reference](QUICK_REFERENCE.md)**                | Fast lookup for common tasks            |
+| 📙 **[Quick Usage](QUICK_USAGE.md)**                        | Image upload quick reference            |
 | 📗 **[Architecture Guide](ARCHITECTURE.md)**                | Technical architecture details          |
 | 📕 **[Contributing Guide](CONTRIBUTING.md)**                | How to contribute to the project        |
 | 📔 **[Changelog](CHANGELOG.md)**                            | Version history and updates             |