Metadata-Version: 2.5
Name: kabaret.ipc
Version: 1.0.0
Summary: IPC Server to communicate with Kabaret sessions
Project-URL: Repository, https://gitlab.com/kabaretstudio/kabaret.ipc
Project-URL: Issues, https://gitlab.com/kabaretstudio/kabaret.ipc/-/issues
Author-email: Valentin Braem <contact@valentinbraem.me>
License-Expression: LGPL-3.0-or-later
License-File: COPYING
License-File: LICENSE
Keywords: animation,api,dcc,fastapi,ipc,kabaret,pipeline,plugin,rest,vfx,websocket
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Requires-Python: >=3.10
Requires-Dist: fastapi
Requires-Dist: kabaret
Requires-Dist: uvicorn
Requires-Dist: websockets
Description-Content-Type: text/markdown

# kabaret.ipc
----
A plugin that packs a local `FastAPI` server, so any external tool such as DCCs, production trackers, etc. can talk to any Kabaret session.

## Installation
```
uv add kabaret.ipc
```
Add the package to your existing virtual environment, and Kabaret loads the plugin entry point automatically. Requires Python 3.10 or newer.

## Quick start
The server writes where it listens and how to authenticate in `~/.kabaret/ipc/server.json`:
```json
{"host": "127.0.0.1", "port": 51234, "token": "...", "pid": 12345}
```
The OS picks the port at each start, so you need to read that file to find the server. The token goes in an `Authorization: Bearer <token>` header on every request.

```python
import json
from pathlib import Path

import requests

info = json.loads((Path.home() / ".kabaret" / "ipc" / "server.json").read_text())

response = requests.post(
    f"http://{info['host']}:{info['port']}/cmds/Flow/resolve_path",
    headers={"Authorization": f"Bearer {info['token']}"},
    json={"kwargs": {"oid": "/my_project/films"}},
)
print(response.json()["result"])
```

## Usage
The first Kabaret session to start spawns the server on an open port, if none is already running. Every session then connects to it through a websocket.

The server stays up as long as one session is connected. When the last one disconnects, a 30sec cooldown starts and shuts the process down, unless a session shows up in the meantime.

If the server crashes or is closed by accident, sessions lose their websocket and try to relaunch it, retrying every two seconds.

Each run writes what it logs to its own file, `~/.kabaret/ipc/logs/ipc-{date}.log`, alongside the console output. Only the five most recent are kept.

## Routes
The full schema is served by FastAPI at `http://{host}:{port}/docs`.

* `GET` - `/sessions`:
  * Returns the active sessions, keyed by session uid: their name, the cluster used and, for GUI sessions, the current oid of the active view.
* `POST` - `/cmds/{actor_name}/{cmd_name}`
  * A single route to use any command from any loaded Actor, i.e. `session.cmds.<actor_name>.<cmd_name>(*args, **kwargs)`.
  * Body: `{"args": [...], "kwargs": {...}}`, needed only if the command takes arguments.
  * `session_uid` is a query parameter. If it is left out and only one session is running, the server automatically uses it.
  * Returns `{"result": ...}`, or an error below.

| Status | Cause |
| --- | --- |
| 400 | several sessions are connected and no `session_uid` was given |
| 401 | missing or invalid token |
| 404 | unknown actor or command |
| 422 | arguments don't match the command signature |
| 500 | the command raised |
| 504 | the session did not reply within 10sec |

`/ws/{session_uid}` is the websocket Kabaret sessions register on. It is internal: external tools use the HTTP routes.

## Security
So that only trusted processes can reach it, the server generates a token and stores it in `~/.kabaret/ipc/server.json`.
Any utility needs to read that file to know how to use the local server.

The server only listens on `127.0.0.1` and the token is regenerated at each server start.

## Resources
[Kabaret IPC Blender Bridge](https://gitlab.com/kabaretstudio/kabaret.ipc_blender_bridge)

## Support
[Discord server](https://discord.gg/NmJDHsN)
