Metadata-Version: 2.4
Name: telekinesis-ai
Version: 0.3.3
Summary: Official Telekinesis SDK for working with Telekinesis APIs.
Author-email: Telekinesis <support@telekinesis.ai>
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://telekinesis.ai
Project-URL: Documentation, https://docs.telekinesis.ai
Project-URL: Telekinesis Examples Repository, https://github.com/telekinesis-ai/telekinesis-examples
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.13,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: requests>=2.32.2
Requires-Dist: loguru>=0.6.0
Requires-Dist: numpy>=2.0
Requires-Dist: requests-toolbelt>=1.0.0
Requires-Dist: telekinesis-datatypes>=0.3.3
Requires-Dist: telekinesis-synapse>=0.1.0
Requires-Dist: telekinesis-medulla>=0.1.10
Requires-Dist: telekinesis-axon>=0.2.2
Requires-Dist: babyros>=0.1.0
Requires-Dist: telekinesis-tf>=0.1.5
Provides-Extra: medulla-ids
Requires-Dist: telekinesis-medulla[ids]>=0.1.10; extra == "medulla-ids"
Provides-Extra: medulla-realsense
Requires-Dist: telekinesis-medulla[realsense]>=0.1.10; extra == "medulla-realsense"
Provides-Extra: isaacsim
Requires-Dist: telekinesis-isaacsim-client>=0.1.2; extra == "isaacsim"
Provides-Extra: docs
Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
Requires-Dist: mkdocstrings[python]<1,>=0.25; extra == "docs"
Requires-Dist: mkdocs-awesome-pages-plugin<3,>=2; extra == "docs"
Requires-Dist: mkdocs-multirepo-plugin<0.9.0,>=0.7.0; extra == "docs"
Requires-Dist: telekinesis-medulla>=0.1.5; extra == "docs"
Requires-Dist: telekinesis-synapse>=0.1.0; extra == "docs"
Requires-Dist: telekinesis-isaacsim-client>=0.1.2; extra == "docs"
Provides-Extra: examples
Requires-Dist: rerun-sdk>=0.31.2; extra == "examples"
Requires-Dist: pycocotools; extra == "examples"
Requires-Dist: scipy; extra == "examples"
Provides-Extra: dev
Requires-Dist: ruff==0.15.8; extra == "dev"
Requires-Dist: pylint==4.0.5; extra == "dev"
Requires-Dist: psutil; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Dynamic: license-file

<div align="center">
  <p>
    <a align="center" href="" target="_blank">
      <img
        width="100%"
        src="https://assets.telekinesis.ai/Telekinesis+Banner.png"
      >
    </a>
  </p>

  <br>

[![PyPI version](https://img.shields.io/pypi/v/telekinesis-ai)](https://pypi.org/project/telekinesis-ai/)
[![License](https://img.shields.io/pypi/l/telekinesis-ai)](https://pypi.org/project/telekinesis-ai/)
[![Python versions](https://img.shields.io/pypi/pyversions/telekinesis-ai)](https://pypi.org/project/telekinesis-ai/)

</div>

<p align="center">
  <a href="https://github.com/telekinesis-ai">GitHub</a>
  &nbsp;•&nbsp;
  <a href="https://www.linkedin.com/company/telekinesis-ai/">LinkedIn</a>
  &nbsp;•&nbsp;
  <a href="https://x.com/telekinesis_ai">X</a>
  &nbsp;•&nbsp;
  <a href="https://discord.gg/7NnQ3bQHqm">Discord</a>
</p>

# Telekinesis Agentic OS

Telekinesis is the Agentic OS for general-purpose robots. It provides a unified Python library that brings the entire Physical AI stack together: Vision-Language-Action models, World Models, perception, planning, hardware interfaces, and more.

Learn more about all available modules in detail in [docs.telekinesis.ai](https://docs.telekinesis.ai/). Join our [Discord community](https://discord.gg/S5v8bYAnc6) to connect, share, and build together.

## Release Model

**Telekinesis Agentic OS library is currently in active development (pre-1.0).  
Modules are introduced incrementally, and the API may evolve between minor releases.    
To ensure compatibility and access to the latest capabilities, always install or upgrade to the most recent version of the package.**

**Currently available modules:**

- `cornea`
- `retina`
- `pupil`
- `vitreous`
- `medulla`
- `synapse`
- `babyros`
- `datatypes`
- `isaacsim`
- `axon`
- `tf`

## Getting Started

**Telekinesis SDK requires a free API key to authenticate requests.**

Create one at [platform.telekinesis.ai](https://platform.telekinesis.ai/api-keys). See the [Quickstart](https://docs.telekinesis.ai/getting-started/quickstart.html) for more details on the generation of API key.


## Installation

### Core SDK

1. Create an isolated environment so that there is no dependency conflicts. We recommend installing `Miniconda` environment by following instructions from [here](https://docs.conda.io/en/latest/miniconda.html#installing).

2. Create a new `conda` environment called `telekinesis`:

   **We currently support Python versions - 3.11, 3.12. Ensure your environment is in the specified Python version.**

   ```bash
   conda create -n telekinesis python=3.11
   ```

3. Activate the environment:

   ```bash
   conda activate telekinesis
   ```

4. Install the core SDK using `pip`:

   ```bash
   pip install telekinesis-ai
   ```

   Note: The Python module is called `telekinesis`, while the package published on PyPI is `telekinesis-ai`.

### `medulla`

[`medulla`](https://pypi.org/project/telekinesis-medulla/#description) is a module in the Telekinesis SDK for connecting to cameras and hardware devices. It is installed by default as part of `telekinesis-ai`, with webcam support included out of the box:

```bash
pip install telekinesis-ai
```

In order to install vendor specific dependencies, please follow the official documentation on https://docs.telekinesis.ai/medulla/overview.html, e.g. for using IDS cameras with `medulla`:

```bash
pip install telekinesis-ai[medulla-ids]
```

You can find the list of supported vendors in the overview section under [supported cameras](https://docs.telekinesis.ai/medulla/overview.html#supported-cameras).

See the official `medulla` [documentation](https://docs.telekinesis.ai/medulla/overview.html#installation) for more details about the installation.

**IDS cameras:** Installing the `ids` extras (`pip install telekinesis-ai[medulla-ids]`) fetches `ids_peak`, `ids_peak_ipl`, and `ids_peak_icv` directly from IDS Imaging Development Systems GmbH's own PyPI distribution. By installing these packages, you become the licensee under the [IDS Software Suite License Terms](https://www.ids-imaging.com) and are bound by its conditions.

**RealSense cameras:** Installing the `realsense` extras (`pip install telekinesis-ai[medulla-realsense]`) fetches `pyrealsense2` directly from Intel's PyPI distribution. By installing this package, you become the licensee under the [Intel RealSense SDK 2.0 License Terms](https://github.com/IntelRealSense/librealsense/blob/master/LICENSE) and are bound by its conditions.

### `synapse`

[`synapse`](https://pypi.org/project/telekinesis-synapse/) is a module in the Telekinesis SDK for controlling and communicating with industrial robot manipulators and tools. It provides a unified API across multiple robot and tool brands. It is installed by default as part of `telekinesis-ai`.

**Robot support:**

- **Offline (simulation):** all supported robots
- **Real-world (hardware control):** Universal Robots only

**Supported platforms:** Windows, macOS

`synapse` depends on [`telekinesis-urdfs`](https://github.com/telekinesis-ai/telekinesis-urdfs) for robot model data, which must be installed before `telekinesis-ai`.

1. Install `telekinesis-urdfs`:

   ```bash
   git clone --depth 1 https://github.com/telekinesis-ai/telekinesis-urdfs.git
   cd telekinesis-urdfs
   pip install .
   ```

   > **Note:** `telekinesis-urdfs` is a large repository containing robot model data. The initial clone and wheel build are expected to take several minutes — do not interrupt the process.

2. Install `telekinesis-ai` (which includes `synapse`):

   ```bash
   pip install telekinesis-ai
   ```

See the official `synapse` [documentation](https://docs.telekinesis.ai/synapse/overview.html) for more details about the installation and supported robots.

### `isaacsim`

**`isaacsim` is currently under active development.** It is a module in the Telekinesis SDK for connecting to NVIDIA Isaac Sim through the Telekinesis Isaac Sim bridge (a Python client built on a C++ core). It is an optional dependency — install it with the `isaacsim` extra:

```bash
pip install telekinesis-ai[isaacsim]
```

**Supported platforms:** Windows (macOS and Linux support coming soon)


## Example

**Important: `TELEKINESIS_API_KEY` is required for the below to run successfully.**

### Vision Module

Run below to test `retina` module:

```python
from telekinesis import retina, datatypes

image_url = "https://assets.telekinesis.ai/examples/v1/images/palletizing.jpg"
image = datatypes.Image.from_url(url=image_url)

detection_results, categories = retina.detect_objects_using_grounding_dino(
    image=image,
    objects=["carton"],
    box_threshold=0.45,
    text_threshold=0.5,
)

detection_results
```

### IsaacSim 

Run below to test `isaacsim_client` connection:

```python
from telekinesis.isaacsim_client import IsaacSimClient

client = IsaacSimClient(
    api_key="",
    base_url="http://127.0.0.1:8766",
    websocket_base_url="ws://127.0.0.1:8766",
)

created = client.articulation.create("/World/ur10e")
print(created["articulation_id"])

client.articulation.set_joint_positions(created["articulation_id"], [0.0] * created["num_dof"])
```
More examples are available on [Telekinesis Isaac Sim Examples](https://github.com/telekinesis-ai/isaacsim-examples)

## Resources

- All module examples are available in [Telekinesis Examples](https://github.com/telekinesis-ai/telekinesis-examples)
- Full SDK documentation and usage details: [Telekinesis Documentation](https://docs.telekinesis.ai)

## Support

For issues and questions:

- Create an [issue](https://github.com/telekinesis-ai/telekinesis-examples/issues) in the GitHub repository.
- Contact the Telekinesis development team at support@telekinesis.ai or on [Discord](https://discord.com/invite/7NnQ3bQHqm).
