telekinesis-ai 0.0.1rc6
Official Telekinesis SDK for working with Telekinesis APIs.
Requires Python: <3.13,>=3.11

<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 its **initial release cycle**, published as release candidates (RC).

**Important: Please note that in this phase, the modules are introduced incrementally, and the versions are continuously evolving, therefore please always ensure you are on the latest version of the package.**

**Currently available modules:**
- `cornea`
- `vitreous`
- `pupil`

## Installation

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`.

## 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).