neuracore 1.0.0__tar.gz

neuracore-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Neuraco
+
+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.

neuracore-1.0.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.1
+Name: neuracore
+Version: 1.0.0
+Summary: Neuracore Client Library
+Home-page: https://github.com/neuraco/neuracore
+Author: Stephen James
+Author-email: stephen@neuraco.com
+Keywords: robotics machine-learning ai client-library
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: examples
+Provides-Extra: local_endpoint
+Provides-Extra: dev
+License-File: LICENSE
+
+# Neuracore Python Client
+
+Neuracore is a powerful robotics and machine learning client library for seamless robot data collection, model deployment, and interaction.
+
+## Features
+
+- Easy robot initialization and connection
+- Streaming data logging
+- Model endpoint management
+- Local and remote model support
+- Flexible dataset creation
+
+## Installation
+
+```bash
+pip install neuracore
+```
+
+## Quick Start
+
+Ensure you have an account at (https://www.neuracore.app/)[https://www.neuracore.app/]
+
+### Authentication
+
+```python
+import neuracore as nc
+
+# This will save your API key locally
+nc.login()
+```
+
+### Robot Connection
+
+```python
+# Connect to a robot
+nc.connect_robot(
+    robot_name="MyRobot", 
+    urdf_path="/path/to/robot.urdf"
+)
+```
+
+### Data Logging
+
+```python
+# Log joint positions
+nc.log_joints({
+    'joint1': 0.5, 
+    'joint2': -0.3
+})
+
+# Log RGB camera image
+nc.log_rgb("top_camera", image_array)
+```
+
+## Development
+
+To set up for development:
+
+```bash
+git clone https://github.com/neuraco/neuracore
+cd neuracore
+pip install -e .[dev]
+```
+
+## Testing
+
+```bash
+export NEURACORE_API_URL=http://localhost:8000/api
+pytest tests/
+```
+
+## Contributing
+
+Contributions are welcome!

neuracore-1.0.0/README.md

@@ -0,0 +1,74 @@
+# Neuracore Python Client
+
+Neuracore is a powerful robotics and machine learning client library for seamless robot data collection, model deployment, and interaction.
+
+## Features
+
+- Easy robot initialization and connection
+- Streaming data logging
+- Model endpoint management
+- Local and remote model support
+- Flexible dataset creation
+
+## Installation
+
+```bash
+pip install neuracore
+```
+
+## Quick Start
+
+Ensure you have an account at (https://www.neuracore.app/)[https://www.neuracore.app/]
+
+### Authentication
+
+```python
+import neuracore as nc
+
+# This will save your API key locally
+nc.login()
+```
+
+### Robot Connection
+
+```python
+# Connect to a robot
+nc.connect_robot(
+    robot_name="MyRobot", 
+    urdf_path="/path/to/robot.urdf"
+)
+```
+
+### Data Logging
+
+```python
+# Log joint positions
+nc.log_joints({
+    'joint1': 0.5, 
+    'joint2': -0.3
+})
+
+# Log RGB camera image
+nc.log_rgb("top_camera", image_array)
+```
+
+## Development
+
+To set up for development:
+
+```bash
+git clone https://github.com/neuraco/neuracore
+cd neuracore
+pip install -e .[dev]
+```
+
+## Testing
+
+```bash
+export NEURACORE_API_URL=http://localhost:8000/api
+pytest tests/
+```
+
+## Contributing
+
+Contributions are welcome!

neuracore-1.0.0/neuracore/__init__.py

@@ -0,0 +1,3 @@
+from .core import *  # noqa: F403
+
+__version__ = "1.0.0"

neuracore-1.0.0/neuracore/auth.py

@@ -0,0 +1,125 @@
+import json
+import os
+from pathlib import Path
+
+import requests
+
+from neuracore.const import API_URL
+
+from .exceptions import AuthenticationError
+from .generate_api_key import generate_api_key
+
+CONFIG_DIR = Path.home() / ".neuracore"
+CONFIG_FILE = "config.json"
+
+
+class Auth:
+    _instance = None
+    _api_key: str | None = None
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __init__(self):
+        self._load_config()
+        self._access_token = None
+
+    def _load_config(self) -> None:
+        """Load configuration from disk if it exists."""
+        config_file = CONFIG_DIR / CONFIG_FILE
+        if config_file.exists():
+            with open(config_file) as f:
+                config = json.load(f)
+                self._api_key = config.get("api_key")
+
+    def _save_config(self) -> None:
+        """Save current configuration to disk."""
+        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        config_file = CONFIG_DIR / CONFIG_FILE
+        with open(config_file, "w") as f:
+            json.dump({"api_key": self._api_key}, f)
+
+    def login(self, api_key: str | None = None) -> None:
+        """
+        Authenticate with the NeuraCore server using an API key.
+
+        Args:
+            api_key: Optional API key. If not provided, will try to use environment
+                    variable NEURACORE_API_KEY or previously saved config.
+        """
+        self._api_key = api_key or os.environ.get("NEURACORE_API_KEY") or self._api_key
+
+        if not self._api_key:
+            print("No API key provided. Attempting to log you in...")
+            self._api_key = generate_api_key()
+
+        # Verify API key with server and get access token
+        try:
+            response = requests.post(
+                f"{API_URL}/auth/verify-api-key",
+                json={"api_key": self._api_key},
+            )
+            if response.status_code != 200:
+                raise AuthenticationError(
+                    f"Failed to authenticate: {response.json().get('detail')}"
+                )
+            token_data = response.json()
+            self._access_token = token_data["access_token"]
+        except requests.exceptions.RequestException as e:
+            raise AuthenticationError(f"Failed to authenticate: {str(e)}")
+
+        # Save configuration if verification successful
+        self._save_config()
+
+    def logout(self) -> None:
+        """Clear authentication state."""
+        self._api_key = None
+        self._access_token = None
+        config_file = CONFIG_DIR / CONFIG_FILE
+        if config_file.exists():
+            config_file.unlink()
+
+    @property
+    def api_key(self) -> str | None:
+        """Get the current API key."""
+        return self._api_key
+
+    @property
+    def access_token(self) -> str | None:
+        """Get the current access token."""
+        return self._access_token
+
+    @property
+    def is_authenticated(self) -> bool:
+        """Check if currently authenticated."""
+        return self._api_key is not None and self._access_token is not None
+
+    def get_headers(self) -> dict:
+        """Get headers for authenticated requests."""
+        if not self.is_authenticated:
+            raise AuthenticationError("Not authenticated. Please call login() first.")
+        return {
+            "Authorization": f"Bearer {self._access_token}",
+            # "Content-Type": "application/json",
+        }
+
+
+# Global instance
+_auth = Auth()
+
+
+def login(api_key: str | None = None) -> None:
+    """Global login function."""
+    _auth.login(api_key)
+
+
+def logout() -> None:
+    """Global logout function."""
+    _auth.logout()
+
+
+def get_auth() -> Auth:
+    """Get the global Auth instance."""
+    return _auth

neuracore-1.0.0/neuracore/const.py

@@ -0,0 +1,3 @@
+import os
+
+API_URL = os.getenv("NEURACORE_API_URL", "https://api.neuracore.app/api")

neuracore-1.0.0/neuracore/core.py

@@ -0,0 +1,250 @@
+import atexit
+
+import numpy as np
+
+from .auth import login as _login
+from .auth import logout as _logout
+from .dataset import Dataset
+from .endpoint import EndpointPolicy
+from .endpoint import connect_endpoint as _connect_endpoint
+from .endpoint import connect_local_endpoint as _connect_local_endpoint
+from .exceptions import RobotError
+from .robot import Robot, get_robot
+from .robot import init as _init_robot
+from .streaming import log_action as _log_action
+from .streaming import log_depth as _log_depth
+from .streaming import log_joints as _log_joints
+from .streaming import log_rgb as _log_rgb
+from .streaming import stop_all_streams as _stop_all_streams
+from .streaming import stop_streaming as _stop_streaming
+from .streaming import wait_until_stream_empty
+
+# Global active robot ID - allows us to avoid passing robot_name to every call
+_active_robot: Robot | None = None
+_active_dataset_id: str | None = None
+_active_recording_id: str | None = None
+
+
+def login(api_key: str | None = None) -> None:
+    """
+    Authenticate with NeuraCore server.
+
+    Args:
+        api_key: Optional API key. If not provided, will look for NEURACORE_API_KEY
+                environment variable or previously saved configuration.
+
+    Raises:
+        AuthenticationError: If authentication fails
+    """
+    _login(api_key)
+
+
+def logout() -> None:
+    """Clear authentication state."""
+    _logout()
+
+
+def connect_robot(
+    robot_name: str, urdf_path: str | None = None, overwrite: bool = False
+) -> None:
+    """
+    Initialize a robot connection.
+
+    Args:
+        robot_name: Unique identifier for the robot
+        urdf_path: Optional path to robot's URDF file
+    """
+    global _active_robot
+    _active_robot = _init_robot(robot_name, urdf_path, overwrite)
+
+
+def _get_robot(robot_name: str) -> Robot:
+    """Get a robot by name."""
+    robot: Robot = _active_robot
+    if robot_name is None:
+        if _active_robot is None:
+            raise RobotError(
+                "No active robot. Call init() first or provide robot_name."
+            )
+    else:
+        robot = get_robot(robot_name)
+    return robot
+
+
+def log_joints(positions: dict[str, float], robot_name: str | None = None) -> None:
+    """
+    Log joint positions for a robot.
+
+    Args:
+        positions: Dictionary mapping joint names to positions (in radians)
+        robot_name: Optional robot ID. If not provided, uses the last initialized robot
+
+    Raises:
+        RobotError: If no robot is active and no robot_name provided
+        StreamingError: If logging fails
+    """
+    _log_joints(_get_robot(robot_name), positions)
+
+
+def log_action(action: dict[str, float], robot_name: str | None = None) -> None:
+    """
+    Log action for a robot.
+
+    Args:
+        action: Dictionary mapping joint names to positions (in radians)
+        robot_name: Optional robot ID. If not provided, uses the last initialized robot
+
+    Raises:
+        RobotError: If no robot is active and no robot_name provided
+        StreamingError: If logging fails
+    """
+    _log_action(_get_robot(robot_name), action)
+
+
+def log_rgb(camera_id: str, image: np.ndarray, robot_name: str | None = None) -> None:
+    """
+    Log RGB image from a camera.
+
+    Args:
+        camera_id: Unique identifier for the camera
+        image: RGB image as numpy array (HxWx3, dtype=uint8 or float32)
+        robot_name: Optional robot ID. If not provided, uses the last initialized robot
+
+    Raises:
+        RobotError: If no robot is active and no robot_name provided
+        StreamingError: If logging fails
+        ValueError: If image format is invalid
+    """
+    _log_rgb(_get_robot(robot_name), camera_id, image)
+
+
+def log_depth(camera_id: str, depth: np.ndarray, robot_name: str | None = None) -> None:
+    """
+    Log depth image from a camera.
+
+    Args:
+        camera_id: Unique identifier for the camera
+        depth: Depth image as numpy array (HxW, dtype=float32, in meters)
+        robot_name: Optional robot ID. If not provided, uses the last initialized robot
+
+    Raises:
+        RobotError: If no robot is active and no robot_name provided
+        StreamingError: If logging fails
+        ValueError: If depth format is invalid
+    """
+    _log_depth(_get_robot(robot_name), camera_id, depth)
+
+
+def start_recording(robot_name: str | None = None) -> None:
+    """
+    Start recording data for a specific robot.
+
+    Args:
+        robot_name: Optional robot ID. If not provided, uses the last initialized robot
+
+    Raises:
+        RobotError: If no robot is active and no robot_name provided
+    """
+    global _active_recording_id
+    if _active_recording_id is not None:
+        raise RobotError("Recording already in progress. Call stop_recording() first.")
+    robot = _get_robot(robot_name)
+    if _active_dataset_id is None:
+        raise RobotError("No active dataset. Call create_dataset() first.")
+    _active_recording_id = robot.start_recording(_active_dataset_id)
+
+
+def stop_recording(robot_name: str | None = None) -> None:
+    """
+    Stop recording data for a specific robot.
+
+    Args:
+        robot_name: Optional robot ID. If not provided, uses the last initialized robot
+
+    Raises:
+        RobotError: If no robot is active and no robot_name provided
+    """
+    global _active_recording_id
+    robot = _get_robot(robot_name)
+    if _active_recording_id is None:
+        raise RobotError("No active recording. Call start_recording() first.")
+    wait_until_stream_empty(robot)
+    robot.stop_recording(_active_recording_id)
+    _active_recording_id = None
+
+
+def create_dataset(
+    name: str, description: str | None = None, tags: list[str] | None = None
+) -> None:
+    """
+    Create a new dataset for robot demonstrations.
+
+    Args:
+        name: Dataset name
+        description: Optional description
+        tags: Optional list of tags
+
+    Raises:
+        DatasetError: If dataset creation fails
+    """
+    global _active_dataset_id
+    _active_dataset = Dataset(name, description, tags)
+    _active_dataset_id = _active_dataset.id
+
+
+def connect_endpoint(name: str) -> EndpointPolicy:
+    """
+    Connect to a deployed model endpoint.
+
+    Args:
+        name: Name of the deployed endpoint
+
+    Returns:
+        EndpointPolicy: Policy object that can be used for predictions
+
+    Raises:
+        EndpointError: If endpoint connection fails
+    """
+    return _connect_endpoint(name)
+
+
+def connect_local_endpoint(path_to_model: str) -> EndpointPolicy:
+    """
+    Connect to a local model endpoint.
+
+    Args:
+        path_to_model: Path to the local model endpoint
+
+    Returns:
+        EndpointPolicy: Policy object that can be used for predictions
+
+    Raises:
+        EndpointError: If endpoint connection fails
+    """
+    return _connect_local_endpoint(path_to_model)
+
+
+def stop(robot_name: str | None = None) -> None:
+    """
+    Stop streaming for a specific robot.
+
+    Args:
+        robot_name: Optional robot ID. If not provided, uses the last initialized robot
+
+    Raises:
+        RobotError: If no robot is active and no robot_name provided
+    """
+    global _active_robot
+    _stop_streaming(_get_robot(robot_name))
+    if robot_name == _active_robot.name:
+        _active_robot = None
+
+
+def stop_all() -> None:
+    """Stop all active data streams."""
+    global _active_robot
+    _stop_all_streams()
+    _active_robot = None
+
+
+atexit.register(stop_all)

neuracore-1.0.0/neuracore/dataset.py

@@ -0,0 +1,46 @@
+import logging
+
+import requests
+
+from neuracore.const import API_URL
+
+from .auth import Auth, get_auth
+
+logger = logging.getLogger(__name__)
+
+
+class Dataset:
+
+    def __init__(
+        self, name: str, description: str | None = None, tags: list[str] | None = None
+    ):
+        datasets = self._get_datasets()
+        for dataset in datasets:
+            if dataset["name"] == name:
+                self.id = dataset["id"]
+                logger.info(f"Dataset '{name}' already exist.")
+                return
+        id = self._create_dataset(name, description, tags)
+        self.id = id
+
+    def _create_dataset(
+        self, name: str, description: str | None = None, tags: list[str] | None = None
+    ):
+        auth: Auth = get_auth()
+        response = requests.post(
+            f"{API_URL}/api/datasets",
+            headers=auth.get_headers(),
+            json={
+                "name": name,
+                "description": description,
+            },
+        )
+        response.raise_for_status()
+        dataset_json = response.json()
+        return dataset_json["id"]
+
+    def _get_datasets(self):
+        auth: Auth = get_auth()
+        response = requests.get(f"{API_URL}/api/datasets", headers=auth.get_headers())
+        response.raise_for_status()
+        return response.json()