haru-cli 0.1.0__tar.gz → 0.1.2__tar.gz

{haru_cli-0.1.0 → haru_cli-0.1.2}/CHANGELOG.md

@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Sampling controls (`temperature`, `top_p`, `top_k`, `seed`) across three
+  surfaces: model entries, per-agent `sampling:` blocks, and CLI/REPL
+  overrides (`--temperature/--top-p/--top-k/--seed`, `/sampling`).
+  Precedence CLI/REPL → agent → model, merged per-field; unset fields are
+  omitted from requests. `top_k`/`seed` travel via Converse
+  `additionalModelRequestFields`.
+
+### Fixed
+
+- `temperature` is no longer required (or sent by default) on model entries —
+  Claude 5-series and Opus 4.7+ reject non-default sampling values with an
+  HTTP 400, which the previous always-sent temperature would have triggered.
+
+### Added
+
+- `haru config init`: interactive starter configuration under
+  `~/.config/haru` (SSO settings prompted; guardrails explicitly disabled
+  when no id is provided). `haru config show` prints a secret-free summary.
+- Config resolution order: `--config`, `$HARU_CONFIG`, `./config/haru.yaml`,
+  `~/.config/haru/haru.yaml` — installed CLIs work outside a project clone.
+- `haru agents`: list configured agents with model, prompt, tools, and MCP
+  servers.
+- Chat REPL slash commands: `/help`, `/model` (list/switch models), `/agent`
+  (list/switch agents).
+
+### Fixed
+
+- `haru login` reports configuration errors as clean messages instead of a
+  traceback, pointing at `haru config init`.
+
 ## [0.1.0] - 2026-07-26
 
 ### Added

{haru_cli-0.1.0 → haru_cli-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: haru-cli
-Version: 0.1.0
+Version: 0.1.2
 Summary: Secure, scriptable CLI for Amazon Bedrock Claude models via the AWS Strands Agents SDK.
 Author: haru-cli maintainers
 License-Expression: Apache-2.0
@@ -56,22 +56,38 @@ uv sync
 
 | Command                          | Purpose                                                       |
 | -------------------------------- | ------------------------------------------------------------- |
+| `haru config init`               | Create a starter configuration (interactive)                  |
+| `haru config show`               | Show the resolved configuration (no secrets)                  |
 | `haru login`                     | Browser sign-in to IAM Identity Center (OAuth 2.0 + PKCE)     |
 | `haru chat`                      | Interactive streaming chat REPL                               |
 | `haru chat --session-id <id>`    | Persist and restore the conversation under a session id       |
 | `haru chat --agent <name>`       | Chat with a specific configured agent                         |
 | `haru run "<prompt>"`            | One-shot prompt; prints the answer and exits                  |
+| `haru agents`                    | List configured agents (model, prompt, tools, MCP)            |
 | `haru session list`              | List stored session ids                                       |
 | `haru --version`                 | Print the installed version                                   |
 
-Every command accepts `--config <path>` (default: `config/haru.yaml`).
+Configuration is resolved from `--config`, then `$HARU_CONFIG`, then
+`./config/haru.yaml`, then `~/.config/haru/haru.yaml`.
+
+Inside `haru chat`, slash commands switch targets mid-session:
+
+| REPL command     | Purpose                                                    |
+| ---------------- | ---------------------------------------------------------- |
+| `/help`          | Show REPL commands                                         |
+| `/model`         | List configured models (default and active marked)         |
+| `/model <name>`  | Switch the default agent to that model (resets the chat)   |
+| `/agent`         | List configured agents                                     |
+| `/agent <name>`  | Switch to that agent (resets the chat)                     |
 
 ## Quickstart
 
 ```bash
-uv run haru login
-uv run haru run "Summarise the Converse API in two sentences."
-uv run haru chat --agent supervisor --session-id demo
+haru config init      # writes ~/.config/haru (asks for your SSO start URL)
+export HARU_AWS_ACCOUNT_ID=<your AWS account id>
+haru login
+haru run "Summarise the Converse API in two sentences."
+haru chat --agent supervisor --session-id demo
 ```
 
 Authentication uses the same PKCE authorization-code flow as `aws sso login`,
@@ -80,12 +96,43 @@ caching tokens in the botocore-compatible schema under `~/.aws/sso/cache`
 tokens are refreshed automatically; when a fresh login is needed, commands say
 so plainly.
 
+## Sampling controls
+
+haru-cli exposes `temperature`, `top_p`, `top_k`, and `seed` on **three
+configuration surfaces** — a capability Kiro CLI does not offer on any of its
+configuration surfaces (its v2/v3 agent formats and `cli.json` define no
+sampling fields):
+
+| Surface                  | Where                                          | Example                                   |
+| ------------------------ | ---------------------------------------------- | ----------------------------------------- |
+| Model catalogue          | `models.yaml`, per model entry                 | `temperature: 0.2`, `top_k: 50`           |
+| Agent profile            | `agents.yaml`, per agent `sampling:` block     | `sampling: {temperature: 0.1}`            |
+| CLI / REPL               | `--temperature/--top-p/--top-k/--seed` flags on `run` and `chat`; `/sampling` in the REPL | `haru run "..." --top-k 20` |
+
+Precedence: **CLI/REPL override → agent `sampling:` block → model entry**,
+merged per-field. Unset fields are omitted from requests entirely, keeping
+the provider's defaults. In the chat REPL, `/sampling` shows the model
+default, session override, and effective value for each field;
+`/sampling temperature=0.2 top_k=50` applies overrides and `/sampling reset`
+clears them.
+
+Model compatibility (AWS-side behaviour, not a haru limitation):
+
+- **Claude 5-series and Opus 4.7+** (Sonnet 5, Opus 5, Opus 4.8) reject
+  non-default `temperature`/`top_p`/`top_k` with an HTTP 400 — leave them
+  unset on those entries (the shipped config does).
+- **Claude Haiku 4.5, Sonnet 4.5, and older Claude models**, plus
+  non-Anthropic Bedrock models, accept them.
+- `seed` is forwarded via Converse `additionalModelRequestFields` for Bedrock
+  models that support it; **no Claude model accepts a seed today**, so do not
+  expect determinism from Claude — the field exists for models that honour it.
+
 ## Configuration
 
 Declarative YAML under `config/` — models, agents, orchestration
-(supervisor/swarm/graph), MCP servers, guardrails, sessions, logging, and
-OpenTelemetry. No secrets in YAML: values reference environment variables with
-`${env:VAR}`. See [docs/configuration.md](docs/configuration.md).
+(supervisor/swarm/graph), MCP servers, guardrails, sessions, sampling,
+logging, and OpenTelemetry. No secrets in YAML: values reference environment
+variables with `${env:VAR}`. See [docs/configuration.md](docs/configuration.md).
 
 ## Development
 

haru_cli-0.1.2/README.md

@@ -0,0 +1,139 @@
+# haru-cli
+
+A secure, scriptable command line interface for interacting with Amazon Bedrock Claude models
+through governed, observable, multi-agent workflows. haru-cli is a thin, functional orchestration
+layer over the [AWS Strands Agents SDK](https://strandsagents.com), talking to Bedrock through the
+Converse API with streaming, tool use, MCP client support, multi-agent orchestration, session
+persistence, OpenTelemetry observability, and Bedrock Guardrails.
+
+## Requirements
+
+- Python 3.13+ (tested on 3.13 and 3.14)
+- [uv](https://docs.astral.sh/uv/)
+- AWS access via IAM Identity Center (SSO)
+
+## Install
+
+```bash
+pipx install haru-cli
+```
+
+Or from a clone:
+
+```bash
+uv sync
+```
+
+## Commands
+
+| Command                          | Purpose                                                       |
+| -------------------------------- | ------------------------------------------------------------- |
+| `haru config init`               | Create a starter configuration (interactive)                  |
+| `haru config show`               | Show the resolved configuration (no secrets)                  |
+| `haru login`                     | Browser sign-in to IAM Identity Center (OAuth 2.0 + PKCE)     |
+| `haru chat`                      | Interactive streaming chat REPL                               |
+| `haru chat --session-id <id>`    | Persist and restore the conversation under a session id       |
+| `haru chat --agent <name>`       | Chat with a specific configured agent                         |
+| `haru run "<prompt>"`            | One-shot prompt; prints the answer and exits                  |
+| `haru agents`                    | List configured agents (model, prompt, tools, MCP)            |
+| `haru session list`              | List stored session ids                                       |
+| `haru --version`                 | Print the installed version                                   |
+
+Configuration is resolved from `--config`, then `$HARU_CONFIG`, then
+`./config/haru.yaml`, then `~/.config/haru/haru.yaml`.
+
+Inside `haru chat`, slash commands switch targets mid-session:
+
+| REPL command     | Purpose                                                    |
+| ---------------- | ---------------------------------------------------------- |
+| `/help`          | Show REPL commands                                         |
+| `/model`         | List configured models (default and active marked)         |
+| `/model <name>`  | Switch the default agent to that model (resets the chat)   |
+| `/agent`         | List configured agents                                     |
+| `/agent <name>`  | Switch to that agent (resets the chat)                     |
+
+## Quickstart
+
+```bash
+haru config init      # writes ~/.config/haru (asks for your SSO start URL)
+export HARU_AWS_ACCOUNT_ID=<your AWS account id>
+haru login
+haru run "Summarise the Converse API in two sentences."
+haru chat --agent supervisor --session-id demo
+```
+
+Authentication uses the same PKCE authorization-code flow as `aws sso login`,
+caching tokens in the botocore-compatible schema under `~/.aws/sso/cache`
+(0600) so standard AWS tooling can consume and refresh the same cache. Access
+tokens are refreshed automatically; when a fresh login is needed, commands say
+so plainly.
+
+## Sampling controls
+
+haru-cli exposes `temperature`, `top_p`, `top_k`, and `seed` on **three
+configuration surfaces** — a capability Kiro CLI does not offer on any of its
+configuration surfaces (its v2/v3 agent formats and `cli.json` define no
+sampling fields):
+
+| Surface                  | Where                                          | Example                                   |
+| ------------------------ | ---------------------------------------------- | ----------------------------------------- |
+| Model catalogue          | `models.yaml`, per model entry                 | `temperature: 0.2`, `top_k: 50`           |
+| Agent profile            | `agents.yaml`, per agent `sampling:` block     | `sampling: {temperature: 0.1}`            |
+| CLI / REPL               | `--temperature/--top-p/--top-k/--seed` flags on `run` and `chat`; `/sampling` in the REPL | `haru run "..." --top-k 20` |
+
+Precedence: **CLI/REPL override → agent `sampling:` block → model entry**,
+merged per-field. Unset fields are omitted from requests entirely, keeping
+the provider's defaults. In the chat REPL, `/sampling` shows the model
+default, session override, and effective value for each field;
+`/sampling temperature=0.2 top_k=50` applies overrides and `/sampling reset`
+clears them.
+
+Model compatibility (AWS-side behaviour, not a haru limitation):
+
+- **Claude 5-series and Opus 4.7+** (Sonnet 5, Opus 5, Opus 4.8) reject
+  non-default `temperature`/`top_p`/`top_k` with an HTTP 400 — leave them
+  unset on those entries (the shipped config does).
+- **Claude Haiku 4.5, Sonnet 4.5, and older Claude models**, plus
+  non-Anthropic Bedrock models, accept them.
+- `seed` is forwarded via Converse `additionalModelRequestFields` for Bedrock
+  models that support it; **no Claude model accepts a seed today**, so do not
+  expect determinism from Claude — the field exists for models that honour it.
+
+## Configuration
+
+Declarative YAML under `config/` — models, agents, orchestration
+(supervisor/swarm/graph), MCP servers, guardrails, sessions, sampling,
+logging, and OpenTelemetry. No secrets in YAML: values reference environment
+variables with `${env:VAR}`. See [docs/configuration.md](docs/configuration.md).
+
+## Development
+
+All quality gates must pass before a change is considered done:
+
+```bash
+uv run ruff check
+uv run ruff format
+uv run mypy src
+uv run pytest
+```
+
+Coverage is gated at 90% (`--cov-fail-under=90`). CI runs the full gate set on
+Python 3.13 and 3.14; releases are built with `uv build` and published to PyPI
+via Trusted Publishing on `v*` tags.
+
+Install the pre-commit hooks once per clone:
+
+```bash
+uv tool run pre-commit install
+```
+
+## Project layout
+
+- `src/haru/` — the package (auth, config, models, agents, tools, steering, sessions, observability, commands)
+- `config/` — declarative YAML configuration and steering prompts
+- `tests/unit`, `tests/integration` — pytest suites (coverage gate: 90%)
+- `.kiro/steering/` — authoritative engineering steering documents
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).

{haru_cli-0.1.0 → haru_cli-0.1.2}/config/agents.yaml

@@ -28,3 +28,10 @@ orchestration:
     edges:
       - from: research
         to: write
+# Per-agent sampling overrides beat the model entry's values and are in turn
+# beaten by CLI/REPL overrides. Example:
+#   researcher:
+#     model: haiku-4-5
+#     sampling:
+#       temperature: 0.1
+#       top_k: 20

haru_cli-0.1.2/config/models.yaml

@@ -0,0 +1,31 @@
+# Sampling fields (temperature, top_p, top_k, seed) are optional; unset
+# fields are omitted from requests, keeping the provider's defaults.
+# Claude 5-series and Opus 4.7+ models reject non-default temperature/top_p/
+# top_k with an HTTP 400, so leave them unset on those entries. seed is
+# passed through to models that support it (no Claude model does today).
+default_model: sonnet-5
+models:
+  opus-5:
+    model_id: us.anthropic.claude-opus-5
+    region: us-east-1
+    max_tokens: 8192
+    streaming: true
+  sonnet-5:
+    model_id: us.anthropic.claude-sonnet-5
+    region: us-east-1
+    max_tokens: 8192
+    streaming: true
+  opus-4-8:
+    model_id: us.anthropic.claude-opus-4-8
+    region: us-east-1
+    max_tokens: 8192
+    streaming: true
+  # Haiku 4.5 accepts sampling parameters:
+  haiku-4-5:
+    model_id: us.anthropic.claude-haiku-4-5
+    region: us-east-1
+    max_tokens: 4096
+    temperature: 0.2
+    top_p: 0.9
+    top_k: 50
+    streaming: true

{haru_cli-0.1.0 → haru_cli-0.1.2}/docs/configuration.md

@@ -38,6 +38,18 @@ Bare Bedrock model ids receive the `us.` geographic inference-profile prefix
 by default. Explicit prefixes (`eu.`, `au.`, `global.`, ...) and full ARNs
 pass through as configured — writing one into YAML is the approval surface.
 
+## Sampling
+
+`temperature`, `top_p`, `top_k`, and `seed` are optional on every model entry
+and may also be set per agent (a `sampling:` block) or per invocation
+(`--temperature/--top-p/--top-k/--seed`, or `/sampling` inside `haru chat`).
+Precedence is CLI/REPL → agent → model, merged per-field; unset fields are
+omitted from requests. `temperature`/`top_p` map to the Converse inference
+configuration; `top_k` and `seed` travel via
+`additionalModelRequestFields`. Claude 5-series and Opus 4.7+ models reject
+non-default sampling values (HTTP 400), and no Claude model honours `seed` —
+use these fields with models that accept them (for example Haiku 4.5).
+
 ## Sessions
 
 Conversation persistence is configured in the base file:

{haru_cli-0.1.0 → haru_cli-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "haru-cli"
-version = "0.1.0"
+version = "0.1.2"
 description = "Secure, scriptable CLI for Amazon Bedrock Claude models via the AWS Strands Agents SDK."
 readme = "README.md"
 license = "Apache-2.0"

{haru_cli-0.1.0 → haru_cli-0.1.2}/src/haru/agents/factory.py

@@ -15,9 +15,9 @@ from strands.models import BedrockModel
 from strands.session.session_manager import SessionManager
 from strands.tools.mcp import MCPClient
 
-from haru.config.schema import HaruConfig
+from haru.config.schema import HaruConfig, SamplingConfig
 from haru.errors import ConfigError
-from haru.models.bedrock import build_model, get_model_config
+from haru.models.bedrock import build_model, get_model_config, merge_sampling
 from haru.steering.prompts import DEFAULT_PROMPTS_ROOT, load_prompts, resolve_prompt
 from haru.tools.mcp import collect_tools
 
@@ -30,16 +30,33 @@ def build_agent(  # noqa: PLR0913 - keyword-only wiring points, all optional
     prompts_root: Path | None = None,
     mcp_clients: Mapping[str, MCPClient] | None = None,
     session_manager: SessionManager | None = None,
+    model_name: str | None = None,
+    sampling: SamplingConfig | None = None,
 ) -> Agent:
     """Build the named agent from configuration (default model when unnamed).
 
-    Raises ConfigError for unknown agents, prompt references, or tools.
+    ``model_name`` overrides the model for the default (unnamed) agent only;
+    named agents pin their own model. ``sampling`` overrides sampling fields
+    (precedence: this override, then the agent's ``sampling`` block, then the
+    model entry). Raises ConfigError for unknown agents, prompt references,
+    tools, or an invalid override.
     """
     if agent_name is None:
-        model = build_model(get_model_config(config), session, guardrails=config.guardrails)
+        model_cfg = get_model_config(config, model_name)
+        model = build_model(model_cfg, session, guardrails=config.guardrails, sampling=sampling)
         return Agent(model=model, session_manager=session_manager)
+    if model_name is not None:
+        raise ConfigError(
+            f"Agent {agent_name!r} pins its own model; model overrides apply"
+            " to the default agent only"
+        )
     model, system_prompt, tools = resolve_agent_parts(
-        config, agent_name, session, prompts_root=prompts_root, mcp_clients=mcp_clients
+        config,
+        agent_name,
+        session,
+        prompts_root=prompts_root,
+        mcp_clients=mcp_clients,
+        sampling=sampling,
     )
     return Agent(
         model=model,
@@ -50,13 +67,14 @@ def build_agent(  # noqa: PLR0913 - keyword-only wiring points, all optional
     )
 
 
-def resolve_agent_parts(
+def resolve_agent_parts(  # noqa: PLR0913 - keyword-only wiring points, all optional
     config: HaruConfig,
     agent_name: str,
     session: boto3.Session,
     *,
     prompts_root: Path | None = None,
     mcp_clients: Mapping[str, MCPClient] | None = None,
+    sampling: SamplingConfig | None = None,
 ) -> tuple[BedrockModel, str | None, list[Any]]:
     """Resolve an agent's model, steering prompt, and tool list from config."""
     if config.agents is None or agent_name not in config.agents.agents:
@@ -64,7 +82,10 @@ def resolve_agent_parts(
         raise ConfigError(f"Unknown agent {agent_name!r}; configured agents: {available}")
     agent_cfg = config.agents.agents[agent_name]
     model = build_model(
-        get_model_config(config, agent_cfg.model), session, guardrails=config.guardrails
+        get_model_config(config, agent_cfg.model),
+        session,
+        guardrails=config.guardrails,
+        sampling=merge_sampling(agent_cfg.sampling, sampling),
     )
 
     system_prompt: str | None = None

{haru_cli-0.1.0 → haru_cli-0.1.2}/src/haru/cli.py

@@ -2,7 +2,9 @@
 
 import click
 
+from haru.commands.agents import agents
 from haru.commands.chat import chat
+from haru.commands.config import config
 from haru.commands.login import login
 from haru.commands.run import run
 from haru.commands.session import session
@@ -14,7 +16,9 @@ def cli() -> None:
     """haru: a governed CLI for Amazon Bedrock agents."""
 
 
+cli.add_command(agents)
 cli.add_command(chat)
+cli.add_command(config)
 cli.add_command(login)
 cli.add_command(run)
 cli.add_command(session)

haru_cli-0.1.2/src/haru/commands/agents.py

@@ -0,0 +1,42 @@
+"""The ``haru agents`` command: list configured agents."""
+
+from pathlib import Path
+
+import click
+
+from haru.config import load_config, resolve_config_path
+from haru.errors import HaruError
+
+
+@click.command()
+@click.option(
+    "--config",
+    "config_path",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    default=None,
+    help="Path to haru.yaml (default: ./config/haru.yaml, then ~/.config/haru/haru.yaml).",
+)
+def agents(config_path: Path | None) -> None:
+    """List configured agents (model, prompt, tools, MCP servers)."""
+    try:
+        loaded = load_config(resolve_config_path(config_path))
+    except HaruError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    if loaded.agents is None or not loaded.agents.agents:
+        click.echo("No agents configured; chat uses the default agent.")
+        return
+    for name in sorted(loaded.agents.agents):
+        entry = loaded.agents.agents[name]
+        parts = [f"model={entry.model}"]
+        if entry.system_prompt_ref:
+            parts.append(f"prompt={entry.system_prompt_ref}")
+        if entry.tools:
+            parts.append(f"tools={','.join(entry.tools)}")
+        if entry.mcp_servers:
+            parts.append(f"mcp={','.join(entry.mcp_servers)}")
+        click.echo(f"{name:<14} {'  '.join(parts)}")
+    if loaded.agents.orchestration is not None:
+        click.echo(
+            f"\nDefault orchestration pattern: {loaded.agents.orchestration.default_pattern}"
+        )