holix-sdk 0.1.0__py3-none-any.whl

holix_sdk/__init__.py

@@ -0,0 +1,26 @@
+"""Holix SDK — stable public API for extension authors."""
+
+from holix_sdk.extension import (
+    CAPABILITY_AGENT,
+    CAPABILITY_CLI,
+    CAPABILITY_HTTP,
+    CAPABILITY_SIDECAR,
+    ExtensionBase,
+    ExtensionContext,
+    ExtensionInfo,
+    HolixExtension,
+)
+from holix_sdk.version import __api_version__, __version__
+
+__all__ = [
+    "__api_version__",
+    "__version__",
+    "CAPABILITY_AGENT",
+    "CAPABILITY_CLI",
+    "CAPABILITY_HTTP",
+    "CAPABILITY_SIDECAR",
+    "ExtensionBase",
+    "ExtensionContext",
+    "ExtensionInfo",
+    "HolixExtension",
+]

holix_sdk/agent.py

@@ -0,0 +1,62 @@
+"""Agent extension protocol — source of truth for Holix agent extensions."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+
+@dataclass(frozen=True, slots=True)
+class SlashCommandSpec:
+    """Slash command contributed by an agent extension."""
+
+    command: str
+    description: str
+
+
+@dataclass(frozen=True, slots=True)
+class AgentExtensionContext:
+    """Context passed to agent extensions during registration."""
+
+    profile_name: str
+    holix_version: str
+
+
+@runtime_checkable
+class AgentExtension(Protocol):
+    """Extension that augments the Holix agent runtime."""
+
+    name: str
+    version: str
+    requires_holix: str
+    permissions: frozenset[str]
+
+    def register_tools(self, registry: Any, agent: Any) -> None:
+        """Register additional tools on the agent ToolRegistry."""
+        ...
+
+    def register_slash_commands(self, commands: list[SlashCommandSpec]) -> None:
+        """Append slash commands (mutates the provided list)."""
+        ...
+
+    def augment_system_prompt(self, profile: str) -> str | None:
+        """Optional extra system prompt fragment for this profile."""
+        ...
+
+
+class AgentExtensionBase:
+    """Convenience base with defaults."""
+
+    name: str = ""
+    version: str = "0.0.0"
+    requires_holix: str = ">=0.1.0"
+    permissions: frozenset[str] = frozenset()
+
+    def register_tools(self, registry: Any, agent: Any) -> None:
+        return None
+
+    def register_slash_commands(self, commands: list[SlashCommandSpec]) -> None:
+        return None
+
+    def augment_system_prompt(self, profile: str) -> str | None:
+        return None

holix_sdk/agent_runtime.py

@@ -0,0 +1,39 @@
+"""Agent runtime types for host extensions."""
+
+from core.agent import HolixAgent
+from core.agent_events import (
+    AgentEvent,
+    AgentEventBus,
+    AssistantDeltaEvent,
+    ErrorEvent,
+    EventType,
+    FinalResponseEvent,
+    ThinkingEvent,
+    ToolCallErrorEvent,
+    ToolCallResultEvent,
+    ToolCallStartEvent,
+)
+from core.plan_review.review_events import PlanReviewRequestEvent
+from core.security.confirmation_events import ConfirmationRequestEvent, ConfirmationResponseEvent
+from core.subagents.interaction_events import SubAgentQuestionEvent
+from core.tools.file_diff import DIFF_SEPARATOR, format_write_file_result
+
+__all__ = [
+    "DIFF_SEPARATOR",
+    "AgentEvent",
+    "AgentEventBus",
+    "AssistantDeltaEvent",
+    "ConfirmationRequestEvent",
+    "ConfirmationResponseEvent",
+    "ErrorEvent",
+    "EventType",
+    "FinalResponseEvent",
+    "HolixAgent",
+    "PlanReviewRequestEvent",
+    "SubAgentQuestionEvent",
+    "ThinkingEvent",
+    "ToolCallErrorEvent",
+    "ToolCallResultEvent",
+    "ToolCallStartEvent",
+    "format_write_file_result",
+]

holix_sdk/commands.py

@@ -0,0 +1,5 @@
+"""Host command menu specs."""
+
+from core.host.command_menu import HostCommandSpec, command_specs, host_menu_commands
+
+__all__ = ["HostCommandSpec", "command_specs", "host_menu_commands"]

holix_sdk/extension.py

@@ -0,0 +1,90 @@
+"""Extension protocol — source of truth for Holix host extensions."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+CAPABILITY_CLI = "cli"
+CAPABILITY_HTTP = "http"
+CAPABILITY_SIDECAR = "sidecar"
+CAPABILITY_AGENT = "agent"
+
+ALL_CAPABILITIES = frozenset(
+    {CAPABILITY_CLI, CAPABILITY_HTTP, CAPABILITY_SIDECAR, CAPABILITY_AGENT}
+)
+
+
+@dataclass(frozen=True, slots=True)
+class ExtensionContext:
+    """Runtime context passed to extensions on startup."""
+
+    holix_version: str
+    data_dir: str
+    profile: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ExtensionInfo:
+    """Metadata for ``holix extensions list``."""
+
+    name: str
+    version: str
+    requires_holix: str
+    description: str
+    capabilities: frozenset[str]
+    permissions: frozenset[str]
+    package: str
+    entry_point: str
+    manifest_id: str | None = None
+
+
+@runtime_checkable
+class HolixExtension(Protocol):
+    """Optional package that plugs into Holix CLI, gateway, and/or agent runtime."""
+
+    name: str
+    version: str
+    requires_holix: str
+    description: str
+    capabilities: frozenset[str]
+    permissions: frozenset[str]
+
+    def register_cli(self, app: Any) -> None:
+        """Attach Typer subcommands to the root ``holix`` CLI."""
+        ...
+
+    def mount_gateway(self, app: Any) -> None:
+        """Attach FastAPI routes to the API gateway (no-op if disabled)."""
+        ...
+
+    def on_startup(self, ctx: ExtensionContext) -> None:
+        """Called once after extension discovery (CLI or gateway boot)."""
+        ...
+
+    def on_shutdown(self) -> None:
+        """Called on process exit (best-effort)."""
+        ...
+
+
+class ExtensionBase:
+    """Convenience base with defaults — subclass for new extensions."""
+
+    name: str = ""
+    version: str = "0.0.0"
+    requires_holix: str = ">=0.1.0"
+    description: str = ""
+    capabilities: frozenset[str] = frozenset()
+    permissions: frozenset[str] = frozenset()
+
+    def register_cli(self, app: Any) -> None:
+        return None
+
+    def mount_gateway(self, app: Any) -> None:
+        return None
+
+    def on_startup(self, ctx: ExtensionContext) -> None:
+        return None
+
+    def on_shutdown(self) -> None:
+        return None

holix_sdk/host.py

@@ -0,0 +1,32 @@
+"""Host bridge utilities — requires Holix installed."""
+
+from __future__ import annotations
+
+
+def __getattr__(name: str):
+    """Lazy import from Holix CLI (runtime dependency)."""
+    if name in {
+        "AgentCommands",
+        "TranscriptStore",
+        "all_slash_commands",
+        "content_to_plain_text",
+        "is_slash_command",
+        "normalize_slash_input",
+        "slash_commands_for_locale",
+    }:
+        from cli.shared.commands.agent_commands import AgentCommands
+        from cli.shared.commands.registry import all_slash_commands, slash_commands_for_locale
+        from cli.shared.rich_text import content_to_plain_text
+        from cli.shared.slash_input import is_slash_command, normalize_slash_input
+        from cli.tui.shared.transcript_store import TranscriptStore
+
+        return {
+            "AgentCommands": AgentCommands,
+            "TranscriptStore": TranscriptStore,
+            "all_slash_commands": all_slash_commands,
+            "content_to_plain_text": content_to_plain_text,
+            "is_slash_command": is_slash_command,
+            "normalize_slash_input": normalize_slash_input,
+            "slash_commands_for_locale": slash_commands_for_locale,
+        }[name]
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

holix_sdk/i18n.py

@@ -0,0 +1,5 @@
+"""Internationalization helpers."""
+
+from core.i18n import LocaleStore, host_locale, normalize_locale, t
+
+__all__ = ["LocaleStore", "host_locale", "normalize_locale", "t"]

holix_sdk/models.py

@@ -0,0 +1,25 @@
+"""Runtime model selection menus."""
+
+from core.models.menu import (
+    ModelChoice,
+    ModelsMenuState,
+    ProviderMenu,
+    apply_model_choice_sync,
+    build_models_menu,
+    choice_for_provider_model,
+    current_model_label,
+    is_slot_active,
+    resolve_model_config,
+)
+
+__all__ = [
+    "ModelChoice",
+    "ModelsMenuState",
+    "ProviderMenu",
+    "apply_model_choice_sync",
+    "build_models_menu",
+    "choice_for_provider_model",
+    "current_model_label",
+    "is_slot_active",
+    "resolve_model_config",
+]

holix_sdk/paths.py

@@ -0,0 +1,5 @@
+"""Safe path helpers."""
+
+from core.paths import realpath_under, resolve_holix_default_data_dir
+
+__all__ = ["realpath_under", "resolve_holix_default_data_dir"]

holix_sdk/profile.py

@@ -0,0 +1,5 @@
+"""Profile management."""
+
+from cli.core import ProfileManager, init_profile
+
+__all__ = ["ProfileManager", "init_profile"]

holix_sdk/security.py

@@ -0,0 +1,27 @@
+"""Security and approval helpers."""
+
+from cli.tui.web_security import (
+    WebTuiSecurityError,
+    WebTuiSecurityPolicy,
+    append_query_token,
+    build_web_tui_policy,
+    generate_web_token,
+    is_loopback_host,
+    token_valid,
+)
+from core.plan_review.review_guard import PlanReviewChoice, get_plan_review_guard
+from core.security.confirmation import ConfirmationChoice, get_action_guard
+
+__all__ = [
+    "ConfirmationChoice",
+    "PlanReviewChoice",
+    "WebTuiSecurityError",
+    "WebTuiSecurityPolicy",
+    "append_query_token",
+    "build_web_tui_policy",
+    "generate_web_token",
+    "get_action_guard",
+    "get_plan_review_guard",
+    "is_loopback_host",
+    "token_valid",
+]

holix_sdk/version.py

@@ -0,0 +1,4 @@
+"""SDK versioning — semantic API version separate from package version."""
+
+__api_version__ = 1
+__version__ = "0.1.0"

holix_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: holix-sdk
+Version: 0.1.0
+Summary: Stable public API for Holix extensions and host integrations
+Project-URL: Homepage, https://holix-agent.ru
+Project-URL: Repository, https://github.com/javded-itres/holix-sdk
+Project-URL: Documentation, https://github.com/javded-itres/holix-sdk/blob/main/docs/en/EXTENSIONS.md
+Project-URL: Issues, https://github.com/javded-itres/holix-sdk/issues
+Author: Pavel Lukyanov
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,extensions,holix,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Requires-Dist: holix>=0.1.21
+Description-Content-Type: text/markdown
+
+# holix-sdk
+
+[![CI](https://github.com/javded-itres/holix-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/javded-itres/holix-sdk/actions/workflows/ci.yml)
+
+**Separate installable package** — stable public API for [Holix](https://github.com/javded-itres/Holix) extension authors.
+
+Holix core (`core.*`, `cli.*`) is internal. Extension packages import **only** `holix_sdk`.
+
+## Install
+
+```bash
+pip install holix-sdk Holix
+```
+
+Requires [Holix](https://pypi.org/project/Holix/) `>=0.1.21` on PyPI.
+
+## API version
+
+```python
+from holix_sdk import __api_version__
+# Currently: 1
+```
+
+Breaking changes to the extension API happen only in major releases of `holix-sdk`.
+
+## Quick example
+
+```python
+from holix_sdk import ExtensionBase, CAPABILITY_CLI
+from holix_sdk.agent import AgentExtensionBase, SlashCommandSpec
+from holix_sdk.host import AgentCommands
+```
+
+## Documentation
+
+| Language | Guide |
+|----------|-------|
+| English | [docs/en/EXTENSIONS.md](docs/en/EXTENSIONS.md) |
+| Russian | [docs/ru/EXTENSIONS.md](docs/ru/EXTENSIONS.md) |
+
+## Development
+
+```bash
+git clone git@github.com:javded-itres/holix-sdk.git
+cd holix-sdk
+uv sync --group dev
+uv run pytest -q
+```
+
+## Publish
+
+Automated via GitHub Actions on tag `v*` — see [docs/PYPI.md](docs/PYPI.md).
+
+```bash
+# bump pyproject.toml + holix_sdk/version.py, then:
+git tag v0.1.0 && git push origin v0.1.0
+```
+
+Local check:
+
+```bash
+uv build && uv run twine check dist/*
+```
+
+PyPI package name: `holix-sdk`.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

holix_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+holix_sdk/__init__.py,sha256=76ms8k8enevh3kqkYWi0H1848LUKk16qzAs0jUXHL3Q,563
+holix_sdk/agent.py,sha256=wgD-zZ48Tr7aDBfgum-1m49B2-eLUOH87tLJ0ym8A0U,1665
+holix_sdk/agent_runtime.py,sha256=cnmhri4VihjtR-IZGFix6BogT24gPHr6ZJlE_GS-RUY,1066
+holix_sdk/commands.py,sha256=fkuv-93JxDTZVuMaymebkrnmfmD1NBHg9yKWPvAGjQ0,187
+holix_sdk/extension.py,sha256=tY8OTci7DDwXtqNq9ooOwCOPhRrODcNgbtXwuw0EGfU,2282
+holix_sdk/host.py,sha256=K2I_aMwYuTzzxFDZRetrh4xBjfEpWW9AHFq1YJFW8yM,1290
+holix_sdk/i18n.py,sha256=XT87W_2_fMyC-wdyJbqTHk1yfmLItKm3Atmo6MXXu-4,171
+holix_sdk/models.py,sha256=sPXpfQQSN5FP2Nlq9jN28uzKw6l45oaUU43m-mB6tC0,523
+holix_sdk/paths.py,sha256=wkXUf4uBCAHfQ6cw1I41dRBiaQG6RsDfJ1EdLbBCYLk,159
+holix_sdk/profile.py,sha256=L5VJ_TB3VgxFQoPZZ_pQecoJV423pquj63GrNO9x_F4,122
+holix_sdk/security.py,sha256=QmBC0enARSyib8EF_rIId55g_johSYeL9i373Qw1xj0,692
+holix_sdk/version.py,sha256=tbfjcpEYGPo4UV746bpUQcC7As-fo4e6JBc4qfzztf4,119
+holix_sdk-0.1.0.dist-info/METADATA,sha256=V_ntRQd5cX3GbK2Cf2WjdsQRV4p6ZupS5N7zPrXi2fw,2582
+holix_sdk-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+holix_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=dXfm47JSjiyn_TZ2tj2V_aT2svtkzByqbN9uqu9pIl4,1074
+holix_sdk-0.1.0.dist-info/RECORD,,

holix_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

holix_sdk-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Holix Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.