humalab 0.0.4__py3-none-any.whl → 0.0.5__py3-none-any.whl

humalab/humalab_api_client.py

@@ -114,11 +114,23 @@ class HumaLabApiClient:
     def delete(self, endpoint: str, **kwargs) -> requests.Response:
         """Make a DELETE request."""
         return self._make_request("DELETE", endpoint, **kwargs)
-    
+
+    # User Authentication API methods
+    def validate_token(self) -> Dict[str, Any]:
+        """
+        Validate JWT token and return user info.
+
+        Returns:
+            User information from the validated token
+        """
+        response = self.get("/api-key/validate")
+        return response.json()
+
     # Convenience methods for common API operations
     
     def get_resources(
-        self, 
+        self,
+        project_name: str,
         resource_types: Optional[str] = None,
         limit: int = 20,
         offset: int = 0,
@@ -126,89 +138,98 @@ class HumaLabApiClient:
     ) -> Dict[str, Any]:
         """
         Get list of all resources.
-        
+
         Args:
+            project_name: Project name (required)
             resource_types: Comma-separated resource types to filter by
             limit: Maximum number of resources to return
             offset: Number of resources to skip
             latest_only: If true, only return latest version of each resource
-            
+
         Returns:
             Resource list with pagination info
         """
         params = {
+            "project_name": project_name,
             "limit": limit,
             "offset": offset,
             "latest_only": latest_only
         }
         if resource_types:
             params["resource_types"] = resource_types
-            
+
         response = self.get("/resources", params=params)
         return response.json()
     
-    def get_resource(self, name: str, version: Optional[int] = None) -> Dict[str, Any]:
+    def get_resource(self, name: str, project_name: str, version: Optional[int] = None) -> Dict[str, Any]:
         """
         Get a specific resource.
-        
+
         Args:
             name: Resource name
-            version: Specific version (defaults to latest)
-            
+            project_name: Project name (required)
+            version: Optional specific version (defaults to latest)
+
         Returns:
             Resource data
         """
         if version is not None:
             endpoint = f"/resources/{name}/{version}"
+            params = {"project_name": project_name}
         else:
             endpoint = f"/resources/{name}"
-        
-        response = self.get(endpoint)
+            params = {"project_name": project_name}
+
+        response = self.get(endpoint, params=params)
         return response.json()
     
     def download_resource(
-        self, 
-        name: str, 
+        self,
+        name: str,
+        project_name: str,
         version: Optional[int] = None
     ) -> bytes:
         """
         Download a resource file.
-        
+
         Args:
             name: Resource name
-            version: Specific version (defaults to latest)
-            
+            project_name: Project name (required)
+            version: Optional specific version (defaults to latest)
+
         Returns:
             Resource file content as bytes
         """
+        endpoint = f"/resources/{name}/download"
+        params = {"project_name": project_name}
         if version is not None:
-            endpoint = f"/resources/{name}/download?version={version}"
-        else:
-            endpoint = f"/resources/{name}/download"
+            params["version"] = str(version)
 
-        response = self.get(endpoint)
+        response = self.get(endpoint, params=params)
         return response.content
     
     def upload_resource(
-        self, 
-        name: str, 
-        file_path: str, 
+        self,
+        name: str,
+        file_path: str,
         resource_type: str,
+        project_name: str,
         description: Optional[str] = None,
         filename: Optional[str] = None,
         allow_duplicate_name: bool = False
     ) -> Dict[str, Any]:
         """
         Upload a resource file.
-        
+
         Args:
             name: Resource name
             file_path: Path to file to upload
             resource_type: Type of resource (urdf, mjcf, etc.)
+            project_name: Project name (required)
             description: Optional description
             filename: Optional custom filename
             allow_duplicate_name: Allow creating new version with existing name
-            
+
         Returns:
             Created resource data
         """
@@ -219,12 +240,13 @@ class HumaLabApiClient:
                 data['description'] = description
             if filename:
                 data['filename'] = filename
-                
+
             params = {
                 'resource_type': resource_type,
+                'project_name': project_name,
                 'allow_duplicate_name': allow_duplicate_name
             }
-            
+
             response = self.post(f"/resources/{name}/upload", files=files, params=params)
             return response.json()
     
@@ -232,42 +254,511 @@ class HumaLabApiClient:
         """Get list of all available resource types."""
         response = self.get("/resources/types")
         return response.json()
+
+    def get_scenarios(
+        self,
+        project_name: str,
+        skip: int = 0,
+        limit: int = 10,
+        include_inactive: bool = False,
+        search: Optional[str] = None,
+        status_filter: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Get list of scenarios with pagination and filtering.
+
+        Args:
+            project_name: Project name (required)
+            skip: Number of scenarios to skip for pagination
+            limit: Maximum number of scenarios to return (1-100)
+            include_inactive: Include inactive scenarios in results
+            search: Search term to filter by name, description, or UUID
+            status_filter: Filter by specific status
+
+        Returns:
+            Paginated list of scenarios
+        """
+        params = {
+            "project_name": project_name,
+            "skip": skip,
+            "limit": limit,
+            "include_inactive": include_inactive
+        }
+        if search:
+            params["search"] = search
+        if status_filter:
+            params["status_filter"] = status_filter
+
+        response = self.get("/scenarios", params=params)
+        return response.json()
     
-    def delete_resource(self, name: str, version: Optional[int] = None) -> None:
+    def get_scenario(self, uuid: str, project_name: str, version: Optional[int] = None) -> Dict[str, Any]:
         """
-        Delete a resource.
-        
+        Get a specific scenario.
+
         Args:
-            name: Resource name
-            version: Specific version to delete (if None, deletes all versions)
+            uuid: Scenario UUID
+            project_name: Project name (required)
+            version: Optional specific version (defaults to latest)
+
+        Returns:
+            Scenario data
         """
+        endpoint = f"/scenarios/{uuid}"
+        params = {"project_name": project_name}
         if version is not None:
-            endpoint = f"/resources/{name}/{version}"
-        else:
-            endpoint = f"/resources/{name}"
+            params["scenario_version"] = str(version)
+
+        response = self.get(endpoint, params=params)
+        return response.json()
+
+    def create_scenario(
+        self,
+        name: str,
+        project_name: str,
+        description: Optional[str] = None,
+        yaml_content: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Create a new scenario.
+
+        Args:
+            name: Scenario name
+            project_name: Project name to organize the scenario (required)
+            description: Optional scenario description
+            yaml_content: Optional YAML content defining the scenario
+
+        Returns:
+            Created scenario data with UUID and version
+
+        Raises:
+            HTTPException: If scenario name already exists for the project
+        """
+        data = {
+            "name": name,
+            "project_name": project_name
+        }
+        if description:
+            data["description"] = description
+        if yaml_content:
+            data["yaml_content"] = yaml_content
+
+        response = self.post("/scenarios", data=data)
+        return response.json()
+
+    # Run CI API methods
+    
+    def create_project(self, name: str, description: Optional[str] = None) -> Dict[str, Any]:
+        """
+        Create a new project.
         
-        self.delete(endpoint)
+        Args:
+            name: Project name
+            description: Optional project description
+            
+        Returns:
+            Created project data
+        """
+        data = {"name": name}
+        if description:
+            data["description"] = description
+            
+        response = self.post("/projects", data=data)
+        return response.json()
     
-    def get_scenarios(self) -> List[Dict[str, Any]]:
-        """Get list of all scenarios."""
-        response = self.get("/scenarios")
+    def get_projects(
+        self, 
+        limit: int = 20, 
+        offset: int = 0
+    ) -> Dict[str, Any]:
+        """
+        Get list of projects.
+        
+        Args:
+            limit: Maximum number of projects to return
+            offset: Number of projects to skip
+            
+        Returns:
+            Project list with pagination info
+        """
+        params = {"limit": limit, "offset": offset}
+        response = self.get("/projects", params=params)
         return response.json()
     
-    def get_scenario(self, uuid: str, version: Optional[int] = None) -> Dict[str, Any]:
+    def get_project(self, name: str) -> Dict[str, Any]:
         """
-        Get a specific scenario.
+        Get a specific project.
         
         Args:
-            uuid: Scenario UUID
-            version: Specific version (defaults to latest)
+            name: Project name
             
         Returns:
-            Scenario data
+            Project data
         """
-        if version is not None:
-            endpoint = f"/scenarios/{uuid}/{version}"
-        else:
-            endpoint = f"/scenarios/{uuid}"
+        response = self.get(f"/projects/{name}")
+        return response.json()
+    
+    def update_project(self, name: str, description: Optional[str] = None) -> Dict[str, Any]:
+        """
+        Update a project.
+
+        Args:
+            name: Project name
+            description: Optional new description
+
+        Returns:
+            Updated project data
+        """
+        data = {}
+        if description is not None:
+            data["description"] = description
+
+        response = self.put(f"/projects/{name}", data=data)
+        return response.json()
+    
+    def create_run(
+        self, 
+        name: str, 
+        project_name: str,
+        description: Optional[str] = None,
+        arguments: Optional[List[Dict[str, str]]] = None,
+        tags: Optional[List[str]] = None
+    ) -> Dict[str, Any]:
+        """
+        Create a new run.
         
-        response = self.get(endpoint)
+        Args:
+            name: Run name
+            project_name: Project name
+            description: Optional run description
+            arguments: Optional list of key-value arguments
+            tags: Optional list of tags
+            
+        Returns:
+            Created run data with runId
+        """
+        data = {
+            "name": name,
+            "project_name": project_name,
+            "arguments": arguments or [],
+            "tags": tags or []
+        }
+        if description:
+            data["description"] = description
+            
+        response = self.post("/runs", data=data)
+        return response.json()
+    
+    def get_runs(
+        self,
+        project_name: Optional[str],
+        status: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+        limit: int = 20,
+        offset: int = 0
+    ) -> Dict[str, Any]:
+        """
+        Get list of runs.
+        
+        Args:
+            project_name: Filter by project name
+            status: Filter by status (running, finished, failed, killed)
+            tags: Filter by tags
+            limit: Maximum number of runs to return
+            offset: Number of runs to skip
+            
+        Returns:
+            Run list with pagination info
+        """
+        params = {"limit": limit, "offset": offset}
+        if not project_name:
+            raise ValueError("project_name is required to get runs.")
+        params["project_name"] = project_name
+        if status:
+            params["status"] = status
+        if tags:
+            params["tags"] = ",".join(tags)
+            
+        response = self.get("/runs", params=params)
+        return response.json()
+    
+    def get_run(self, run_id: str) -> Dict[str, Any]:
+        """
+        Get a specific run.
+        
+        Args:
+            run_id: Run ID
+            
+        Returns:
+            Run data
+        """
+        response = self.get(f"/runs/{run_id}")
+        return response.json()
+    
+    def update_run(
+        self,
+        run_id: str,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        status: Optional[str] = None,
+        arguments: Optional[List[Dict[str, str]]] = None,
+        tags: Optional[List[str]] = None
+    ) -> Dict[str, Any]:
+        """
+        Update a run.
+
+        Args:
+            run_id: Run ID
+            name: Optional new name
+            description: Optional new description
+            status: Optional new status
+            arguments: Optional new arguments
+            tags: Optional new tags
+
+        Returns:
+            Updated run data
+        """
+        data = {}
+        if name is not None:
+            data["name"] = name
+        if description is not None:
+            data["description"] = description
+        if status is not None:
+            data["status"] = status
+        if arguments is not None:
+            data["arguments"] = arguments
+        if tags is not None:
+            data["tags"] = tags
+
+        response = self.put(f"/runs/{run_id}", data=data)
+        return response.json()
+    
+    def create_episode(
+        self, 
+        run_id: str, 
+        episode_name: str,
+        status: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Create a new episode.
+        
+        Args:
+            run_id: Run ID
+            episode_name: Episode name
+            status: Optional episode status
+            
+        Returns:
+            Created episode data
+        """
+        data = {
+            "episode_name": episode_name,
+            "run_id": run_id
+        }
+        if status:
+            data["status"] = status
+            
+        response = self.post("/episodes", data=data)
+        return response.json()
+    
+    def get_episodes(
+        self,
+        run_id: Optional[str] = None,
+        status: Optional[str] = None,
+        limit: int = 20,
+        offset: int = 0
+    ) -> Dict[str, Any]:
+        """
+        Get list of episodes.
+        
+        Args:
+            run_id: Filter by run ID
+            status: Filter by status
+            limit: Maximum number of episodes to return
+            offset: Number of episodes to skip
+            
+        Returns:
+            Episode list with pagination info
+        """
+        params = {"limit": limit, "offset": offset}
+        if run_id:
+            params["run_id"] = run_id
+        if status:
+            params["status"] = status
+            
+        response = self.get("/episodes", params=params)
+        return response.json()
+    
+    def get_episode(self, run_id: str, episode_name: str) -> Dict[str, Any]:
+        """
+        Get a specific episode.
+        
+        Args:
+            run_id: Run ID
+            episode_name: Episode name
+            
+        Returns:
+            Episode data
+        """
+        response = self.get(f"/episodes/{run_id}/{episode_name}")
+        return response.json()
+    
+    def update_episode(
+        self,
+        run_id: str,
+        episode_name: str,
+        status: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Update an episode.
+        
+        Args:
+            run_id: Run ID
+            episode_name: Episode name
+            status: Optional new status
+            
+        Returns:
+            Updated episode data
+        """
+        data = {}
+        if status is not None:
+            data["status"] = status
+            
+        response = self.put(f"/episodes/{run_id}/{episode_name}", data=data)
+        return response.json()
+    
+    def delete_episode(self, run_id: str, episode_name: str) -> None:
+        """
+        Delete an episode.
+        
+        Args:
+            run_id: Run ID
+            episode_name: Episode name
+        """
+        self.delete(f"/episodes/{run_id}/{episode_name}")
+    
+    def upload_blob(
+        self,
+        artifact_key: str,
+        run_id: str,
+        file_path: str,
+        artifact_type: str,
+        episode_name: Optional[str] = None,
+        description: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Upload a blob artifact (image/video).
+        
+        Args:
+            artifact_key: Artifact key identifier
+            run_id: Run ID
+            file_path: Path to file to upload
+            artifact_type: Type of artifact ('image' or 'video')
+            episode_name: Optional episode name (None for run-level artifacts)
+            description: Optional description
+            
+        Returns:
+            Created artifact data
+        """
+        with open(file_path, 'rb') as f:
+            files = {'file': f}
+            form_data = {
+                'artifact_key': artifact_key,
+                'run_id': run_id,
+                'artifact_type': artifact_type
+            }
+            if episode_name:
+                form_data['episode_name'] = episode_name
+            if description:
+                form_data['description'] = description
+                
+            response = self.post("/artifacts/blob/upload", files=files, data=form_data)
+            return response.json()
+    
+    def upsert_metrics(
+        self,
+        artifact_key: str,
+        run_id: str,
+        metric_type: str,
+        metric_data: List[Dict[str, Any]],
+        episode_name: Optional[str] = None,
+        description: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Upsert metrics artifact (create or append).
+        
+        Args:
+            artifact_key: Artifact key identifier
+            run_id: Run ID
+            metric_type: Type of metric display ('line', 'bar', 'scatter', 'gauge', 'counter')
+            metric_data: List of metric data points with 'key', 'values', 'timestamp'
+            episode_name: Optional episode name (None for run-level artifacts)
+            description: Optional description
+            
+        Returns:
+            Created/updated artifact data
+        """
+        data = {
+            "artifact_key": artifact_key,
+            "run_id": run_id,
+            "metric_type": metric_type,
+            "metric_data": metric_data
+        }
+        if episode_name:
+            data["episode_name"] = episode_name
+        if description:
+            data["description"] = description
+            
+        response = self.post("/artifacts/metrics", data=data)
+        return response.json()
+    
+    def get_artifacts(
+        self,
+        run_id: Optional[str] = None,
+        episode_name: Optional[str] = None,
+        artifact_type: Optional[str] = None,
+        limit: int = 20,
+        offset: int = 0
+    ) -> Dict[str, Any]:
+        """
+        Get list of artifacts.
+        
+        Args:
+            run_id: Filter by run ID
+            episode_name: Filter by episode name
+            artifact_type: Filter by artifact type
+            limit: Maximum number of artifacts to return
+            offset: Number of artifacts to skip
+            
+        Returns:
+            Artifact list with pagination info
+        """
+        params = {"limit": limit, "offset": offset}
+        if run_id:
+            params["run_id"] = run_id
+        if episode_name:
+            params["episode_name"] = episode_name
+        if artifact_type:
+            params["artifact_type"] = artifact_type
+            
+        response = self.get("/artifacts", params=params)
+        return response.json()
+    
+    def get_artifact(
+        self, 
+        run_id: str, 
+        episode_name: str, 
+        artifact_key: str
+    ) -> Dict[str, Any]:
+        """
+        Get a specific artifact.
+        
+        Args:
+            run_id: Run ID
+            episode_name: Episode name
+            artifact_key: Artifact key
+            
+        Returns:
+            Artifact data
+        """
+        response = self.get(f"/artifacts/{run_id}/{episode_name}/{artifact_key}")
         return response.json()