hyperagents 1.2.3rc5.post3__py3-none-any.whl

hyperclaw/naming.py

@@ -0,0 +1,284 @@
+"""Naming the assistant: the first step of onboarding (spec §14).
+
+The customer either types a name, or asks for a suggestion. A suggestion is
+ONE name plus a one-sentence reason, generated by the configured model when
+one is reachable, otherwise taken from a fixed starter list (deterministic
+order). The customer keeps it, asks for another, or types their own. The
+chosen name is stored in the customer's own config.json.
+
+Everything here is chat-only: no tools, any model, or no model at all.
+:class:`NamingFlow` is a plain state machine, so the command-line
+onboarding, the terminal first run and the Telegram first run share the
+same steps and wording.
+"""
+from __future__ import annotations
+
+import logging
+import re
+from typing import Callable, Optional
+
+log = logging.getLogger("hyperclaw.naming")
+
+# Starter list used when no model is reachable. Written fresh for HyperClaw.
+FALLBACK_NAMES = [
+    ("Juniper", "It's evergreen and steady, the kind of name that stays useful in every season."),
+    ("Wren", "Wrens are small, quick and attentive, which is how a good assistant should feel."),
+    ("Harbor", "A harbor is where things come in and get sorted out safely."),
+    ("Quill", "It's a nod to all the notes, drafts and messages we'll write together."),
+    ("Linden", "Linden trees are the shady spot people gather under: calm, dependable company."),
+    ("Beacon", "It keeps watch and points you to what needs your attention."),
+    ("Indigo", "A deep, calm color for an assistant that stays unhurried when you're busy."),
+    ("Compass", "It's there to help you find your way through a crowded day."),
+    ("Sable", "It's short, distinctive and easy to say in a hurry."),
+    ("Marlo", "It's friendly and a little uncommon, so it's clearly yours."),
+]
+
+SUGGEST_WORDS = {"", "suggest", "suggest one", "you pick", "pick one", "surprise me",
+                 "you choose", "choose", "s", "?"}
+KEEP_WORDS = {"", "y", "yes", "keep", "keep it", "ok", "okay", "sure", "sounds good",
+              "love it", "perfect", "k"}
+ANOTHER_WORDS = {"a", "another", "another one", "next", "no", "n", "different",
+                 "something else", "try again", "again"}
+
+MAX_NAME = 32
+_NAME_OK = re.compile(r"^[A-Za-z0-9][A-Za-z0-9 .'\-]*$")
+
+# ── exact wording (shared by every surface) ─────────────────────────────
+INTRO = ("First, let's give me a name. Type a name you like, or say \"suggest\" "
+         "and I'll propose one.")
+PROPOSAL = ("How about {name}? {reason}\n"
+            "Say \"yes\" to keep it, \"another\" for a different one, or type a name of your own.")
+CONFIRMED = "{name} it is. That's saved in your config, and you can change it any time with /name."
+FALLBACK_NOTE = ("(I picked that from my starter list because no model is connected yet. "
+                 "Once one is, /name suggest lets me come up with a name myself.)")
+KEEP_OR_NEW = "Keep '{name}', or choose a new name?"
+KEPT = "Keeping the name {name}."
+# Terminal wording for the same question (no buttons): keep (or Enter) / new.
+KEEP_OR_NEW_PROMPT = "Keep '{name}', or choose a new name? (keep / new, Enter = keep)"
+KEEP_ANSWERS = {"", "keep", "k", "keep it", "yes", "y"}
+NEW_ANSWERS = {"new", "n", "choose new", "choose a new name", "change", "new name"}
+INVALID = ("That name won't work ({why}). Type a name of up to {max} letters, numbers or "
+           "spaces, or say \"suggest\".")
+
+
+def validate_name(text: str) -> tuple:
+    """(clean_name, "") or ("", reason)."""
+    name = re.sub(r"\s+", " ", (text or "").strip()).strip("\"'")
+    if not name:
+        return "", "it's empty"
+    if len(name) > MAX_NAME:
+        return "", f"it's longer than {MAX_NAME} characters"
+    if len(name.split()) > 3:
+        return "", "keep it to three words or fewer"
+    if not _NAME_OK.match(name) or not re.search(r"[A-Za-z]", name):
+        return "", "use letters, numbers, spaces, apostrophes or hyphens"
+    return name, ""
+
+
+# ── proposals ───────────────────────────────────────────────────────────
+
+PROPOSE_PROMPT = (
+    "Suggest ONE short, friendly name for a new personal AI assistant, and give a "
+    "one-sentence reason for it. Do not use any of these names: {avoid}. "
+    "Reply on a single line exactly in this form:\n"
+    "NAME: <name> | REASON: <one sentence>"
+)
+_REPLY = re.compile(r"NAME:\s*(.+?)\s*\|\s*REASON:\s*(.+)", re.I | re.S)
+
+
+def _first_sentence(text: str) -> str:
+    t = re.sub(r"\s+", " ", text or "").strip()
+    m = re.match(r"(.+?[.!?])(\s|$)", t)
+    t = m.group(1) if m else t
+    return t[:200]
+
+
+def parse_model_reply(text: str, avoid: set) -> Optional[tuple]:
+    m = _REPLY.search(text or "")
+    if not m:
+        return None
+    name, why = validate_name(m.group(1).strip().strip("*_`"))
+    reason = _first_sentence(m.group(2).strip().strip("*_`"))
+    if why or not reason or name.lower() in {a.lower() for a in avoid}:
+        return None
+    if not reason.endswith((".", "!", "?")):
+        reason += "."
+    return name, reason
+
+
+def fallback_proposal(avoid: set) -> tuple:
+    low = {a.lower() for a in avoid}
+    for name, reason in FALLBACK_NAMES:
+        if name.lower() not in low:
+            return name, reason
+    # Every starter name was turned down: cycle deterministically.
+    name, reason = FALLBACK_NAMES[len(avoid) % len(FALLBACK_NAMES)]
+    return name, reason
+
+
+def propose_name(avoid: set, model_call: Optional[Callable[[str], Optional[str]]] = None) -> tuple:
+    """(name, reason, source) with source "model" or "fallback"."""
+    if model_call is not None:
+        try:
+            reply = model_call(PROPOSE_PROMPT.format(
+                avoid=", ".join(sorted(avoid)) or "none"))
+            parsed = parse_model_reply(reply or "", avoid)
+            if parsed:
+                return parsed[0], parsed[1], "model"
+        except Exception as e:  # unreachable, timeout, bad reply: fall back
+            log.info(f"name proposal fell back to the starter list: {e}")
+    name, reason = fallback_proposal(avoid)
+    return name, reason, "fallback"
+
+
+def default_model_call(timeout: float = 20.0) -> Optional[Callable[[str], Optional[str]]]:
+    """A one-shot, tool-free text call on the configured chat model, or None
+    when no model is configured (then the starter list is used)."""
+    try:
+        from hyperclaw.providers import registry
+        cands = registry().resolve("primary", {"chat"})
+    except Exception:
+        return None
+    if not cands:
+        return None
+    prov, model = cands[0]
+
+    def call(prompt: str) -> Optional[str]:
+        from hyperclaw.cost_guard import guard_client, max_output
+        if prov.kind == "anthropic":
+            import anthropic
+            from hyperclaw.api_utils import extract_text
+            client = guard_client(anthropic.Anthropic(api_key=prov.api_key, timeout=timeout,
+                                                      max_retries=0), getattr(prov, "name", None))
+            resp = client.messages.create(model=model,
+                                          max_tokens=max_output("naming", prov.name, model),
+                                          messages=[{"role": "user", "content": prompt}])
+            return extract_text(resp)
+        import openai
+        client = guard_client(openai.OpenAI(api_key=prov.api_key or "unused",
+                                           base_url=prov.base_url or None, timeout=timeout,
+                                           max_retries=0), getattr(prov, "name", None))
+        resp = client.chat.completions.create(
+            model=model, max_tokens=max_output("naming", prov.name, model),
+            messages=[{"role": "user", "content": prompt}])
+        return resp.choices[0].message.content if resp.choices else None
+
+    return call
+
+
+# ── storage ─────────────────────────────────────────────────────────────
+
+def current_name() -> str:
+    from hyperclaw.userconfig import load_config
+    return str(load_config().get("ai_name") or "").strip()
+
+
+def is_named() -> bool:
+    return bool(current_name())
+
+
+def save_name(name: str, source: str) -> None:
+    """source: "customer" (typed) or "suggested:model" / "suggested:fallback"."""
+    from hyperclaw.userconfig import update_config
+    update_config(ai_name=name, ai_name_source=source)
+
+
+# ── the flow ────────────────────────────────────────────────────────────
+
+class NamingFlow:
+    """ask -> (typed name | suggestion -> keep / another / typed) -> done."""
+
+    def __init__(self, model_call: Optional[Callable] = None, save: bool = True):
+        self.model_call = model_call
+        self.save = save
+        self.state = "ask"
+        self.proposed: Optional[tuple] = None
+        self.offered: list = []
+        self.name: str = ""
+        self.source: str = ""
+
+    def start(self) -> str:
+        self.state = "ask"
+        return INTRO
+
+    def suggest(self) -> str:
+        name, reason, source = propose_name(set(self.offered), self.model_call)
+        self.offered.append(name)
+        self.proposed = (name, reason, source)
+        self.state = "proposed"
+        return PROPOSAL.format(name=name, reason=reason)
+
+    def _finish(self, name: str, source: str) -> str:
+        self.name, self.source, self.state = name, source, "done"
+        if self.save:
+            save_name(name, source)
+        msg = CONFIRMED.format(name=name)
+        if source == "suggested:fallback":
+            msg += "\n" + FALLBACK_NOTE
+        return msg
+
+    def handle(self, text: str) -> str:
+        t = (text or "").strip()
+        low = t.lower().rstrip(".!")
+        if self.state == "ask":
+            if low in SUGGEST_WORDS:
+                return self.suggest()
+        elif self.state == "proposed":
+            if low in KEEP_WORDS:
+                name, _, source = self.proposed
+                return self._finish(name, f"suggested:{source}")
+            if low in ANOTHER_WORDS or low in SUGGEST_WORDS:
+                return self.suggest()
+        elif self.state == "done":
+            return CONFIRMED.format(name=self.name)
+        name, why = validate_name(t)
+        if why:
+            return INVALID.format(why=why, max=MAX_NAME)
+        return self._finish(name, "customer")
+
+    @property
+    def done(self) -> bool:
+        return self.state == "done"
+
+
+def run_interactive(ask: Callable[[str], str], say: Callable[[str], None],
+                    model_call: Optional[Callable] = None, save: bool = True) -> str:
+    """Drive the flow with a prompt function (terminal / onboarding).
+    ask(label) returns the customer's line; EOF/empty handling is the
+    caller's. Returns the chosen name."""
+    flow = NamingFlow(model_call=model_call, save=save)
+    say(flow.start())
+    label = "Name (Enter = suggest one)"
+    for _ in range(50):
+        reply = flow.handle(ask(label))
+        say(reply)
+        if flow.done:
+            return flow.name
+        label = ("Keep it? yes / another / or type a name" if flow.state == "proposed"
+                 else "Name (Enter = suggest one)")
+    # Pathological input loop: keep whatever was last proposed.
+    if flow.proposed:
+        say(flow.handle("yes"))
+    return flow.name
+
+
+def run_command(argv: list, model_call: Optional[Callable] = None) -> str:
+    """Non-interactive /name: show, set <name>, suggest (proposal only;
+    keep it with `/name <that name>`)."""
+    if not argv or argv[0].lower() in ("show",):
+        cur = current_name()
+        return (f"My name is {cur}." if cur else "I don't have a name yet. "
+                "Use /name <name>, or /name suggest.")
+    if argv[0].lower() == "suggest":
+        name, reason, source = propose_name({current_name()} - {""}, model_call)
+        msg = (f"How about {name}? {reason}\nTo keep it, send /name {name} "
+               f"(or /name suggest for another).")
+        if source == "fallback":
+            msg += "\n" + FALLBACK_NOTE
+        return msg
+    text = " ".join(argv[1:] if argv[0].lower() == "set" else argv)
+    name, why = validate_name(text)
+    if why:
+        return INVALID.format(why=why, max=MAX_NAME)
+    save_name(name, "customer")
+    return CONFIRMED.format(name=name)

hyperclaw/notices.py

@@ -0,0 +1,65 @@
+"""User-facing failure notices (standard ruled by Vaughn, 2026-10-10, 20.7).
+
+Every notice a user can see when something fails must:
+  1. say WHICH action failed ("I couldn't send that message"),
+  2. never imply success (no "sent", "done", "delivered", "completed"),
+  3. never carry the technical error. That goes to the log via log_failure().
+
+All user-visible failure wording lives here so Telegram, the scheduler,
+Solomon, the TUI bridge, the terminal and the HTTP chat say it one way.
+"""
+from __future__ import annotations
+
+import logging
+import re
+
+# action id -> the verb phrase after "I couldn't ..."
+ACTIONS: dict = {
+    "answer": "answer that message",
+    "send_message": "send that message",
+    "read_file": "read that file",
+    "write_file": "save that file",
+    "get_answer": "get an answer to that message",
+    "morning_brief": "finish the morning brief",
+    "heartbeat": "finish the heartbeat check",
+    "all_hands": "finish the all-hands report",
+    "request": "carry out that request",
+    "tool": "run that tool",
+}
+GENERIC_ACTION = "complete that request"
+_RETRY = "Please try again in a moment."
+
+# Words a failure notice must never contain (it would read as success).
+SUCCESS_WORDS = re.compile(
+    r"\b(sent|done|delivered|completed|succeeded|success|successfully|finished)\b", re.I)
+
+
+def action_phrase(action: str | None = None, what: str | None = None) -> str:
+    """The phrase naming the failed action. ``what`` is a free-form phrase
+    (e.g. "run the calendar tool") and wins over ``action``; an unknown or
+    missing action falls back to a generic phrase that still names a request."""
+    if what and what.strip():
+        return what.strip()
+    return ACTIONS.get(action or "", GENERIC_ACTION)
+
+
+def failure_notice(action: str | None = None, *, what: str | None = None,
+                   detail: str = "", retry: bool = True) -> str:
+    """'Sorry, I couldn't <action>. <detail> Please try again in a moment.'
+
+    ``detail`` is a plain-language sentence for the user (never exception text).
+    """
+    text = f"Sorry, I couldn't {action_phrase(action, what)}."
+    if detail:
+        text += " " + detail.strip()
+    if retry:
+        text += " " + _RETRY
+    return text
+
+
+def log_failure(logger: logging.Logger, action: str | None, error=None, *,
+                context: str = "", exc_info: bool = False) -> None:
+    """Log the technical error for a failed action (the only place it goes)."""
+    logger.error("%s failed%s: %s", action or "action",
+                 f" ({context})" if context else "", str(error)[:500] if error else "no detail",
+                 exc_info=exc_info)

hyperclaw/oai_stream.py

@@ -0,0 +1,106 @@
+"""Split OpenAI-compatible streaming deltas into ("thinking" | "text", str).
+
+Reasoning models served through vLLM (HyperSpeed V2 runs the qwen3
+reasoning parser) stream their chain of thought in a side field
+(``delta.reasoning_content``; newer vLLM builds call it ``delta.reasoning``)
+and the answer in ``delta.content``. Without a reasoning parser the same
+model writes ``<think>…</think>`` inline in ``content``. Either way the
+reasoning must never be shown or saved as the answer, and the answer's
+leading blank lines (qwen3 starts content with "\\n\\n") are dropped.
+
+Used by every OpenAI-schema streaming loop (solomon, the TUI) so they
+classify chunks the same way.
+"""
+
+REASONING_FIELDS = ("reasoning_content", "reasoning")
+OPEN_TAG, CLOSE_TAG = "<think>", "</think>"
+
+
+def _field(delta, name):
+    if delta is None:
+        return None
+    if isinstance(delta, dict):
+        return delta.get(name)
+    val = getattr(delta, name, None)
+    if val is None:
+        extra = getattr(delta, "model_extra", None) or {}
+        val = extra.get(name)
+    return val
+
+
+def _partial_tag_len(buf: str) -> int:
+    """Length of the longest suffix of buf that could start a think tag."""
+    for n in range(min(len(buf), len(CLOSE_TAG) - 1), 0, -1):
+        tail = buf[-n:]
+        if OPEN_TAG.startswith(tail) or CLOSE_TAG.startswith(tail):
+            return n
+    return 0
+
+
+class DeltaSplitter:
+    """Stateful: feed() each streamed delta, flush() once at the end."""
+
+    def __init__(self):
+        self.in_think = False
+        self.text_started = False
+        self._pending = ""
+        self.text_chars = 0
+        self.thinking_chars = 0
+
+    def _emit(self, out, kind, s):
+        if not s:
+            return
+        if kind == "text":
+            if not self.text_started:
+                s = s.lstrip()
+                if not s:
+                    return
+                self.text_started = True
+            self.text_chars += len(s)
+        else:
+            self.thinking_chars += len(s)
+        out.append((kind, s))
+
+    def feed(self, delta) -> list:
+        out = []
+        for name in REASONING_FIELDS:
+            r = _field(delta, name)
+            if isinstance(r, str) and r:
+                self._emit(out, "thinking", r)
+                break
+        content = _field(delta, "content")
+        if isinstance(content, str) and content:
+            self._feed_content(content, out)
+        return out
+
+    def _feed_content(self, s, out):
+        buf = self._pending + s
+        self._pending = ""
+        while buf:
+            if self.in_think:
+                i = buf.find(CLOSE_TAG)
+                if i >= 0:
+                    self._emit(out, "thinking", buf[:i])
+                    buf = buf[i + len(CLOSE_TAG):]
+                    self.in_think = False
+                    continue
+            else:
+                o, c = buf.find(OPEN_TAG), buf.find(CLOSE_TAG)
+                hits = [(i, t) for i, t in ((o, OPEN_TAG), (c, CLOSE_TAG)) if i >= 0]
+                if hits:
+                    i, tag = min(hits)
+                    self._emit(out, "text", buf[:i])
+                    buf = buf[i + len(tag):]
+                    self.in_think = tag == OPEN_TAG   # a stray </think> is dropped
+                    continue
+            keep = _partial_tag_len(buf)
+            self._emit(out, "thinking" if self.in_think else "text", buf[:len(buf) - keep])
+            self._pending = buf[len(buf) - keep:]
+            break
+
+    def flush(self) -> list:
+        out = []
+        if self._pending:
+            self._emit(out, "thinking" if self.in_think else "text", self._pending)
+            self._pending = ""
+        return out