haru-cli 0.1.0__py3-none-any.whl

haru/config/schema.py

@@ -0,0 +1,261 @@
+"""Typed, immutable configuration schema for haru-cli.
+
+Every YAML document under ``config/`` validates into one of these models at
+load time. Models are frozen and reject unknown keys so configuration errors
+surface immediately with the offending path.
+"""
+
+from typing import Literal, Self
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class _FrozenModel(BaseModel):
+    """Base for all configuration models: immutable, strict about keys."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid", protected_namespaces=())
+
+
+class AppConfig(_FrozenModel):
+    """Top-level application settings."""
+
+    name: str
+    default_command: str = "chat"
+
+
+class SsoConfig(_FrozenModel):
+    """IAM Identity Center (SSO) login settings."""
+
+    start_url: str
+    sso_region: str
+    registration_scopes: tuple[str, ...] = ("sso:account:access",)
+    client_name: str = "haru-cli"
+    account_id_env: str
+    role_name: str
+    callback_port: int = Field(default=0, ge=0, le=65535)
+    browser: bool = True
+
+
+class AuthConfig(_FrozenModel):
+    """Authentication and AWS session settings."""
+
+    sso: SsoConfig
+    bedrock_region: str
+
+
+class IncludesConfig(_FrozenModel):
+    """Relative paths of the include files that complete the configuration."""
+
+    models: str | None = None
+    agents: str | None = None
+    mcp: str | None = None
+    guardrails: str | None = None
+    logging: str | None = None
+
+
+class ModelConfig(_FrozenModel):
+    """A single Bedrock model entry."""
+
+    model_id: str
+    region: str
+    max_tokens: int = Field(ge=1)
+    temperature: float = Field(ge=0.0, le=1.0)
+    streaming: bool = True
+
+
+class ModelsConfig(_FrozenModel):
+    """The model catalogue and the default model key."""
+
+    default_model: str
+    models: dict[str, ModelConfig]
+
+    @model_validator(mode="after")
+    def _default_model_exists(self) -> Self:
+        if self.default_model not in self.models:
+            raise ValueError(f"default_model {self.default_model!r} is not a configured model")
+        return self
+
+
+class AgentConfig(_FrozenModel):
+    """A single agent definition."""
+
+    model: str
+    system_prompt_ref: str | None = None
+    tools: tuple[str, ...] = ()
+    mcp_servers: tuple[str, ...] = ()
+
+
+class SwarmConfig(_FrozenModel):
+    """Swarm orchestration settings."""
+
+    members: tuple[str, ...]
+    max_handoffs: int = Field(default=8, ge=1)
+    execution_timeout_seconds: int = Field(default=300, ge=1)
+
+
+class GraphNode(_FrozenModel):
+    """A node in a graph orchestration."""
+
+    id: str
+    agent: str
+
+
+class GraphEdge(_FrozenModel):
+    """A directed edge in a graph orchestration."""
+
+    source: str = Field(alias="from")
+    target: str = Field(alias="to")
+
+
+class GraphConfig(_FrozenModel):
+    """Graph orchestration settings."""
+
+    nodes: tuple[GraphNode, ...]
+    edges: tuple[GraphEdge, ...]
+
+    @model_validator(mode="after")
+    def _edges_reference_nodes(self) -> Self:
+        node_ids = {node.id for node in self.nodes}
+        for edge in self.edges:
+            for endpoint in (edge.source, edge.target):
+                if endpoint not in node_ids:
+                    raise ValueError(f"graph edge references unknown node {endpoint!r}")
+        return self
+
+
+class OrchestrationConfig(_FrozenModel):
+    """Multi-agent orchestration settings."""
+
+    default_pattern: Literal["supervisor", "swarm", "graph"] = "supervisor"
+    swarm: SwarmConfig | None = None
+    graph: GraphConfig | None = None
+
+
+class AgentsConfig(_FrozenModel):
+    """The agent roster and orchestration configuration."""
+
+    agents: dict[str, AgentConfig]
+    orchestration: OrchestrationConfig | None = None
+
+    @model_validator(mode="after")
+    def _references_are_defined(self) -> Self:
+        if self.orchestration is None:
+            return self
+        if self.orchestration.swarm is not None:
+            for member in self.orchestration.swarm.members:
+                if member not in self.agents:
+                    raise ValueError(f"swarm member {member!r} is not a configured agent")
+        if self.orchestration.graph is not None:
+            for node in self.orchestration.graph.nodes:
+                if node.agent not in self.agents:
+                    raise ValueError(f"graph node {node.id!r} references unknown agent")
+        return self
+
+
+class MCPServerConfig(_FrozenModel):
+    """A single MCP server connection."""
+
+    transport: Literal["stdio", "streamable-http"]
+    command: str | None = None
+    args: tuple[str, ...] = ()
+    url: str | None = None
+    headers: dict[str, str] = Field(default_factory=dict)
+    disabled: bool = False
+    continue_on_error: bool = False
+
+    @model_validator(mode="after")
+    def _transport_fields(self) -> Self:
+        if self.transport == "stdio" and self.command is None:
+            raise ValueError("stdio MCP servers require a 'command'")
+        if self.transport == "streamable-http" and self.url is None:
+            raise ValueError("streamable-http MCP servers require a 'url'")
+        return self
+
+
+class MCPConfig(_FrozenModel):
+    """The MCP server registry."""
+
+    mcp_servers: dict[str, MCPServerConfig] = Field(default_factory=dict)
+
+
+class SessionsConfig(_FrozenModel):
+    """Conversation persistence settings.
+
+    The file backend always uses an explicit project-local directory; the OS
+    temp directory is never used.
+    """
+
+    backend: Literal["file", "s3"] = "file"
+    storage_dir: str = "./.haru/sessions"
+    bucket: str | None = None
+    prefix: str = "haru/sessions"
+    region: str | None = None
+
+    @model_validator(mode="after")
+    def _s3_requires_bucket(self) -> Self:
+        if self.backend == "s3" and self.bucket is None:
+            raise ValueError("s3 session backend requires a 'bucket'")
+        return self
+
+
+class GuardrailsConfig(_FrozenModel):
+    """Bedrock Guardrails settings."""
+
+    enabled: bool = True
+    guardrail_id: str | None = None
+    guardrail_version: str = "DRAFT"
+    trace: Literal["enabled", "disabled", "enabled_full"] = "enabled"
+    redact_input: bool = True
+    redact_input_message: str = "[redacted]"
+    redact_output: bool = False
+
+
+class LoggingConfig(_FrozenModel):
+    """Application logging settings."""
+
+    level: str = "INFO"
+    format: Literal["json", "text"] = "json"
+    file: str | None = None
+
+
+class OtelConfig(_FrozenModel):
+    """OpenTelemetry exporter settings."""
+
+    enabled: bool = False
+    endpoint: str | None = None
+    service_name: str = "haru-cli"
+    console_export: bool = False
+
+
+class ObservabilityConfig(_FrozenModel):
+    """Observability settings."""
+
+    otel: OtelConfig
+
+
+class GuardrailsFile(_FrozenModel):
+    """Shape of the guardrails include file."""
+
+    guardrails: GuardrailsConfig
+
+
+class LoggingFile(_FrozenModel):
+    """Shape of the logging include file."""
+
+    logging: LoggingConfig
+    observability: ObservabilityConfig
+
+
+class HaruConfig(_FrozenModel):
+    """The complete haru-cli configuration after includes are resolved."""
+
+    app: AppConfig
+    auth: AuthConfig
+    sessions: SessionsConfig | None = None
+    includes: IncludesConfig | None = None
+    models: ModelsConfig | None = None
+    agents: AgentsConfig | None = None
+    mcp: MCPConfig | None = None
+    guardrails: GuardrailsConfig | None = None
+    logging: LoggingConfig | None = None
+    observability: ObservabilityConfig | None = None

haru/errors.py

@@ -0,0 +1,25 @@
+"""Typed exceptions for haru-cli.
+
+Third-party errors are converted to these types at module boundaries so that
+callers only ever handle haru-cli exceptions.
+"""
+
+
+class HaruError(Exception):
+    """Base class for all haru-cli errors."""
+
+
+class ConfigError(HaruError):
+    """Raised when configuration is missing, malformed, or insecure."""
+
+
+class AuthError(HaruError):
+    """Raised when authentication fails or is misconfigured."""
+
+
+class AuthExpiredError(AuthError):
+    """Raised when cached credentials are missing or expired; re-login is required."""
+
+
+class ToolError(HaruError):
+    """Raised when a tool or MCP server cannot be constructed or listed."""

haru/models/__init__.py

@@ -0,0 +1,5 @@
+"""Strands BedrockModel factories."""
+
+from haru.models.bedrock import build_model, get_model_config, list_models, resolve_model_id
+
+__all__ = ["build_model", "get_model_config", "list_models", "resolve_model_id"]

haru/models/bedrock.py

@@ -0,0 +1,77 @@
+"""Build Strands BedrockModel instances from typed configuration.
+
+Model transport stays entirely inside Strands; this module only maps validated
+configuration onto ``BedrockModel`` construction. Bare model identifiers get
+the ``us.`` geographic inference-profile prefix so data residency defaults to
+the US; any explicitly configured prefix (including ``global.``) is respected
+as written, since configuration is the approval surface.
+"""
+
+import boto3
+from strands.models import BedrockModel
+
+from haru.config.schema import GuardrailsConfig, HaruConfig, ModelConfig, ModelsConfig
+from haru.errors import ConfigError
+from haru.observability.guardrails import apply_guardrail
+
+_GEO_PREFIXES = ("us.", "eu.", "ap.", "apac.", "au.", "jp.", "global.")
+_DEFAULT_GEO_PREFIX = "us."
+
+
+def resolve_model_id(model_id: str) -> str:
+    """Return ``model_id`` with the default ``us.`` prefix applied when bare.
+
+    Identifiers that already carry a geographic prefix, or that are full ARNs,
+    are returned unchanged.
+    """
+    if model_id.startswith("arn:") or model_id.startswith(_GEO_PREFIXES):
+        return model_id
+    return f"{_DEFAULT_GEO_PREFIX}{model_id}"
+
+
+def build_model(
+    model_cfg: ModelConfig,
+    session: boto3.Session,
+    guardrails: GuardrailsConfig | None = None,
+) -> BedrockModel:
+    """Build a Strands BedrockModel from ``model_cfg`` and a boto3 session.
+
+    When ``guardrails`` is enabled, the Bedrock Guardrails parameters are
+    attached to the model.
+    """
+    return BedrockModel(
+        boto_session=session,
+        region_name=model_cfg.region,
+        model_id=resolve_model_id(model_cfg.model_id),
+        max_tokens=model_cfg.max_tokens,
+        temperature=model_cfg.temperature,
+        streaming=model_cfg.streaming,
+        # Rich tool schemas can fail ConverseStream's strict validation.
+        strict_tools=False,
+        **apply_guardrail(model_cfg, guardrails),
+    )
+
+
+def get_model_config(config: HaruConfig, name: str | None = None) -> ModelConfig:
+    """Return the model entry for ``name`` (or the configured default).
+
+    Raises ConfigError when no models are configured or the key is unknown.
+    """
+    models = _require_models(config)
+    key = name if name is not None else models.default_model
+    entry = models.models.get(key)
+    if entry is None:
+        available = ", ".join(sorted(models.models))
+        raise ConfigError(f"Unknown model {key!r}; configured models: {available}")
+    return entry
+
+
+def list_models(config: HaruConfig) -> list[str]:
+    """Return the configured model keys, sorted."""
+    return sorted(_require_models(config).models)
+
+
+def _require_models(config: HaruConfig) -> ModelsConfig:
+    if config.models is None:
+        raise ConfigError("No models configured; add a models include to config/haru.yaml")
+    return config.models

haru/observability/__init__.py

@@ -0,0 +1,6 @@
+"""OpenTelemetry configuration and Bedrock Guardrails mapping."""
+
+from haru.observability.guardrails import apply_guardrail
+from haru.observability.telemetry import configure_telemetry
+
+__all__ = ["apply_guardrail", "configure_telemetry"]

haru/observability/guardrails.py

@@ -0,0 +1,36 @@
+"""Map guardrail configuration onto Strands BedrockModel keyword arguments.
+
+Guardrails fail closed: when enabled, a guardrail id is mandatory, and input
+redaction defaults on. Disabling guardrails must be an explicit configuration
+choice, never a fallback.
+"""
+
+from typing import Any
+
+from haru.config.schema import GuardrailsConfig, ModelConfig
+from haru.errors import ConfigError
+
+
+def apply_guardrail(
+    model_cfg: ModelConfig, guardrail_cfg: GuardrailsConfig | None
+) -> dict[str, Any]:
+    """Return the guardrail kwargs for BedrockModel construction.
+
+    Returns an empty mapping when guardrails are absent or explicitly
+    disabled. Raises ConfigError when guardrails are enabled without an id.
+    """
+    if guardrail_cfg is None or not guardrail_cfg.enabled:
+        return {}
+    if not guardrail_cfg.guardrail_id:
+        raise ConfigError(
+            f"Guardrails are enabled but no guardrail_id is configured"
+            f" (model {model_cfg.model_id!r}); set guardrails.guardrail_id"
+        )
+    return {
+        "guardrail_id": guardrail_cfg.guardrail_id,
+        "guardrail_version": guardrail_cfg.guardrail_version,
+        "guardrail_trace": guardrail_cfg.trace,
+        "guardrail_redact_input": guardrail_cfg.redact_input,
+        "guardrail_redact_input_message": guardrail_cfg.redact_input_message,
+        "guardrail_redact_output": guardrail_cfg.redact_output,
+    }

haru/observability/telemetry.py

@@ -0,0 +1,34 @@
+"""Configure OpenTelemetry tracing via the Strands telemetry helper.
+
+Telemetry is a strict no-op when disabled; when enabled, the OTLP exporter is
+initialised through ``StrandsTelemetry``, with the endpoint and service name
+published via the standard OTel environment variables.
+"""
+
+import logging
+import os
+
+from strands.telemetry import StrandsTelemetry
+
+from haru.config.schema import ObservabilityConfig
+
+logger = logging.getLogger(__name__)
+
+_OTEL_ENDPOINT_ENV = "OTEL_EXPORTER_OTLP_ENDPOINT"
+_OTEL_SERVICE_NAME_ENV = "OTEL_SERVICE_NAME"
+
+
+def configure_telemetry(obs_cfg: ObservabilityConfig | None) -> None:
+    """Initialise OTel exporters when enabled; do nothing when disabled."""
+    if obs_cfg is None or not obs_cfg.otel.enabled:
+        return
+    otel = obs_cfg.otel
+    if otel.endpoint is not None:
+        os.environ.setdefault(_OTEL_ENDPOINT_ENV, otel.endpoint)
+    os.environ.setdefault(_OTEL_SERVICE_NAME_ENV, otel.service_name)
+
+    telemetry = StrandsTelemetry()
+    telemetry.setup_otlp_exporter()
+    if otel.console_export:
+        telemetry.setup_console_exporter()
+    logger.debug("OpenTelemetry configured (service=%s)", otel.service_name)

haru/sessions/__init__.py

@@ -0,0 +1,5 @@
+"""Conversation session persistence."""
+
+from haru.sessions.manager import build_session_manager, list_sessions
+
+__all__ = ["build_session_manager", "list_sessions"]

haru/sessions/manager.py

@@ -0,0 +1,70 @@
+"""Build Strands session managers from typed configuration.
+
+The file backend persists to an explicit project-local directory
+(``./.haru/sessions`` by default) — never the OS temp directory. The S3
+backend stores sessions under a configurable bucket and prefix.
+"""
+
+from pathlib import Path
+
+import boto3
+from strands.session import FileSessionManager, S3SessionManager
+from strands.session.session_manager import SessionManager
+
+from haru.config.schema import HaruConfig, SessionsConfig
+
+_SESSION_DIR_PREFIX = "session_"
+
+_DEFAULT_SESSIONS = SessionsConfig()
+
+
+def build_session_manager(
+    config: HaruConfig, session_id: str, *, boto_session: boto3.Session | None = None
+) -> SessionManager:
+    """Build the configured session manager (file by default) for ``session_id``."""
+    sessions = config.sessions if config.sessions is not None else _DEFAULT_SESSIONS
+    if sessions.backend == "s3":
+        return S3SessionManager(
+            session_id,
+            bucket=str(sessions.bucket),
+            prefix=sessions.prefix,
+            boto_session=boto_session,
+            region_name=sessions.region,
+        )
+    storage_dir = Path(sessions.storage_dir)
+    storage_dir.mkdir(parents=True, exist_ok=True)
+    return FileSessionManager(session_id, storage_dir=str(storage_dir))
+
+
+def list_sessions(
+    config: HaruConfig | None = None, *, boto_session: boto3.Session | None = None
+) -> list[str]:
+    """Return the stored session ids for the configured backend, sorted."""
+    sessions = (
+        config.sessions if config is not None and config.sessions is not None else _DEFAULT_SESSIONS
+    )
+    if sessions.backend == "s3":
+        return _list_s3_sessions(sessions, boto_session)
+    storage_dir = Path(sessions.storage_dir)
+    if not storage_dir.is_dir():
+        return []
+    return sorted(
+        entry.name.removeprefix(_SESSION_DIR_PREFIX)
+        for entry in storage_dir.iterdir()
+        if entry.is_dir() and entry.name.startswith(_SESSION_DIR_PREFIX)
+    )
+
+
+def _list_s3_sessions(sessions: SessionsConfig, boto_session: boto3.Session | None) -> list[str]:
+    session = boto_session if boto_session is not None else boto3.Session()
+    client = session.client("s3", region_name=sessions.region)
+    prefix = f"{sessions.prefix.rstrip('/')}/{_SESSION_DIR_PREFIX}" if sessions.prefix else ""
+    found: set[str] = set()
+    paginator = client.get_paginator("list_objects_v2")
+    for page in paginator.paginate(Bucket=str(sessions.bucket), Prefix=prefix):
+        for item in page.get("Contents", []):
+            remainder = item["Key"].removeprefix(prefix)
+            session_id = remainder.split("/", 1)[0]
+            if session_id:
+                found.add(session_id)
+    return sorted(found)

haru/steering/__init__.py

@@ -0,0 +1,5 @@
+"""Reusable system prompt management."""
+
+from haru.steering.prompts import load_prompts, resolve_prompt
+
+__all__ = ["load_prompts", "resolve_prompt"]

haru/steering/prompts.py

@@ -0,0 +1,42 @@
+"""Load and resolve reusable system prompts.
+
+Prompts live in versioned markdown files under ``config/prompts/`` and are
+referenced by agents via ``system_prompt_ref`` — never inlined in code. A ref
+may compose several prompts with ``+`` (for example ``base+researcher``),
+which concatenates them in order: a shared base plus a role overlay.
+"""
+
+from pathlib import Path
+
+from haru.errors import ConfigError
+
+DEFAULT_PROMPTS_ROOT = Path("config") / "prompts"
+
+_COMPOSE_SEPARATOR = "+"
+
+
+def load_prompts(root: Path) -> dict[str, str]:
+    """Load every ``*.md`` prompt under ``root``, keyed by file stem."""
+    if not root.is_dir():
+        raise ConfigError(f"Prompts directory not found: {root}")
+    return {
+        path.stem: path.read_text(encoding="utf-8").strip() for path in sorted(root.glob("*.md"))
+    }
+
+
+def resolve_prompt(ref: str, prompts: dict[str, str]) -> str:
+    """Resolve ``ref`` (optionally composite, ``a+b``) to prompt text.
+
+    Raises ConfigError when any referenced prompt is missing.
+    """
+    parts = [part.strip() for part in ref.split(_COMPOSE_SEPARATOR)]
+    if not all(parts):
+        raise ConfigError(f"Malformed prompt reference {ref!r}")
+    missing = [part for part in parts if part not in prompts]
+    if missing:
+        available = ", ".join(sorted(prompts)) or "none"
+        raise ConfigError(
+            f"Unknown prompt reference(s) {', '.join(missing)!s} in {ref!r};"
+            f" available prompts: {available}"
+        )
+    return "\n\n".join(prompts[part] for part in parts)

haru/tools/__init__.py

@@ -0,0 +1,12 @@
+"""Built-in tool registry and MCP client construction."""
+
+from haru.tools.mcp import build_mcp_clients, collect_tools, started_mcp_clients
+from haru.tools.registry import available_builtin_tools, resolve_builtin_tools
+
+__all__ = [
+    "available_builtin_tools",
+    "build_mcp_clients",
+    "collect_tools",
+    "resolve_builtin_tools",
+    "started_mcp_clients",
+]