Metadata-Version: 2.4
Name: telekinesis-ai
Version: 0.2.5
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.31.0
Requires-Dist: loguru>=0.5.3
Requires-Dist: numpy>=2.0
Requires-Dist: requests-toolbelt
Requires-Dist: psutil
Requires-Dist: telekinesis-datatypes==0.2.2
Provides-Extra: medulla
Requires-Dist: telekinesis-medulla>=0.1.5; extra == "medulla"
Provides-Extra: medulla-ids
Requires-Dist: telekinesis-medulla[ids]>=0.1.5; extra == "medulla-ids"
Provides-Extra: synapse
Requires-Dist: telekinesis-synapse>=0.1.0; extra == "synapse"
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"
Provides-Extra: examples
Requires-Dist: rerun-sdk>=0.31.2; extra == "examples"
Provides-Extra: dev
Requires-Dist: ruff==0.15.8; extra == "dev"
Requires-Dist: pylint==4.0.5; extra == "dev"
Dynamic: license-file

<div align="center">
  <p>
    <a align="center" href="" target="_blank">
      <img
        width="100%"
        src="https://telekinesis-public-assets.s3.us-east-1.amazonaws.com/Telekinesis+Banner.png"
      >
    </a>
  </p>

  <br>

[Telekinesis Examples](https://github.com/telekinesis-ai/telekinesis-examples) | [Telekinesis Data](https://gitlab.com/telekinesis/telekinesis-data)
<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 Skill Library

The **Telekinesis Agentic Skill Library** is the first large-scale Python library for building agentic robotics, computer vision, and Physical AI systems. It provides:

- Skills: a broad set of AI algorithms for perception, motion planning, and control.
- Physical AI Agents: LLM/VLM agents for task planning across industrial, mobile, and humanoid robots.

The library is intended for robotics, computer vision, and research teams that want to:

- Speed up development by integrating production-grade robotics, computer vision, and AI algorithms
- Add intelligence to robots with LLM/VLM-driven task planning tied to real perception and control systems
- Iterate quickly on Physical AI systems using a single, consistent Python library

Learn more about the Telekinesis Agentic Skill Library in the
[About Telekinesis](https://docs.telekinesis.ai/).

Join our [Discord community](https://discord.gg/S5v8bYAnc6) to add your own skills and be part of the Physical AI revolution!

## Release Model

**The Telekinesis Agentic Skill 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`

## 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`:

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

3. Activate the environment:

   ```bash
   conda activate telekinesis
   ```

4. Install the core SDK using `pip`:

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

   ```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. You can install it as part of `telekinesis-ai` with:

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

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.

### `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.

**Supported platforms:** Windows, macOS

`synapse` depends on [Pinocchio](https://github.com/stack-of-tasks/pinocchio) for kinematics and [`telekinesis-urdfs`](https://github.com/telekinesis-ai/telekinesis-urdfs) for robot model data, both of which must be installed before the package.

1. Install Pinocchio via Conda:

   ```bash
   conda install conda-forge::pinocchio -y
   ```

2. 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.

3. Install `synapse` as part of `telekinesis-ai`:

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

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

## 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](/getting-started/quickstart.md) for more details on the generation of API key.

Continue to [Example section](#example) to quickly validate the installation.

## Example

**The following example assumes the API key has been generated and has been set as `TELEKINESIS_API_KEY` environment variable.**

Run a sample python code to quickly test your installation.

> **This example will fail if `TELEKINESIS_API_KEY` is not set correctly.**

1. Create a `Python` file named `telekinesis_ai_example.py` in a directory of your choice in your system, and copy paste the below:

   ```python
   import numpy as np
   from telekinesis import vitreous

   # Create a cylinder mesh
   cylinder_mesh = vitreous.create_cylinder_mesh(
   		radius=0.01,
   		height=0.02,
   		radial_resolution=20,
   		height_resolution=4,
   		retain_base=False,
   		vertex_tolerance=1e-6,
   		transformation_matrix=np.eye(4, dtype=np.float32),
   		compute_vertex_normals=True,
   	)

   # Convert it to point cloud
   point_cloud = vitreous.convert_mesh_to_point_cloud(
   		mesh=cylinder_mesh,
   		num_points=10000,
   		sampling_method="poisson_disk",
   		initial_sampling_factor=5,
   		initial_point_cloud=None,
   		use_triangle_normal=False,
   	)
   print(point_cloud.positions)
   # Use point_cloud in downstream processing or visualize the point cloud with any tool
   ```

2. On a terminal, navigate to the directory where the above file named `telekinesis_ai_example.py` has been created, run the below command:

   ```bash
   python telekinesis_ai_example.py
   ```

   Expected output:
   Some logs and random valued point cloud positions in the below format is output

   ```bash
   ...
   ...
   [[-0.00835031 -0.00536731 -0.00429686]
    [ 0.00854885  0.00497764  0.00044501]
    [ 0.00838172  0.00530565  0.00249433]
    ...
    [-0.00280485  0.00955575  0.00949276]
    [-0.00743726 -0.00653076 -0.00238814]
    [ 0.00023231 -0.00996321  0.00887559]]
   ```

You are now set up to build with Telekinesis.

The recommended way to explore Telekinesis Agentic Skill Library today is via the [Telekinesis Examples](https://github.com/telekinesis-ai/telekinesis-examples.git) repository, which contains fully runnable workflows built on top of the SDK.

## Resources

- Examples  
  Runnable examples demonstrating Telekinesis Agentic Skill Library capabilities: [Telekinesis Examples](https://github.com/telekinesis-ai/telekinesis-examples)

- Documentation  
  Full SDK documentation and usage details: [Telekinesis Documentation](https://docs.telekinesis.ai)

- Sample Data  
  Datasets used across the examples: [Telekinesis Data](https://gitlab.com/telekinesis/telekinesis-data)

## 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).
