nomadicml 0.0.1__tar.gz

nomadicml-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 NomadicML
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nomadicml-0.0.1/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE
+include README.md
+include requirements.txt
+recursive-include examples *.py

nomadicml-0.0.1/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.1
+Name: nomadicml
+Version: 0.0.1
+Summary: Python SDK for NomadicML's DriveMonitor API
+Author: NomadicML Inc
+Author-email: info@nomadicml.com
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+License-File: LICENSE
+
+# NomadicML Python SDK
+
+A Python client library for the NomadicML DriveMonitor API, allowing you to upload and analyze driving videos programmatically.
+
+## Installation
+
+### From PyPI (for users)
+
+```bash
+pip install nomadicml
+```
+
+### For Development (from source)
+
+To install the package in development mode, where changes to the code will be immediately reflected without reinstallation:
+
+```bash
+# Clone the repository
+git clone https://github.com/nomadic-ml/drivemonitor.git
+cd sdk
+
+# For development: Install in editable mode
+pip install -e .
+```
+
+With this installation, any changes you make to the code will be immediately available when you import the package.
+
+## Quick Start
+
+```python
+from nomadicml import NomadicML
+
+# Initialize the client with your API key
+client = NomadicML(api_key="your_api_key")
+
+# Upload a video and analyze it in one step
+result = client.video.upload_and_analyze("path/to/your/video.mp4")
+
+# Print the detected events
+for event in result["events"]:
+    print(f"Event: {event['type']} at {event['time']}s - {event['description']}")
+#For a batch upload
+
+videos_list = [.....]#list of video paths
+batch_results = client.video.upload_and_analyze_videos(videos_list, wait_for_completion=False)
+
+    
+video_ids = [
+    res.get("video_id")
+    for res in batch_results
+    if res                                         # safety for None
+    ]
+
+    
+full_results = client.video.wait_for_analyses(video_ids)
+
+```
+
+## Authentication
+
+You need an API key to use the NomadicML API. You can get one by:
+
+1. Log in to your DriveMonitor account
+2. Go to Profile > API Key
+3. Generate a new API key
+
+Then use this key when initializing the client:
+
+```python
+client = NomadicML(api_key="your_api_key")
+```
+
+## Video Upload and Analysis
+
+### Upload a video
+
+```python
+# Upload a local video file
+result = client.video.upload_video(
+    source="file",
+    file_path="path/to/video.mp4"
+)
+
+# Or upload from YouTube
+result = client.video.upload_video(
+    source="youtube",
+    youtube_url="https://www.youtube.com/watch?v=VIDEO_ID"
+)
+
+# Get the video ID from the response
+video_id = result["video_id"]
+```
+
+### Analyze a video
+
+```python
+# Start analysis
+client.video.analyze_video(video_id)
+
+# Wait for analysis to complete
+status = client.video.wait_for_analysis(video_id)
+
+# Get analysis results
+analysis = client.video.get_video_analysis(video_id)
+
+# Get detected events
+events = client.video.get_video_events(video_id)
+```
+
+### Upload and analyze in one step
+
+```python
+# Upload and analyze a video, waiting for results
+analysis = client.video.upload_and_analyze("path/to/video.mp4")
+
+# Or just start the process without waiting
+result = client.video.upload_and_analyze("path/to/video.mp4", wait_for_completion=False)
+```
+
+## Advanced Usage
+
+### Filter events by severity or type
+
+```python
+# Get only high severity events
+high_severity_events = client.video.get_video_events(
+    video_id=video_id,
+    severity="high"
+)
+
+# Get only traffic violation events
+traffic_violations = client.video.get_video_events(
+    video_id=video_id,
+    event_type="Traffic Violation"
+)
+```
+
+### Custom timeout and polling interval
+
+```python
+# Wait for analysis with a custom timeout and polling interval
+client.video.wait_for_analysis(
+    video_id=video_id,
+    timeout=1200,  # 20 minutes
+    poll_interval=10  # Check every 10 seconds
+)
+```
+
+### Custom API endpoint
+
+If you're using a custom deployment of the DriveMonitor backend:
+
+```python
+# Connect to a local or custom deployment
+client = NomadicML(
+    api_key="your_api_key",
+    base_url="http://localhost:8099"
+)
+```
+
+## Error Handling
+
+The SDK provides specific exceptions for different error types:
+
+```python
+from nomadicml import NomadicMLError, AuthenticationError, VideoUploadError
+
+try:
+    client.video.upload_and_analyze("path/to/video.mp4")
+except AuthenticationError:
+    print("API key is invalid or expired")
+except VideoUploadError as e:
+    print(f"Failed to upload video: {e}")
+except NomadicMLError as e:
+    print(f"An error occurred: {e}")
+```
+
+## Development
+
+### Setup
+
+Clone the repository and install development dependencies:
+
+```bash
+git clone https://github.com/nomadicml/nomadicml-python.git
+cd nomadicml-python
+pip install -e ".[dev]"
+```
+
+### Running tests
+
+```bash
+pytest
+```
+
+## License
+
+MIT License. See LICENSE file for details.

nomadicml-0.0.1/README.md

@@ -0,0 +1,198 @@
+# NomadicML Python SDK
+
+A Python client library for the NomadicML DriveMonitor API, allowing you to upload and analyze driving videos programmatically.
+
+## Installation
+
+### From PyPI (for users)
+
+```bash
+pip install nomadicml
+```
+
+### For Development (from source)
+
+To install the package in development mode, where changes to the code will be immediately reflected without reinstallation:
+
+```bash
+# Clone the repository
+git clone https://github.com/nomadic-ml/drivemonitor.git
+cd sdk
+
+# For development: Install in editable mode
+pip install -e .
+```
+
+With this installation, any changes you make to the code will be immediately available when you import the package.
+
+## Quick Start
+
+```python
+from nomadicml import NomadicML
+
+# Initialize the client with your API key
+client = NomadicML(api_key="your_api_key")
+
+# Upload a video and analyze it in one step
+result = client.video.upload_and_analyze("path/to/your/video.mp4")
+
+# Print the detected events
+for event in result["events"]:
+    print(f"Event: {event['type']} at {event['time']}s - {event['description']}")
+#For a batch upload
+
+videos_list = [.....]#list of video paths
+batch_results = client.video.upload_and_analyze_videos(videos_list, wait_for_completion=False)
+
+    
+video_ids = [
+    res.get("video_id")
+    for res in batch_results
+    if res                                         # safety for None
+    ]
+
+    
+full_results = client.video.wait_for_analyses(video_ids)
+
+```
+
+## Authentication
+
+You need an API key to use the NomadicML API. You can get one by:
+
+1. Log in to your DriveMonitor account
+2. Go to Profile > API Key
+3. Generate a new API key
+
+Then use this key when initializing the client:
+
+```python
+client = NomadicML(api_key="your_api_key")
+```
+
+## Video Upload and Analysis
+
+### Upload a video
+
+```python
+# Upload a local video file
+result = client.video.upload_video(
+    source="file",
+    file_path="path/to/video.mp4"
+)
+
+# Or upload from YouTube
+result = client.video.upload_video(
+    source="youtube",
+    youtube_url="https://www.youtube.com/watch?v=VIDEO_ID"
+)
+
+# Get the video ID from the response
+video_id = result["video_id"]
+```
+
+### Analyze a video
+
+```python
+# Start analysis
+client.video.analyze_video(video_id)
+
+# Wait for analysis to complete
+status = client.video.wait_for_analysis(video_id)
+
+# Get analysis results
+analysis = client.video.get_video_analysis(video_id)
+
+# Get detected events
+events = client.video.get_video_events(video_id)
+```
+
+### Upload and analyze in one step
+
+```python
+# Upload and analyze a video, waiting for results
+analysis = client.video.upload_and_analyze("path/to/video.mp4")
+
+# Or just start the process without waiting
+result = client.video.upload_and_analyze("path/to/video.mp4", wait_for_completion=False)
+```
+
+## Advanced Usage
+
+### Filter events by severity or type
+
+```python
+# Get only high severity events
+high_severity_events = client.video.get_video_events(
+    video_id=video_id,
+    severity="high"
+)
+
+# Get only traffic violation events
+traffic_violations = client.video.get_video_events(
+    video_id=video_id,
+    event_type="Traffic Violation"
+)
+```
+
+### Custom timeout and polling interval
+
+```python
+# Wait for analysis with a custom timeout and polling interval
+client.video.wait_for_analysis(
+    video_id=video_id,
+    timeout=1200,  # 20 minutes
+    poll_interval=10  # Check every 10 seconds
+)
+```
+
+### Custom API endpoint
+
+If you're using a custom deployment of the DriveMonitor backend:
+
+```python
+# Connect to a local or custom deployment
+client = NomadicML(
+    api_key="your_api_key",
+    base_url="http://localhost:8099"
+)
+```
+
+## Error Handling
+
+The SDK provides specific exceptions for different error types:
+
+```python
+from nomadicml import NomadicMLError, AuthenticationError, VideoUploadError
+
+try:
+    client.video.upload_and_analyze("path/to/video.mp4")
+except AuthenticationError:
+    print("API key is invalid or expired")
+except VideoUploadError as e:
+    print(f"Failed to upload video: {e}")
+except NomadicMLError as e:
+    print(f"An error occurred: {e}")
+```
+
+## Development
+
+### Setup
+
+Clone the repository and install development dependencies:
+
+```bash
+git clone https://github.com/nomadicml/nomadicml-python.git
+cd nomadicml-python
+pip install -e ".[dev]"
+```
+
+### Running tests
+
+```bash
+pytest
+```
+
+## License
+
+MIT License. See LICENSE file for details.

nomadicml-0.0.1/examples/basic_usage.py

@@ -0,0 +1,226 @@
+"""
+Basic usage examples for the NomadicML SDK.
+"""
+
+import os
+import logging
+from nomadicml import NomadicML
+
+# Set up logging to see progress information
+logging.basicConfig(level=logging.INFO)
+
+# Get API key from environment variable or input
+API_KEY = os.environ.get("NOMADICML_API_KEY") or input("Enter your NomadicML API key: ")
+
+# Path to a video file for testing
+VIDEO_PATH = os.environ.get("VIDEO_PATH") or input("Enter path to a video file: ")
+
+# Initialize the client with your API key
+# Add base_url for development use
+# Change collection_name to "videos" for production use
+client = NomadicML(api_key=API_KEY, collection_name="videos_dev")
+
+def verify_authentication():
+    """
+    Verify that the API key is valid.
+    """
+    print("\n=== Verifying Authentication ===")
+    try:
+        # Verify authentication
+        auth_info = client.verify_auth()
+        print(f"Authentication successful: {auth_info}")
+        return True
+    except Exception as e:
+        print(f"Authentication failed due to error: {e}")
+        return False
+
+def upload_video():
+    """
+    Upload a video file to the DriveMonitor API.
+    """
+    print("\n=== Uploading Video ===")
+    try:
+        # Upload the video
+        result = client.video.upload_video(
+            source="file",
+            file_path=VIDEO_PATH
+        )
+        video_id = result["video_id"]
+        print(f"Video uploaded successfully. ID: {video_id}")
+        return video_id
+    except Exception as e:
+        print(f"Video upload failed: {e}")
+        return None
+
+def analyze_video(video_id):
+    """
+    Start analysis for the uploaded video.
+    """
+    print("\n=== Starting Video Analysis ===")
+    try:
+        # Start analysis
+        result = client.video.analyze_video(video_id)
+        print(f"Analysis started: {result}")
+        return True
+    except Exception as e:
+        print(f"Failed to start analysis: {e}")
+        return False
+
+def check_status(video_id):
+    """
+    Check the status of the video analysis.
+    """
+    print("\n=== Checking Video Status ===")
+    try:
+        # Get the status
+        status = client.video.get_video_status(video_id)
+        print(f"Current status: {status}")
+        return status
+    except Exception as e:
+        print(f"Failed to get status: {e}")
+        return None
+
+def wait_for_completion(video_id):
+    """
+    Wait for the video analysis to complete.
+    """
+    print("\n=== Waiting for Analysis to Complete ===")
+    try:
+        # Wait for completion with a shorter timeout for the example
+        final_status = client.video.wait_for_analysis(video_id, timeout=180)
+        print(f"Analysis completed: {final_status.get('status', 'Unknown')}")
+        return True
+    except Exception as e:
+        print(f"Error waiting for completion: {e}")
+        return False
+
+def get_results(video_id):
+    """
+    Get the full analysis results.
+    """
+    print("\n=== Getting Analysis Results ===")
+    try:
+        # Get the analysis
+        analysis = client.video.get_video_analysis(video_id)
+        print(f"Analysis summary:")
+        
+        # Print metadata if available
+        if "metadata" in analysis:
+            metadata = analysis["metadata"]
+            print(f"  Video: {metadata.get('filename', 'Unknown')}")
+            if "duration" in metadata:
+                print(f"  Duration: {metadata['duration']:.2f} seconds")
+            if "width" in metadata and "height" in metadata:
+                print(f"  Resolution: {metadata['width']}x{metadata['height']}")
+        
+        # Print events if available
+        if "events" in analysis and analysis["events"]:
+            print(f"\nDetected events ({len(analysis['events'])}):")
+        else:
+            print("\nNo events detected.")
+            
+        return analysis
+    except Exception as e:
+        print(f"Failed to get analysis results: {e}")
+        return None
+
+def upload_and_analyze_in_one_step(return_subset: bool = True):
+    """
+    Upload and analyze a video in one operation.
+    """
+    print("\n=== Upload and Analyze in One Step ===")
+    try:
+        # Upload and analyze with a shorter timeout for the example
+        analysis = client.video.upload_and_analyze(
+            file_path=VIDEO_PATH,
+            timeout=180,
+            return_subset=return_subset
+        )
+        print(f"Upload and analysis completed successfully.")
+        
+        # Print a summary of the results
+        if hasattr(analysis, 'visual_analysis') and analysis.visual_analysis and hasattr(analysis.visual_analysis, 'events') and analysis.visual_analysis.events:
+            print(f"\nDetected {len(analysis.visual_analysis.events)} events.")
+        elif isinstance(analysis, dict) and "events" in analysis and analysis["events"]: # Keep compatibility if return_subset=False
+            print(f"\nDetected {len(analysis['events'])} events.")
+        else:
+            print("\nNo events detected.")
+            
+        return analysis
+    except Exception as e:
+        print(f"Upload and analyze failed: {e}")
+        return None
+
+def main():
+    """
+    Run the examples.
+    """
+    print("=== NomadicML SDK Basic Usage Example ===")
+    
+    # Verify authentication
+    if not verify_authentication():
+        print("Exiting due to authentication failure.")
+        return
+    
+    # Ask which example to run
+    print("\nChoose an example to run:")
+    print("1. Step-by-step (upload, analyze, get results)")
+    print("2. All-in-one (upload and analyze in one step)")
+    print("3. Only upload video")
+    print("4. Only analyze video")
+    
+    choice = input("Enter your choice (1, 2, 3 or 4): ").strip()
+    
+    if choice == "1":
+        # Step-by-step example
+        video_id = upload_video()
+        if not video_id:
+            print("Exiting due to upload failure.")
+            return
+            
+        if not analyze_video(video_id):
+            print("Exiting due to analysis startup failure.")
+            return
+            
+        status = check_status(video_id)
+        if not status:
+            print("Exiting due to status check failure.")
+            return
+            
+        if not wait_for_completion(video_id):
+            print("Exiting due to timeout or error while waiting for completion.")
+            return
+            
+        results = get_results(video_id)
+        if not results:
+            print("Exiting due to failure getting results.")
+            return
+    
+    elif choice == "2":
+        # All-in-one example
+        results = upload_and_analyze_in_one_step()
+        if not results:
+            print("Exiting due to upload and analyze failure.")
+            return
+    elif choice == "3":
+        # Only upload video
+        print("\n=== Only Uploading Video ===")
+        video_id = upload_video()
+        if not video_id:
+            print("Exiting due to upload failure.")
+            return
+    elif choice == "4":
+        # Only analyze video
+        print("\n=== Only Analyzing Video ===")
+        video_id = input("Enter the video ID to analyze: ")
+        if not analyze_video(video_id):
+            print("Exiting due to analysis startup failure.")
+            return
+    else:
+        print("Invalid choice. Exiting.")
+        return
+    
+    print("\n=== Example Completed Successfully ===")
+
+if __name__ == "__main__":
+    main()

nomadicml-0.0.1/nomadicml/__init__.py

@@ -0,0 +1,42 @@
+"""
+NomadicML Python SDK for the DriveMonitor API.
+
+This SDK provides a simple interface to interact with the 
+DriveMonitor backend for analyzing driving videos.
+"""
+
+__version__ = "0.1.0"
+
+from .client import NomadicML
+from .video import VideoClient
+from .exceptions import NomadicMLError, AuthenticationError, APIError, VideoUploadError, AnalysisError
+from .types import VideoSource, ProcessingStatus, Severity, convert_to_upload_analyze_response_subset
+
+# Add video client to NomadicML
+def _add_video_client(client):
+    client.video = VideoClient(client)
+    return client
+
+# Patch the NomadicML class
+_original_init = NomadicML.__init__
+
+def _patched_init(self, *args, **kwargs):
+    _original_init(self, *args, **kwargs)
+    _add_video_client(self)
+
+NomadicML.__init__ = _patched_init
+
+__all__ = [
+    "NomadicML",
+    "VideoClient",
+    "NomadicMLError",
+    "AuthenticationError",
+    "APIError",
+    "VideoUploadError",
+    "AnalysisError",
+    "VideoSource",
+    "ProcessingStatus",
+    "EventType",
+    "Severity",
+    "convert_to_upload_analyze_response_subset",
+]