vystak 0.1.0__py3-none-any.whl

vystak/__init__.py

@@ -0,0 +1,126 @@
+"""Vystak — declarative AI agent orchestration."""
+
+__version__ = "0.1.0"
+
+# Schema models
+# Hash engine
+from vystak.hash import AgentHashTree, hash_agent, hash_dict, hash_model
+
+# Provider ABCs and supporting types
+from vystak.providers import (
+    AgentStatus,
+    ChannelAdapter,
+    DeployPlan,
+    DeployResult,
+    FrameworkAdapter,
+    GeneratedCode,
+    PlatformProvider,
+    ValidationError,
+)
+
+# Provisioning engine
+from vystak.provisioning import (
+    CommandHealthCheck,
+    CycleError,
+    HealthCheck,
+    HttpHealthCheck,
+    NoopHealthCheck,
+    Provisionable,
+    ProvisionError,
+    ProvisionGraph,
+    ProvisionResult,
+    TcpHealthCheck,
+)
+from vystak.schema import (
+    Agent,
+    Cache,
+    Channel,
+    ChannelProvider,
+    ChannelType,
+    Database,
+    Embedding,
+    Gateway,
+    McpServer,
+    McpTransport,
+    Model,
+    NamedModel,
+    ObjectStore,
+    Platform,
+    Postgres,
+    Provider,
+    Qdrant,
+    Queue,
+    Redis,
+    Resource,
+    Secret,
+    Service,
+    SessionStore,
+    Skill,
+    SkillRequirements,
+    SlackChannel,
+    Sqlite,
+    VectorStore,
+    Workspace,
+    WorkspaceType,
+)
+
+# Loader
+from vystak.schema.loader import dump_agent, load_agent
+
+__all__ = [
+    "__version__",
+    "Agent",
+    "Cache",
+    "Channel",
+    "ChannelProvider",
+    "ChannelType",
+    "Database",
+    "Embedding",
+    "Gateway",
+    "McpServer",
+    "McpTransport",
+    "Model",
+    "NamedModel",
+    "ObjectStore",
+    "Platform",
+    "Postgres",
+    "Provider",
+    "Qdrant",
+    "Queue",
+    "Redis",
+    "Resource",
+    "Secret",
+    "Service",
+    "SessionStore",
+    "Skill",
+    "SkillRequirements",
+    "SlackChannel",
+    "Sqlite",
+    "VectorStore",
+    "Workspace",
+    "WorkspaceType",
+    "AgentHashTree",
+    "hash_agent",
+    "hash_dict",
+    "hash_model",
+    "dump_agent",
+    "load_agent",
+    "AgentStatus",
+    "ChannelAdapter",
+    "DeployPlan",
+    "DeployResult",
+    "FrameworkAdapter",
+    "GeneratedCode",
+    "PlatformProvider",
+    "ValidationError",
+    "CommandHealthCheck",
+    "CycleError",
+    "HealthCheck",
+    "HttpHealthCheck",
+    "NoopHealthCheck",
+    "Provisionable",
+    "ProvisionError",
+    "ProvisionGraph",
+    "ProvisionResult",
+    "TcpHealthCheck",
+]

vystak/hash/__init__.py

@@ -0,0 +1,6 @@
+"""Content-addressable hash engine for stateless change detection."""
+
+from vystak.hash.hasher import hash_dict, hash_model
+from vystak.hash.tree import AgentHashTree, hash_agent
+
+__all__ = ["AgentHashTree", "hash_agent", "hash_dict", "hash_model"]

vystak/hash/hasher.py

@@ -0,0 +1,18 @@
+"""Leaf-level hashing for Pydantic models and dicts."""
+
+import hashlib
+import json
+
+from pydantic import BaseModel
+
+
+def hash_model(model: BaseModel) -> str:
+    """SHA-256 of canonical JSON representation of a Pydantic model."""
+    canonical = json.dumps(model.model_dump(mode="python"), sort_keys=True, default=str)
+    return hashlib.sha256(canonical.encode()).hexdigest()
+
+
+def hash_dict(data: dict) -> str:
+    """SHA-256 of canonical JSON representation of a dict."""
+    canonical = json.dumps(data, sort_keys=True, default=str)
+    return hashlib.sha256(canonical.encode()).hexdigest()

vystak/hash/tree.py

@@ -0,0 +1,82 @@
+"""Hash tree composition for agent definitions."""
+
+import hashlib
+from dataclasses import dataclass
+
+from vystak.hash.hasher import hash_model
+from vystak.schema.agent import Agent
+
+
+@dataclass
+class AgentHashTree:
+    """Per-section hashes for an agent, enabling partial deploy detection."""
+
+    brain: str
+    skills: str
+    mcp_servers: str
+    channels: str
+    workspace: str
+    resources: str
+    secrets: str
+    sessions: str
+    memory: str
+    services: str
+    root: str
+
+
+def _hash_list(items: list) -> str:
+    if not items:
+        return hashlib.sha256(b"[]").hexdigest()
+    individual = sorted(hash_model(item) for item in items)
+    combined = "|".join(individual)
+    return hashlib.sha256(combined.encode()).hexdigest()
+
+
+def _hash_optional(item) -> str:
+    if item is None:
+        return hashlib.sha256(b"null").hexdigest()
+    return hash_model(item)
+
+
+def hash_agent(agent: Agent) -> AgentHashTree:
+    """Compute the full hash tree for an agent definition."""
+    brain = hash_model(agent.model)
+    skills = _hash_list(agent.skills)
+    mcp_servers = _hash_list(agent.mcp_servers)
+    channels = _hash_list(agent.channels)
+    workspace = _hash_optional(agent.workspace)
+    resources = _hash_list(agent.resources)
+    secrets = _hash_list(agent.secrets)
+    sessions = _hash_optional(agent.sessions)
+    memory = _hash_optional(agent.memory)
+    services = _hash_list(agent.services)
+
+    sections = "|".join(
+        [
+            brain,
+            skills,
+            mcp_servers,
+            channels,
+            workspace,
+            resources,
+            secrets,
+            sessions,
+            memory,
+            services,
+        ]
+    )
+    root = hashlib.sha256(sections.encode()).hexdigest()
+
+    return AgentHashTree(
+        brain=brain,
+        skills=skills,
+        mcp_servers=mcp_servers,
+        channels=channels,
+        workspace=workspace,
+        resources=resources,
+        secrets=secrets,
+        sessions=sessions,
+        memory=memory,
+        services=services,
+        root=root,
+    )

vystak/ir/__init__.py

@@ -0,0 +1 @@
+"""Intermediate representation consumed by framework adapters."""

vystak/providers/__init__.py

@@ -0,0 +1,23 @@
+"""Provider base classes for platform and resource provisioning."""
+
+from vystak.providers.base import (
+    AgentStatus,
+    ChannelAdapter,
+    DeployPlan,
+    DeployResult,
+    FrameworkAdapter,
+    GeneratedCode,
+    PlatformProvider,
+    ValidationError,
+)
+
+__all__ = [
+    "AgentStatus",
+    "ChannelAdapter",
+    "DeployPlan",
+    "DeployResult",
+    "FrameworkAdapter",
+    "GeneratedCode",
+    "PlatformProvider",
+    "ValidationError",
+]

vystak/providers/base.py

@@ -0,0 +1,77 @@
+"""Abstract base classes for framework adapters, platform providers, and channel adapters."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+
+from vystak.schema.agent import Agent
+from vystak.schema.channel import Channel
+
+
+@dataclass
+class GeneratedCode:
+    files: dict[str, str]
+    entrypoint: str
+
+
+@dataclass
+class DeployPlan:
+    agent_name: str
+    actions: list[str]
+    current_hash: str | None
+    target_hash: str
+    changes: dict[str, tuple[str | None, str]]
+
+
+@dataclass
+class DeployResult:
+    agent_name: str
+    success: bool
+    hash: str
+    message: str
+
+
+@dataclass
+class AgentStatus:
+    agent_name: str
+    running: bool
+    hash: str | None
+    info: dict = field(default_factory=dict)
+
+
+@dataclass
+class ValidationError:
+    field: str
+    message: str
+
+
+class FrameworkAdapter(ABC):
+    @abstractmethod
+    def generate(self, agent: Agent) -> GeneratedCode: ...
+
+    @abstractmethod
+    def validate(self, agent: Agent) -> list[ValidationError]: ...
+
+
+class PlatformProvider(ABC):
+    @abstractmethod
+    def plan(self, agent: Agent, current_hash: str | None) -> DeployPlan: ...
+
+    @abstractmethod
+    def apply(self, plan: DeployPlan) -> DeployResult: ...
+
+    @abstractmethod
+    def destroy(self, agent_name: str) -> None: ...
+
+    @abstractmethod
+    def status(self, agent_name: str) -> AgentStatus: ...
+
+    @abstractmethod
+    def get_hash(self, agent_name: str) -> str | None: ...
+
+
+class ChannelAdapter(ABC):
+    @abstractmethod
+    def setup(self, agent: Agent, channel: Channel) -> None: ...
+
+    @abstractmethod
+    def teardown(self, channel: Channel) -> None: ...

vystak/provisioning/__init__.py

@@ -0,0 +1,37 @@
+"""Provisioning engine — dependency graph, health checks, and provisionable protocol."""
+
+from vystak.provisioning.graph import CycleError, ProvisionError, ProvisionGraph
+from vystak.provisioning.grouping import group_agents_by_platform, platform_fingerprint
+from vystak.provisioning.health import (
+    CommandHealthCheck,
+    HealthCheck,
+    HttpHealthCheck,
+    NoopHealthCheck,
+    TcpHealthCheck,
+)
+from vystak.provisioning.listener import (
+    NullListener,
+    PrintListener,
+    ProvisionEvent,
+    ProvisionListener,
+)
+from vystak.provisioning.node import Provisionable, ProvisionResult
+
+__all__ = [
+    "CommandHealthCheck",
+    "CycleError",
+    "group_agents_by_platform",
+    "HealthCheck",
+    "HttpHealthCheck",
+    "NoopHealthCheck",
+    "NullListener",
+    "platform_fingerprint",
+    "PrintListener",
+    "Provisionable",
+    "ProvisionError",
+    "ProvisionEvent",
+    "ProvisionGraph",
+    "ProvisionListener",
+    "ProvisionResult",
+    "TcpHealthCheck",
+]

vystak/provisioning/graph.py

@@ -0,0 +1,122 @@
+"""Dependency graph for provisioning resources."""
+
+from dataclasses import dataclass, field
+
+from vystak.provisioning.listener import NullListener, ProvisionEvent, ProvisionListener
+from vystak.provisioning.node import Provisionable, ProvisionResult
+
+
+class CycleError(Exception):
+    pass
+
+
+class ProvisionError(Exception):
+    pass
+
+
+@dataclass
+class ProvisionGraph:
+    _nodes: dict[str, Provisionable] = field(default_factory=dict)
+    _implicit_deps: dict[str, list[str]] = field(default_factory=dict)
+    _listener: ProvisionListener = field(default_factory=NullListener)
+
+    def set_listener(self, listener: ProvisionListener) -> None:
+        """Set the event listener for provision progress."""
+        self._listener = listener
+
+    def add(self, node: Provisionable) -> None:
+        self._nodes[node.name] = node
+
+    def add_dependency(self, name: str, depends_on: str) -> None:
+        self._implicit_deps.setdefault(name, []).append(depends_on)
+
+    def _all_deps(self, name: str) -> list[str]:
+        node = self._nodes[name]
+        all_deps = list(node.depends_on)
+        all_deps.extend(self._implicit_deps.get(name, []))
+        return [d for d in all_deps if d in self._nodes]
+
+    def _resolve_order(self) -> list[str]:
+        reverse: dict[str, list[str]] = {name: [] for name in self._nodes}
+        in_degree: dict[str, int] = {name: 0 for name in self._nodes}
+
+        for name in self._nodes:
+            deps = self._all_deps(name)
+            in_degree[name] = len(deps)
+            for dep in deps:
+                reverse[dep].append(name)
+
+        queue = [n for n, d in in_degree.items() if d == 0]
+        order: list[str] = []
+
+        while queue:
+            node = queue.pop(0)
+            order.append(node)
+            for dependent in reverse[node]:
+                in_degree[dependent] -= 1
+                if in_degree[dependent] == 0:
+                    queue.append(dependent)
+
+        if len(order) != len(self._nodes):
+            raise CycleError("Dependency cycle detected in provision graph")
+
+        return order
+
+    def execute(self) -> dict[str, ProvisionResult]:
+        order = self._resolve_order()
+        results: dict[str, ProvisionResult] = {}
+
+        for name in order:
+            node = self._nodes[name]
+
+            self._listener.on_start(
+                ProvisionEvent(
+                    node_name=name,
+                    event_type="start",
+                    message=name,
+                )
+            )
+
+            # Pass listener to node if it supports it
+            if hasattr(node, "set_listener"):
+                node.set_listener(self._listener)
+
+            result = node.provision(context=results)
+            results[name] = result
+
+            if not result.success:
+                self._listener.on_error(
+                    ProvisionEvent(
+                        node_name=name,
+                        event_type="error",
+                        message=name,
+                        detail=result.error or "",
+                    )
+                )
+                raise ProvisionError(f"Failed to provision {name}: {result.error}")
+
+            self._listener.on_complete(
+                ProvisionEvent(
+                    node_name=name,
+                    event_type="complete",
+                    message=name,
+                    detail=result.info.get("detail", ""),
+                )
+            )
+
+            check = node.health_check()
+            self._listener.on_health_check(
+                ProvisionEvent(
+                    node_name=name,
+                    event_type="health_check",
+                    message=f"Waiting for {name}",
+                )
+            )
+            check.wait()
+
+        return results
+
+    def destroy_all(self) -> None:
+        order = self._resolve_order()
+        for name in reversed(order):
+            self._nodes[name].destroy()

vystak/provisioning/grouping.py

@@ -0,0 +1,26 @@
+"""Group agents by platform fingerprint for shared infrastructure."""
+
+import hashlib
+import json
+
+from vystak.schema.agent import Agent
+
+
+def platform_fingerprint(agent: Agent) -> str:
+    if agent.platform is None:
+        return "docker:default"
+    key = {
+        "provider_type": agent.platform.provider.type,
+        "provider_config": agent.platform.provider.config,
+        "platform_type": agent.platform.type,
+    }
+    canonical = json.dumps(key, sort_keys=True, default=str)
+    return hashlib.md5(canonical.encode()).hexdigest()
+
+
+def group_agents_by_platform(agents: list[Agent]) -> dict[str, list[Agent]]:
+    groups: dict[str, list[Agent]] = {}
+    for agent in agents:
+        fp = platform_fingerprint(agent)
+        groups.setdefault(fp, []).append(agent)
+    return groups

vystak/provisioning/health.py

@@ -0,0 +1,62 @@
+"""Health check classes for resource readiness verification."""
+
+import socket
+import time
+import urllib.request
+from abc import ABC, abstractmethod
+
+
+class HealthCheck(ABC):
+    @abstractmethod
+    def check(self) -> bool: ...
+
+    def wait(self, timeout: int = 60, interval: float = 1.0) -> None:
+        deadline = time.time() + timeout
+        while time.time() < deadline:
+            if self.check():
+                return
+            time.sleep(interval)
+        raise TimeoutError(f"Health check did not pass within {timeout}s")
+
+
+class NoopHealthCheck(HealthCheck):
+    def check(self) -> bool:
+        return True
+
+
+class TcpHealthCheck(HealthCheck):
+    def __init__(self, host: str, port: int):
+        self.host = host
+        self.port = port
+
+    def check(self) -> bool:
+        try:
+            with socket.create_connection((self.host, self.port), timeout=2):
+                return True
+        except (TimeoutError, ConnectionRefusedError, OSError):
+            return False
+
+
+class CommandHealthCheck(HealthCheck):
+    def __init__(self, container, command: list[str]):
+        self.container = container
+        self.command = command
+
+    def check(self) -> bool:
+        try:
+            result = self.container.exec_run(self.command, demux=False)
+            return result.exit_code == 0
+        except Exception:
+            return False
+
+
+class HttpHealthCheck(HealthCheck):
+    def __init__(self, url: str):
+        self.url = url
+
+    def check(self) -> bool:
+        try:
+            resp = urllib.request.urlopen(self.url, timeout=2)
+            return resp.status == 200
+        except Exception:
+            return False

vystak/provisioning/listener.py

@@ -0,0 +1,68 @@
+"""Provision event listener — callbacks for graph execution progress."""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class ProvisionEvent:
+    """An event emitted during provisioning."""
+
+    node_name: str
+    event_type: str  # "start", "step", "complete", "error", "health_check"
+    message: str = ""
+    detail: str = ""
+
+
+class ProvisionListener:
+    """Base listener for provision graph events. Override methods to handle events."""
+
+    def on_start(self, event: ProvisionEvent) -> None:
+        """Called before a node starts provisioning."""
+
+    def on_step(self, event: ProvisionEvent) -> None:
+        """Called during provisioning for sub-step progress (build, push, etc.)."""
+
+    def on_complete(self, event: ProvisionEvent) -> None:
+        """Called after a node finishes provisioning successfully."""
+
+    def on_error(self, event: ProvisionEvent) -> None:
+        """Called when a node fails to provision."""
+
+    def on_health_check(self, event: ProvisionEvent) -> None:
+        """Called when waiting for a health check."""
+
+
+class PrintListener(ProvisionListener):
+    """Prints provision events to stdout with indentation."""
+
+    def __init__(self, indent: str = "    "):
+        self._indent = indent
+
+    def on_start(self, event: ProvisionEvent) -> None:
+        print(f"{self._indent}{event.message}... ", end="", flush=True)
+
+    def on_step(self, event: ProvisionEvent) -> None:
+        if event.detail:
+            print(f"\n{self._indent}{event.message}: {event.detail}... ", end="", flush=True)
+        else:
+            print(f"\n{self._indent}{event.message}... ", end="", flush=True)
+
+    def on_complete(self, event: ProvisionEvent) -> None:
+        if event.detail:
+            print(f"OK ({event.detail})")
+        else:
+            print("OK")
+
+    def on_error(self, event: ProvisionEvent) -> None:
+        print("FAILED")
+        if event.detail:
+            print(f"{self._indent}  Error: {event.detail}")
+
+    def on_health_check(self, event: ProvisionEvent) -> None:
+        pass  # silent by default
+
+
+class NullListener(ProvisionListener):
+    """Does nothing. Used when no listener is provided."""
+
+    pass