🐝 Imperal Quantum SDK (`imperal-sdk`)

The Official Next-Gen AI Cloud OS Framework for Imperal Cloud & Webbee 🐝

Write autonomous, context-aware AI tools and extensions in pure Python. Zero manifests. 0 lines of JSON. Automatic reactive UI. Ambient cloud context. Multi-surface morphing across Terminal, Web Panel, Telegram, and Voice.

Documentation · ICNLI Protocol Spec · Imperal Cloud Panel · Marketplace

🌌 Квантовый скачок: Забудьте старый мир AI-агентов

В мире Web2 и раннего AI разработка инструментов для агентов превратилась в бюрократический ад:

❌ Ручное написание сотен строк manifest.json и громоздких схем JSON Schema.
❌ Многоэтажные абстрактные классы, жесткие интерфейсы и куча клея.
❌ Необходимость держать отдельную команду фронтендеров, чтобы отрисовать результаты работы инструмента в веб-панели.
❌ Потеря контекста между поверхностями: то, что работает в CLI, ломается в вебе и Telegram.

⚡ Встречайте ICNLI Quantum SDK v6.0

Imperal Quantum SDK делает для автономных облачных ИИ-агентов то же, что FastAPI сделал для веб-сервисов — переводит разработку на квантовый мета-уровень:

Zero-Manifest (0 строк JSON): Манифест приложения, типы аргументов, описания для нейросетей, RBAC-скоупы и правила биллинга синтезируются автоматически из стандартных Python type-hints и docstrings.
Auto-IR (UI-as-Data): Вы просто возвращаете Python-словарь или структуру — а ядро Imperal Cloud на лету проецирует её в реактивные Declarative UI карточки, таблицы и метрики без единой строчки фронтенд-кода!
Ambient Context Injection: Контекст сессии (Context), кошелек пользователя, защищенное хранилище (Store), файловая система (Storage) и доступ к LLM (AI) инжектируются невидимо для нейросетей, не засоряя промпт токенами.
Liquid Multi-Surface Morphing: Один и тот же инструмент нативно адаптируется под Терминал (TUI), Веб-панель (Declarative Cards), Telegram (Inline-кнопки) и Голос (Voice Synthesizer).
100% Обратная совместимость: Полная поддержка классических корпоративных расширений на imperal_sdk.Extension (1630+ тестов на 100% PASS).

🚀 Быстрый старт за 60 секунд

1. Установка

pip install imperal-sdk

2. Ваше первое приложение за 15 строк (`server_pulse.py`)

from imperal_sdk import App, Context

# Создаем квантовое приложение — манифест уже готов!
app = App("server-pulse", name="Server Pulse", category="devops")

@app.tool(pricing=5, destructive=False)
def check_host(host: str, port: int = 443, ctx: Context = None) -> dict:
    """Проверить доступность сервера и статус SSL сертификата в реальном времени."""
    # Чистая бизнес-логика:
    is_online = True
    ssl_days = 89
    
    # Возвращаем данные — ядро САМО построит интерактивный UI!
    return {
        "status": "online" if is_online else "down",
        "host": host,
        "ssl_days": ssl_days,
        "metric": f"{ssl_days} days left"
    }

Что произошло автоматически под капотом?

✅ Сгенерирован валидный ICNLI Manifest v6.0.
✅ Аргументы host и port превращены в типизированную JSON Schema.
✅ Docstring стал описанием для ИИ-мозга Webbee.
✅ Зарегистрирован RBAC-скоуп server-pulse:check_host.
✅ Аргумент ctx: Context скрыт от LLM, но готов к работе в рантайме.
✅ Результат выполнения в панели panel.imperal.io автоматически отобразится как стильная адаптивная Metric Card с бейджем и статусом!

💎 Главные квантовые суперсилы

1. ⚡ Автоматический синтез схем (Type-to-Schema Engine)

Больше никаких ручных JSON-схем. Пишите идиоматичный Python:

from typing import List, Optional

@app.tool()
async def deploy_services(
    environment: str, 
    replicas: int = 3, 
    tags: Optional[List[str]] = None,
    dry_run: bool = False
) -> dict:
    """Развернуть микросервисы в целевом окружении с авто-масштабированием."""
    ...

SDK автоматически построит:

{
  "name": "deploy_services",
  "description": "Развернуть микросервисы в целевом окружении с авто-масштабированием.",
  "parameters": {
    "type": "object",
    "properties": {
      "environment": {"type": "string"},
      "replicas": {"type": "integer", "default": 3},
      "tags": {"type": "array", "items": {"type": "string"}},
      "dry_run": {"type": "boolean", "default": false}
    },
    "required": ["environment"]
  }
}

2. 🎨 Auto-IR: UI-as-Data (Фронтенд без фронтендеров)

Ядро Imperal Cloud понимает возвращаемые типы данных и мгновенно проецирует их в Declarative UI:

Что вы возвращаете из функции	Как это выглядит в Imperal Panel
`{"status": "ok", "metric": "99.9%", ...}`	🎴 Metric Card: стильная карточка с бейджем, трендом и деталями
`[{"id": 1, "name": "srv-1", "cpu": 12}, ...]`	📊 Data Table: адаптивная таблица с сортировкой и фильтрами
`{"_ui": {"type": "custom", ...}}`	🧩 Custom IR: полный контроль над Declarative UI деревом

3. 🔮 Ambient Context: Невидимый доступ ко всей Cloud OS

Параметр ctx: Context скрыт от нейросети (не тратит токены промпта!), но внутри функции предоставляет суперсилы всей операционной системы:

@app.tool()
async def analyze_logs(service_name: str, ctx: Context = None) -> dict:
    # 1. Доступ к защищенному хранилищу ключ-значение (Redis):
    await ctx.store.set(f"last_scan:{service_name}", "in_progress")
    
    # 2. Обращение к встроенному ИИ-мозгу Webbee (LLM):
    ai_verdict = await ctx.ai.complete(f"Проанализируй аномалии сервиса {service_name}")
    
    # 3. Данные текущего пользователя и организации:
    user_email = ctx.user.email
    tenant_id = ctx.user.tenant_id
    
    return {"analysis": ai_verdict.text, "analyzed_by": user_email}

4. 🔀 Multi-Surface Morphing: Единая логика на всех устройствах

Webbee работает везде. SDK автоматически адаптирует презентацию:

Терминал (Webbee Code TUI): компактный вывод, псевдографика, нумерованные хоткеи.
Веб-консоль (Imperal Panel): живые графики, интерактивные формы, таблицы.
Telegram Bot: мобильные карточки с callback-кнопками.
Voice / Ambient: лаконичный голосовой синтез ключевых фактов.

5. 🔗 Unix-Piping между расширениями

Инструменты разных расширений можно объединять в конвейеры данных прямо в чате:

"Webbee, возьми домены из DNS-чекера, прогони через SSL-аудитор и отправь алерт в Telegram"

Благодаря типизированным контрактам входов и выходов, расширения стыкуются между собой как детали Lego.

🧪 Герметичное тестирование без интернета

В SDK встроен автономный тестовый набор (autonomous_mock), позволяющий прогонять тесты за миллисекунды:

import pytest
from imperal_sdk.testing.autonomous_mock import MockContext
from server_pulse import check_host

def test_check_host():
    mock_ctx = MockContext(user_id="imp_u_test", role="admin")
    result = check_host(host="imperal.io", ctx=mock_ctx)
    
    assert result["status"] == "online"
    assert "_ui" in result
    assert result["_ui"]["type"] == "metric_card"

Запуск:

pytest -v

🏗️ Архитектура Imperal Cloud OS

                     ┌───────────────────────────────┐
                     │          Webbee Brain         │
                     │    (Agentic AI Reasoning)     │
                     └───────────────┬───────────────┘
                                     │ Intent & Tool Calls
                                     ▼
                     ┌───────────────────────────────┐
                     │    ICNLI Quantum SDK v6.0     │
                     │   imperal_sdk.App / Extension │
                     └───────────────┬───────────────┘
                                     │ Declarative IR & Telemetry
                ┌────────────────────┼────────────────────┐
                ▼                    ▼                    ▼
        ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
        │ Imperal Panel│     │  Webbee Code │     │   Telegram   │
        │   (Web UI)   │     │ (Terminal)   │     │  (Messenger) │
        └──────────────┘     └──────────────┘     └──────────────┘

📜 Совместимость и требования

Python: 3.10, 3.11, 3.12, 3.13+
Зависимости: ультра-легковесный кор, отсутствие тяжелых зависимостей в рантайме.
Стандарты: 100% совместимость со спецификацией ICNLI Protocol.
Лицензия: Apache-2.0.

Imperal Cloud — The First Autonomous ICNLI AI Cloud OS.
Создано с любовью, дерзостью и 🐝 командой Imperal, Valentin Scerbacov и открытым сообществом.

Release files for imperal-sdk 6.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for imperal-sdk 6.0.0
File	Size	Uploaded
imperal_sdk-6.0.0.tar.gz	853.6 kB	Sep 26, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for imperal-sdk 6.0.0
File	Interpreter	ABI	Platform	Reset
imperal_sdk-6.0.0-py3-none-any.whl 381.9 kB Sep 26, 2026	Python 3	none	any	Details

Total release size: 1.2 MB

Release files / imperal_sdk-6.0.0.tar.gz

Download URL	imperal_sdk-6.0.0.tar.gz
Size	853.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`74d44527a47410ebd615c09d957fba473ecd46c8d079cd7f5df6d105ab2b27f7`
BLAKE2b-256 checksum How to use checksums	`9917e20b635e9f6dddd264a664e3ae36250945da7cd9431e597b6bd876c8236f`
Upload date	Sep 26, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/imperalcloud/imperal-sdk
Publishing commit: github.com/imperalcloud/imperal-sdk/tree/95bbbaab28d107aa4b34bdbaad95775fdf707c12

Workflow

Publishing configuration: github.com/imperalcloud/imperal-sdk/blob/95bbbaab28d107aa4b34bdbaad95775fdf707c12/.github/workflows/publish.yml
Publishing logs: github.com/imperalcloud/imperal-sdk/actions/runs/36226284809/attempts/1

Artifact

Subject: imperal_sdk-6.0.0.tar.gz
SHA-256 checksum: 74d44527a47410ebd615c09d957fba473ecd46c8d079cd7f5df6d105ab2b27f7 Verifying attestations

Release files / imperal_sdk-6.0.0-py3-none-any.whl

Download URL	imperal_sdk-6.0.0-py3-none-any.whl
Size	381.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`8512f8a26d4c7bfbd55cee6369525234da8e3330e8ef76dd662ff08dc0792ad8`
BLAKE2b-256 checksum How to use checksums	`49ecc0c3fbc53e9df38b63c96e3dd21af99c86416ef22599b9cb8fd2d5f443bf`
Upload date	Sep 26, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/imperalcloud/imperal-sdk
Publishing commit: github.com/imperalcloud/imperal-sdk/tree/95bbbaab28d107aa4b34bdbaad95775fdf707c12

Workflow

Publishing configuration: github.com/imperalcloud/imperal-sdk/blob/95bbbaab28d107aa4b34bdbaad95775fdf707c12/.github/workflows/publish.yml
Publishing logs: github.com/imperalcloud/imperal-sdk/actions/runs/36226284809/attempts/1

Artifact

Subject: imperal_sdk-6.0.0-py3-none-any.whl
SHA-256 checksum: 8512f8a26d4c7bfbd55cee6369525234da8e3330e8ef76dd662ff08dc0792ad8 Verifying attestations