simulac 0.0.1__tar.gz

simulac-0.0.1/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.3
+Name: simulac
+Version: 0.0.1
+Summary: A CLI, library, and local server for interacting with the Tektonian backend.
+Keywords: robotics,robot-simulation,simulation,physics-engine,mujoco,newton,genesis,mjcf,urdf,usd
+Author: Jeuk Kang
+Author-email: Jeuk Kang <gangjeuk@tektonian.com>
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Requires-Dist: pydantic<3
+Requires-Dist: duckdb>=1.4
+Requires-Dist: structlog>=25.5.0
+Requires-Dist: mujoco>=3.5.0
+Requires-Dist: websockets>=15.0.1
+Requires-Dist: typer>=0.24.1
+Requires-Dist: zstd>=1.5.7.3
+Requires-Dist: msgpack>=1.1.2
+Requires-Dist: autodoc-pydantic>=2.2.0 ; extra == 'doc'
+Requires-Dist: furo>=2025.12.19 ; extra == 'doc'
+Requires-Dist: myst-parser>=4.0.1 ; extra == 'doc'
+Requires-Dist: sphinx>=8.1.3 ; extra == 'doc'
+Requires-Dist: genesis-world==0.3.12 ; extra == 'genesis'
+Requires-Dist: torch>=2.10.0 ; extra == 'genesis'
+Requires-Dist: newton>=1.0.0rc0 ; extra == 'newton'
+Requires-Dist: warp-lang>=1.12.0 ; extra == 'newton'
+Requires-Dist: mujoco-warp>=3.5.0.2 ; extra == 'newton'
+Requires-Python: >=3.10
+Project-URL: Homepage, https://tektonian.com
+Project-URL: Repository, https://github.com/Tektonian/tektonian-python
+Provides-Extra: doc
+Provides-Extra: genesis
+Provides-Extra: newton
+Description-Content-Type: text/markdown
+
+<h1 align="center"><b>Simulac</b></h3>
+
+<h3 align="center"><b>⚡️ Developer centric digital twin builder</b></h3>
+
+---
+
+[Simulac](https://github.com/Tektonian/simulac) is digital twin build tool filling the gap between physical world and software world.
+
+Simulac helps transition between the two worlds, and provides developer-friendly API to building the world.
+
+# Quick start
+
+## Installation
+
+Simulac requires Python 3.10 or later.
+
+```bash
+$ pip install simulac
+$ uv add simulac
+```
+
+## Sign up and create an API key
+
+Remote benchmark execution requires a Tektonian API key.
+Go to our [website](https://tektonian.com) and get an API key.
+
+Store your API key with CLI commend:
+```bash
+simulac login
+```
+
+You can also provide the key through an environment variable:
+```bash
+export SIMULAC_API_KEY=<you_api_key>
+```
+Note: API keys can only be viewed once when created
+
+# Key function
+Simulac provides one-line code execution for robot domain benchmark, and world building API (on developing)
+
+## Benchmark
+
+You can execution famous Physical-AI benchmarks with one-line of code.
+We currently support: 
+- **[Libero](https://tektonian.com/profile/Tektonian/Libero)**
+- **[Calvin](https://tektonian.com/profile/Tektonian/Calvin)**
+- **[Robomimic](https://tektonian.com/profile/Tektonian/Robomimic)**
+- **[Metaworld](https://tektonian.com/profile/Tektonian/Metaworld)** 
+
+Visit [benchmark list](https://tektonian.com/benchmark) for details for running it.
+### Run benchmark
+```python
+from simulac.gym_style import init_bench
+
+env = init_bench(
+    "Tektonian/Libero",
+    "libero_90/KITCHEN_SCENE2_put_the_black_bowl_at_the_back_on_the_plate",
+    0,
+    {"control_mode": "ee_pose"},
+)
+
+step = env.step(ACTION_ARRAY)
+
+```
+### Parallel Benchmark Execution
+
+```python
+from simulac.gym_style import init_bench, make_vec
+
+args = (
+    "Tektonian/Libero",
+    "libero_90/KITCHEN_SCENE2_put_the_black_bowl_at_the_back_on_the_plate",
+    0,
+)
+options = {"benchmark_specific": {"control_mode": "ee_pose"}}
+
+envs = [init_bench(*args, **options) for _ in range(3)]
+vec_env = make_vec(envs)
+
+steps = vec_env.step([[0.0] * 7 for _ in envs])
+print(len(steps))
+```
+
+## Configuration
+
+Simulac reads configuration from environment variables when present:
+
+- `SIMULAC_API_KEY`: use an API key without running `simulac login`
+- `SIMULAC_BASE_URL`: override the default Tektonian API endpoint
+- `SIMULAC_LOG_LEVEL`: set log verbosity. choose one of `off, trace, debug, info, warning, error`
+- `SIMULAC_TELEMETRY=off`: disable telemetry
+
+
+## World building
+
+The world-building surface is best viewed as an evolving foundation for scene assembly and engine integration. 
+
+## Project Status
+
+Simulac is currently alpha software.
+
+- The remote benchmark client is the most complete public surface.
+- Local world-building and runner APIs are still evolving.
+
+## License
+
+Apache-2.0

simulac-0.0.1/README.md

@@ -0,0 +1,107 @@
+<h1 align="center"><b>Simulac</b></h3>
+
+<h3 align="center"><b>⚡️ Developer centric digital twin builder</b></h3>
+
+---
+
+[Simulac](https://github.com/Tektonian/simulac) is digital twin build tool filling the gap between physical world and software world.
+
+Simulac helps transition between the two worlds, and provides developer-friendly API to building the world.
+
+# Quick start
+
+## Installation
+
+Simulac requires Python 3.10 or later.
+
+```bash
+$ pip install simulac
+$ uv add simulac
+```
+
+## Sign up and create an API key
+
+Remote benchmark execution requires a Tektonian API key.
+Go to our [website](https://tektonian.com) and get an API key.
+
+Store your API key with CLI commend:
+```bash
+simulac login
+```
+
+You can also provide the key through an environment variable:
+```bash
+export SIMULAC_API_KEY=<you_api_key>
+```
+Note: API keys can only be viewed once when created
+
+# Key function
+Simulac provides one-line code execution for robot domain benchmark, and world building API (on developing)
+
+## Benchmark
+
+You can execution famous Physical-AI benchmarks with one-line of code.
+We currently support: 
+- **[Libero](https://tektonian.com/profile/Tektonian/Libero)**
+- **[Calvin](https://tektonian.com/profile/Tektonian/Calvin)**
+- **[Robomimic](https://tektonian.com/profile/Tektonian/Robomimic)**
+- **[Metaworld](https://tektonian.com/profile/Tektonian/Metaworld)** 
+
+Visit [benchmark list](https://tektonian.com/benchmark) for details for running it.
+### Run benchmark
+```python
+from simulac.gym_style import init_bench
+
+env = init_bench(
+    "Tektonian/Libero",
+    "libero_90/KITCHEN_SCENE2_put_the_black_bowl_at_the_back_on_the_plate",
+    0,
+    {"control_mode": "ee_pose"},
+)
+
+step = env.step(ACTION_ARRAY)
+
+```
+### Parallel Benchmark Execution
+
+```python
+from simulac.gym_style import init_bench, make_vec
+
+args = (
+    "Tektonian/Libero",
+    "libero_90/KITCHEN_SCENE2_put_the_black_bowl_at_the_back_on_the_plate",
+    0,
+)
+options = {"benchmark_specific": {"control_mode": "ee_pose"}}
+
+envs = [init_bench(*args, **options) for _ in range(3)]
+vec_env = make_vec(envs)
+
+steps = vec_env.step([[0.0] * 7 for _ in envs])
+print(len(steps))
+```
+
+## Configuration
+
+Simulac reads configuration from environment variables when present:
+
+- `SIMULAC_API_KEY`: use an API key without running `simulac login`
+- `SIMULAC_BASE_URL`: override the default Tektonian API endpoint
+- `SIMULAC_LOG_LEVEL`: set log verbosity. choose one of `off, trace, debug, info, warning, error`
+- `SIMULAC_TELEMETRY=off`: disable telemetry
+
+
+## World building
+
+The world-building surface is best viewed as an evolving foundation for scene assembly and engine integration. 
+
+## Project Status
+
+Simulac is currently alpha software.
+
+- The remote benchmark client is the most complete public surface.
+- Local world-building and runner APIs are still evolving.
+
+## License
+
+Apache-2.0

simulac-0.0.1/pyproject.toml

@@ -0,0 +1,122 @@
+# START - project setting
+[build-system]
+requires = ["uv_build>=0.11.1,<0.12"]
+build-backend = "uv_build"
+
+[project]
+name = "simulac"
+version = "0.0.1"
+description = "A CLI, library, and local server for interacting with the Tektonian backend."
+authors = [{ name = "Jeuk Kang", email = "gangjeuk@tektonian.com" }]
+keywords = [
+    "robotics",
+    "robot-simulation",
+    "simulation",
+    "physics-engine",
+    "mujoco",
+    "newton",
+    "genesis",
+    "mjcf",
+    "urdf",
+    "usd",
+]
+readme = "README.md"
+requires-python = ">=3.10"
+classifiers = [
+    # How mature is this project? Common values are
+    #   3 - Alpha
+    #   4 - Beta
+    #   5 - Production/Stable
+    "Development Status :: 3 - Alpha",
+
+    # Indicate who your project is intended for
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Build Tools",
+
+    # Specify the Python versions you support here.
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+]
+dependencies = [
+    "pydantic<3",
+    "duckdb>=1.4",
+    "structlog>=25.5.0",
+    "mujoco>=3.5.0",
+    "websockets>=15.0.1",
+    "typer>=0.24.1",
+    "zstd>=1.5.7.3",
+    "msgpack>=1.1.2",
+]
+
+[project.scripts]
+simulac = "simulac.cli:main"
+
+[project.urls]
+Homepage = "https://tektonian.com"
+Repository = "https://github.com/Tektonian/tektonian-python"
+
+[project.optional-dependencies]
+genesis = ["genesis-world==0.3.12", "torch>=2.10.0"]
+
+newton = ["newton>=1.0.0rc", "warp-lang>=1.12.0", "mujoco-warp>=3.5.0.2"]
+
+doc = [
+    "autodoc-pydantic>=2.2.0",
+    "furo>=2025.12.19",
+    "myst-parser>=4.0.1",
+    "sphinx>=8.1.3",
+]
+
+[dependency-groups]
+dev = [
+    "pyright>=1.1.408",
+    "pylint==3.3.4",
+    "ruff>=0.15.5",
+    "pybind11-stubgen>=2.5.5",
+    "typing_extensions>=4.8,<5",
+    "eval_type_backport; python_version < '3.10'",
+    "packaging",
+    "pytest",
+    "nox>=2026.2.9",
+    "pytest-cov>=7.0.0",
+    "numpy",
+    "pillow",
+    "opencv-python",
+]
+
+# END - project setting
+
+# START - linting tool setting
+[tool.ruff.lint]
+select = ["E", "F", "I", "TC004"]
+ignore = ["F401"]
+
+[tool.ruff.format]
+docstring-code-format = true
+exclude = ["trash"]
+
+[tool.pyright]
+stubPath = ".typings"
+typeCheckingMode = "strict"
+
+[tool.ruff.lint.isort]
+required-imports = ["from __future__ import annotations"]
+
+# END - linting tool setting
+
+# START - build tool
+
+[tool.uv.build-backend]
+module-name = "simulac"
+module-root = ""
+source-include = ["simulac/**"]
+
+# END - build tool
+
+# START - testing tool
+[tool.pytest.ini_options]
+markers = [
+    "integration: tests requiring external web service",
+]
+pythonpath = ["."]
+# END - testing tool

simulac-0.0.1/simulac/__init__.py

@@ -0,0 +1,20 @@
+from .lib.world_maker.entity import Camera, Light, Robot, Stuff
+from .lib.world_maker.object import (
+    CameraObject,
+    Environment,
+    LightObject,
+    RobotObject,
+    StuffObject,
+)
+
+__all__ = [
+    "Robot",
+    "Stuff",
+    "Camera",
+    "Light",
+    "Environment",
+    "RobotObject",
+    "StuffObject",
+    "CameraObject",
+    "LightObject",
+]

simulac-0.0.1/simulac/base/envvar/envvar.py

@@ -0,0 +1,62 @@
+from abc import abstractmethod
+from pathlib import Path
+
+from simulac.base.instantiate.instantiate import ServiceIdentifier, service_identifier
+
+
+@service_identifier("IEnvvarService")
+class IEnvvarService(ServiceIdentifier["IEnvvarService"]):
+    # logging
+    @property
+    @abstractmethod
+    def log_level(self) -> str: ...
+
+    # telemetry
+    @property
+    @abstractmethod
+    def telemetry_disabled(self) -> bool: ...
+
+    # file path
+    @property
+    @abstractmethod
+    def log_file(self) -> Path: ...
+
+    @property
+    @abstractmethod
+    def app_root(self) -> Path:
+        """Root path, where this package is being used"""
+
+    @property
+    @abstractmethod
+    def user_home(self) -> Path: ...
+
+    @property
+    @abstractmethod
+    def tmp_dir(self) -> Path: ...
+
+    @property
+    @abstractmethod
+    def simulac_cache_dir(self) -> Path: ...
+
+    @property
+    @abstractmethod
+    def asset_dir(self) -> Path: ...
+
+    @property
+    @abstractmethod
+    def token_path(self) -> Path: ...
+
+    # token
+    @property
+    @abstractmethod
+    def token(self) -> str | None: ...
+
+    # url
+    @property
+    @abstractmethod
+    def base_url(self) -> str: ...
+
+    # develop
+    @property
+    @abstractmethod
+    def dev_mode(self) -> bool: ...

simulac-0.0.1/simulac/base/envvar/envvar_service.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import os
+import sys
+import tempfile
+from enum import StrEnum
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from simulac.base.envvar.envvar import IEnvvarService
+
+if TYPE_CHECKING:
+    from simulac.sdk.log_service.common.log_service import LogLevel
+
+
+class EnvvarKeyValue(StrEnum):
+    SIMULAC_LOG_LEVEL = "SIMULAC_LOG_LEVEL"
+    SIMULAC_BASE_URL = "SIMULAC_BASE_URL"
+    SIMULAC_TELEMETRY = "SIMULAC_TELEMETRY"
+    SIMULAC_API_KEY = "SIMULAC_API_KEY"
+
+
+class EnvvarService(IEnvvarService):
+    """
+    TODO: @gangjeuk
+    EnvvarService is not idle code
+    1. rename @property names
+    2. is it a good pattern to have directory location related codes here?
+    """
+
+    BASE_URL = "https://tektonian.com/api"
+
+    KEY_VALUE = EnvvarKeyValue
+
+    def __init__(self) -> None:
+        self._log_level = "info"
+
+        self._user_home = os.path.expanduser("~")
+        self._tmp_dir = tempfile.gettempdir()
+        self._app_root = os.getcwd()
+
+    @property
+    def log_level(self) -> str:
+        level = os.environ.get(self.KEY_VALUE.SIMULAC_LOG_LEVEL.value, None)
+        if level in ["off", "trace", "debug", "info", "warning", "error"]:
+            return level
+        else:
+            return self._log_level
+
+    @property
+    def telemetry_disabled(self) -> bool:
+        tele_env = os.environ.get(self.KEY_VALUE.SIMULAC_TELEMETRY.value, None)
+        if tele_env is None:
+            return False
+        elif tele_env == "off":
+            return True
+
+        return False
+
+    @property
+    def log_file(self) -> Path:
+        simulac_log_path = os.path.join(self.app_root, ".simulac", "log.json")
+        return Path(simulac_log_path)
+
+    @property
+    def app_root(self) -> Path:
+        return Path(self._app_root)
+
+    @property
+    def user_home(self) -> Path:
+        return Path(self._user_home)
+
+    @property
+    def tmp_dir(self) -> Path:
+        return Path(self._tmp_dir)
+
+    @property
+    def simulac_cache_dir(self) -> Path:
+        return Path(os.path.join(self.user_home, ".cache", "simulac"))
+
+    @property
+    def asset_dir(self) -> Path:
+        return Path(os.path.join(self.simulac_cache_dir, "asset"))
+
+    @property
+    def token_path(self) -> Path:
+        return Path(os.path.join(self.simulac_cache_dir, "token"))
+
+    @property
+    def token(self) -> str | None:
+        token_env = os.environ.get(self.KEY_VALUE.SIMULAC_API_KEY.value, None)
+        if token_env is not None:
+            return token_env
+
+        token_ret = ""
+        if self.token_path.exists() and self.token_path.is_file():
+            with open(self.token_path, "r") as file:
+                token_ret = file.readline()
+
+        token_ret = token_ret.replace("\n", "").replace("\r", "").strip()
+
+        if len(token_ret) > 40:
+            return token_ret
+
+        return None
+
+    @property
+    def base_url(self) -> str:
+        env_path = os.environ.get(self.KEY_VALUE.SIMULAC_BASE_URL.value, None)
+        if env_path is not None:
+            return env_path
+        else:
+            return self.BASE_URL
+
+    @property
+    def dev_mode(self) -> bool:
+        _dev_mode = os.environ.get("PYTHONDEVMODE", False)
+
+        if _dev_mode is False:
+            _dev_mode = True if sys.warnoptions == ["default"] else False
+        if isinstance(_dev_mode, str):
+            _dev_mode = True if _dev_mode == "1" else False
+        return _dev_mode

simulac-0.0.1/simulac/base/error/error.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+
+class SimulacBaseError(Exception):
+    def __init__(self, message: str, context: dict | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        if context:
+            self.context = context

simulac-0.0.1/simulac/base/instantiate/descriptor.py

@@ -0,0 +1,17 @@
+from typing import Any, Generic, List, Type, TypeVar
+
+from .instantiate import ServiceIdentifier
+
+T = TypeVar("T", bound=ServiceIdentifier[object])
+
+
+class SyncDescriptor(Generic[T]):
+    def __init__(
+        self,
+        ctor: Type[T] | object,
+        static_arguments: List[Any],
+        support_delayed_instantiation: bool,
+    ):
+        self.ctor = ctor
+        self.static_arguments = static_arguments
+        self.support_delayed_instantiation = support_delayed_instantiation

simulac-0.0.1/simulac/base/instantiate/extensions.py

@@ -0,0 +1,45 @@
+from abc import ABC, abstractmethod
+from enum import Enum
+from inspect import isclass, signature
+from typing import Any, Generic, List, MutableMapping, Tuple, Type, TypeVar
+
+from .descriptor import SyncDescriptor
+from .instantiate import ServiceIdentifier
+
+
+class InstantiateType(Enum):
+    EAGER = True
+    DELAYED = False
+
+
+_registry: List[Tuple[Type[ServiceIdentifier[object]], SyncDescriptor[Any]]] = []
+
+
+O = TypeVar("O", bound=object)
+
+
+def register_singleton[O](
+    interface: Type[ServiceIdentifier[O]],
+    descriptor: Type[object],
+    support_delayed_instantiation: InstantiateType = InstantiateType.DELAYED,
+):
+    if not issubclass(interface, ServiceIdentifier):
+        raise Exception("")
+
+    elif not isclass(descriptor):
+        raise Exception("")
+
+    elif not issubclass(descriptor, interface):
+        raise Exception("")
+
+    else:
+        _registry.append(
+            (
+                interface,
+                SyncDescriptor(descriptor, [], support_delayed_instantiation.value),
+            )
+        )
+
+
+def get_singleton_service_descriptors():
+    return _registry