hestiaos 0.1.0__tar.gz

hestiaos-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HestiaOS 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.

hestiaos-0.1.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: hestiaos
+Version: 0.1.0
+Summary: HestiaOS SDK — Domain Interface for the HestiaOS platform
+Author: HestiaOS Team
+License-Expression: MIT
+Project-URL: Homepage, https://hestiaos.local
+Project-URL: Source, https://gitlab.com/hestiaos/hestiaos
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: typer>=0.12.0
+Dynamic: license-file
+
+# 🏠 HestiaOS SDK
+
+**Python SDK for the HestiaOS platform** — deterministic governance, multi-agent orchestration, and local-first AI execution.
+
+[![PyPI version](https://img.shields.io/pypi/v/hestiaos)](https://pypi.org/project/hestiaos/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/hestiaos)](https://pypi.org/project/hestiaos/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+---
+
+## Installation
+
+```bash
+pip install hestiaos
+```
+
+Requires Python 3.11+.
+
+---
+
+## Quickstart
+
+### Python Client
+
+```python
+from hestiaos import Client
+
+client = Client(base_url="http://localhost:8000")
+
+# Run a command through the governance pipeline
+result = client.run("create a report")
+print(result.result)      # "processed: create a report"
+print(result.trace_id)    # "abc-123-def"
+print(result.mode)        # "ALLOW"
+
+# Check system health
+status = client.system.status()
+print(status.status)      # "healthy"
+
+# Retrieve a governance trace
+trace = client.governance.trace("abc-123-def")
+```
+
+### CLI
+
+```bash
+# Run a command
+hestiaos run "create a report"
+
+# Check server health
+hestiaos health
+
+# Retrieve a trace
+hestiaos trace abc-123-def
+
+# JSON output (pipe to jq)
+hestiaos run "hello" --json | jq
+
+# Custom server URL
+hestiaos --base-url http://localhost:8000 health
+```
+
+---
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `hestiaos run <text>` | Execute a command through the governance pipeline |
+| `hestiaos trace <id>` | Retrieve a governance trace by ID |
+| `hestiaos health` | Check server health status |
+
+| Global Option | Description |
+|---------------|-------------|
+| `--base-url, -u` | API base URL (default: `http://localhost:8000`) |
+| `--api-key, -k` | API key for authentication |
+| `--json, -j` | Output as raw JSON |
+
+---
+
+## API
+
+### `Client(base_url, api_key=None)`
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `client.run(input_text)` | `RunResponse` | Execute through governance pipeline |
+| `client.governance.trace(trace_id)` | `dict \| None` | Retrieve governance trace |
+| `client.governance.explain(command_type, command_input)` | `dict` | Explain a governance decision |
+| `client.system.status()` | `SystemStatus` | Server health status |
+
+### Models
+
+- **`RunResponse`**: `result`, `trace_id`, `output`, `mode`, `budget`, `latency_ms`
+- **`TraceResponse`**: `trace_id`, `decision`, `violations`, `latency_ms`
+- **`HealthResponse`**: `status`, `version`, `uptime_seconds`
+- **`GovernanceBlock`**: Raised when governance blocks execution
+
+---
+
+## Development
+
+```bash
+# Clone and install
+git clone <repo-url> && cd hestiaos
+python -m venv venv && source venv/bin/activate
+pip install -e .
+
+# Run tests
+pytest tests/test_sdk_client.py tests/test_cli.py -v
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

hestiaos-0.1.0/README.md

@@ -0,0 +1,117 @@
+# 🏠 HestiaOS SDK
+
+**Python SDK for the HestiaOS platform** — deterministic governance, multi-agent orchestration, and local-first AI execution.
+
+[![PyPI version](https://img.shields.io/pypi/v/hestiaos)](https://pypi.org/project/hestiaos/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/hestiaos)](https://pypi.org/project/hestiaos/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+---
+
+## Installation
+
+```bash
+pip install hestiaos
+```
+
+Requires Python 3.11+.
+
+---
+
+## Quickstart
+
+### Python Client
+
+```python
+from hestiaos import Client
+
+client = Client(base_url="http://localhost:8000")
+
+# Run a command through the governance pipeline
+result = client.run("create a report")
+print(result.result)      # "processed: create a report"
+print(result.trace_id)    # "abc-123-def"
+print(result.mode)        # "ALLOW"
+
+# Check system health
+status = client.system.status()
+print(status.status)      # "healthy"
+
+# Retrieve a governance trace
+trace = client.governance.trace("abc-123-def")
+```
+
+### CLI
+
+```bash
+# Run a command
+hestiaos run "create a report"
+
+# Check server health
+hestiaos health
+
+# Retrieve a trace
+hestiaos trace abc-123-def
+
+# JSON output (pipe to jq)
+hestiaos run "hello" --json | jq
+
+# Custom server URL
+hestiaos --base-url http://localhost:8000 health
+```
+
+---
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `hestiaos run <text>` | Execute a command through the governance pipeline |
+| `hestiaos trace <id>` | Retrieve a governance trace by ID |
+| `hestiaos health` | Check server health status |
+
+| Global Option | Description |
+|---------------|-------------|
+| `--base-url, -u` | API base URL (default: `http://localhost:8000`) |
+| `--api-key, -k` | API key for authentication |
+| `--json, -j` | Output as raw JSON |
+
+---
+
+## API
+
+### `Client(base_url, api_key=None)`
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `client.run(input_text)` | `RunResponse` | Execute through governance pipeline |
+| `client.governance.trace(trace_id)` | `dict \| None` | Retrieve governance trace |
+| `client.governance.explain(command_type, command_input)` | `dict` | Explain a governance decision |
+| `client.system.status()` | `SystemStatus` | Server health status |
+
+### Models
+
+- **`RunResponse`**: `result`, `trace_id`, `output`, `mode`, `budget`, `latency_ms`
+- **`TraceResponse`**: `trace_id`, `decision`, `violations`, `latency_ms`
+- **`HealthResponse`**: `status`, `version`, `uptime_seconds`
+- **`GovernanceBlock`**: Raised when governance blocks execution
+
+---
+
+## Development
+
+```bash
+# Clone and install
+git clone <repo-url> && cd hestiaos
+python -m venv venv && source venv/bin/activate
+pip install -e .
+
+# Run tests
+pytest tests/test_sdk_client.py tests/test_cli.py -v
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

hestiaos-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hestiaos"
+version = "0.1.0"
+description = "HestiaOS SDK — Domain Interface for the HestiaOS platform"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+    {name = "HestiaOS Team"},
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27.0",
+    "typer>=0.12.0",
+]
+
+[project.scripts]
+hestiaos = "hestiaos.cli:main"
+
+[project.urls]
+Homepage = "https://hestiaos.local"
+Source = "https://gitlab.com/hestiaos/hestiaos"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["hestiaos*"]
+
+[tool.setuptools.package-data]
+hestiaos = ["py.typed"]

hestiaos-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hestiaos-0.1.0/setup.py

@@ -0,0 +1,7 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="hestiaos-core",
+    version="1.0.0",
+    packages=find_packages(),
+)

hestiaos-0.1.0/src/hestiaos/__init__.py

@@ -0,0 +1,51 @@
+"""
+HestiaOS SDK — Domain Interface für die HestiaOS-Plattform.
+
+Das SDK ist Resource-Oriented, nicht API-Wrapper-lastig.
+Jeder Resource-Namespace ist ein Attribut des Client-Objekts.
+Der Client mapped auf typed Commands, nicht direkt auf HTTP.
+
+Usage:
+    from hestiaos import Client
+
+    client = Client(base_url="http://localhost:8000")
+    response = client.chat.send("Hello!")
+    status = client.system.status()
+    decision = client.governance.explain("WRITE")
+    result = client.run("Hello, world!")
+"""
+
+from __future__ import annotations
+
+from .client import (
+    AgentResult,
+    ChatResponse,
+    Client,
+    SystemMetrics,
+    SystemStatus,
+)
+from .errors import GovernanceBlock, HestiaError, InvalidInput, NotFound
+from .models import (
+    ErrorResponse,
+    HealthResponse,
+    RunResponse,
+    TraceResponse,
+)
+from .version import __version__
+
+__all__ = [
+    "Client",
+    "ChatResponse",
+    "AgentResult",
+    "SystemStatus",
+    "SystemMetrics",
+    "RunResponse",
+    "TraceResponse",
+    "HealthResponse",
+    "ErrorResponse",
+    "HestiaError",
+    "GovernanceBlock",
+    "InvalidInput",
+    "NotFound",
+    "__version__",
+]

hestiaos-0.1.0/src/hestiaos/cli.py

@@ -0,0 +1,134 @@
+"""
+HestiaOS CLI — Typer-basierte Kommandozeile.
+
+Usage:
+    hestiaos --help
+    hestiaos run "create report"
+    hestiaos trace abc123
+    hestiaos health
+    hestiaos --base-url http://localhost:8000 run "hello" --json
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, NoReturn, Optional
+
+import typer
+
+from hestiaos import Client, GovernanceBlock
+
+app = typer.Typer(
+    name="hestiaos",
+    help="HestiaOS CLI — Interact with the HestiaOS platform.",
+    no_args_is_help=True,
+)
+
+
+# ── Globale Callback-Optionen ───────────────────────────────────────
+@app.callback()
+def _main(
+    ctx: typer.Context,
+    base_url: Optional[str] = typer.Option(
+        None, "--base-url", "-u", help="HestiaOS API base URL (default: http://localhost:8000)"
+    ),
+    api_key: Optional[str] = typer.Option(
+        None, "--api-key", "-k", help="API key for authentication"
+    ),
+    json_output: bool = typer.Option(
+        False, "--json", "-j", help="Output as raw JSON"
+    ),
+) -> None:
+    """Globale Optionen für alle CLI-Commands."""
+    ctx.ensure_object(dict)
+    ctx.obj["base_url"] = base_url or "http://localhost:8000"
+    ctx.obj["api_key"] = api_key
+    ctx.obj["json_output"] = json_output
+
+
+# ── Hilfsfunktionen ─────────────────────────────────────────────────
+def _make_client(ctx: typer.Context) -> Client:
+    """Erzeugt einen Client aus den globalen Optionen."""
+    opts = ctx.obj
+    return Client(
+        base_url=opts["base_url"],
+        api_key=opts.get("api_key"),
+    )
+
+
+def _print_result(ctx: typer.Context, data: dict[str, Any]) -> None:
+    """Gibt das Ergebnis aus — entweder als JSON oder als Text."""
+    if ctx.obj["json_output"]:
+        print(json.dumps(data, indent=2, default=str))
+    else:
+        for key, value in data.items():
+            print(f"{key}: {value}")
+
+
+def _exit_on_error(message: str, code: int = 1) -> NoReturn:
+    """Gibt eine Fehlermeldung aus und beendet das Programm."""
+    print(f"❌ {message}", file=sys.stderr)
+    raise typer.Exit(code=code)
+
+
+# ── Commands ────────────────────────────────────────────────────────
+@app.command()
+def run(
+    ctx: typer.Context,
+    input_text: str = typer.Argument(..., help="Input text to process"),
+) -> None:
+    """Führt einen Command durch die Governance-Pipeline aus."""
+    client = _make_client(ctx)
+    try:
+        result = client.run(input_text)
+    except GovernanceBlock as e:
+        _exit_on_error(str(e), code=1)
+
+    data: dict[str, Any] = {
+        "result": result.result,
+        "trace_id": result.trace_id,
+        "output": result.output,
+        "mode": result.mode,
+        "budget": result.budget,
+        "latency_ms": result.latency_ms,
+    }
+    _print_result(ctx, data)
+
+
+@app.command()
+def trace(
+    ctx: typer.Context,
+    trace_id: str = typer.Argument(..., help="Trace ID to retrieve"),
+) -> None:
+    """Ruft einen vollständigen Governance-Trace ab."""
+    client = _make_client(ctx)
+    result = client.governance.trace(trace_id)
+    if result is None:
+        _exit_on_error(f"Trace '{trace_id}' not found", code=1)
+
+    _print_result(ctx, result)
+
+
+@app.command()
+def health(
+    ctx: typer.Context,
+) -> None:
+    """Prüft den Health-Status des HestiaOS-Servers."""
+    client = _make_client(ctx)
+    status = client.system.status()
+    data: dict[str, Any] = {
+        "status": status.status,
+        "version": status.version,
+        "uptime_seconds": status.uptime_seconds,
+    }
+    _print_result(ctx, data)
+
+
+def main() -> None:
+    """Entrypoint für pyproject.toml [project.scripts]."""
+    app()
+
+
+if __name__ == "__main__":
+    main()