hyperagents 1.2.3rc5.post3__py3-none-any.whl

hyperclaw/solomon.py

@@ -0,0 +1,442 @@
+"""
+HyperClaw Chat Agent
+Simple chat interface used by Telegram bot and scheduler (chat-only, no tools).
+Every prompt is built for a chat scope (hyperclaw.chat_scope): GUEST unless
+the caller proves the chat is the owner's.
+Users can customize the AI name and personality via workspace files.
+"""
+
+import logging
+import os
+import asyncio
+from datetime import datetime
+from pathlib import Path
+from typing import AsyncIterator, Optional
+
+import anthropic
+from hyperclaw.api_utils import extract_text
+from dotenv import load_dotenv
+
+from hyperclaw import cost_guard
+from hyperclaw.chat_scope import GUEST, GUEST_RULES, OWNER
+from hyperclaw.cost_guard import guard_client
+from hyperclaw.chat_scope import normalize as normalize_scope
+
+_OPENAI_API_BASE = os.environ.get("OPENAI_API_BASE", "")
+_USE_OPENAI_COMPAT = bool(_OPENAI_API_BASE)
+
+load_dotenv()
+
+# Paths - use environment variable or default to ~/.hyperclaw
+HYPERCLAW_ROOT = Path(os.environ.get("HYPERCLAW_ROOT", Path.home() / ".hyperclaw"))
+WORKSPACE_PATH = HYPERCLAW_ROOT / "workspace"
+MEMORY_PATH = HYPERCLAW_ROOT / "memory"
+
+MODEL = os.environ.get("OPENAI_MODEL") or os.environ.get("HYPERCLAW_MODEL", "claude-sonnet-4-6")
+# Legacy override for the chat-reply max output; the per-path setting is
+# config.json cost_guard.max_output_tokens_per_path["telegram"] (default 4096).
+MAX_TOKENS = int(os.environ.get("HYPERCLAW_MAX_TOKENS", 4096))
+MAX_HISTORY = 20
+MAX_OUTPUT_PATH = "telegram"
+
+
+def chat_max_tokens(provider: str, model: str) -> int:
+    """The explicit max output for one chat reply (cost guard: every path sets
+    one, within the per-task cap for this model)."""
+    env = os.environ.get("HYPERCLAW_MAX_TOKENS", "").strip()
+    return cost_guard.max_output(MAX_OUTPUT_PATH, provider, model,
+                                 requested=int(env) if env.isdigit() else None)
+
+
+def chat_thinking_on() -> bool:
+    """Every chat answer streams its reasoning, Ask included (Vaughn, 7 Oct 2026,
+    item 12: "My live-reasoning standard applies to every answer, Ask included").
+    HYPERCLAW_CHAT_THINKING=off is the switch that turns it off."""
+    return os.environ.get("HYPERCLAW_CHAT_THINKING", "on").strip().lower() != "off"
+
+
+def chat_request_kwargs(prov_kind: str, model: str, method=None, provider: str = "") -> dict:
+    """Request kwargs for one chat turn on this provider.
+
+    Messages-API providers: max_tokens plus the model's thinking parameters from
+    anthropic_params (the one place that decides them), at low effort for these
+    Ask-style chat answers; with the switch off, max_tokens only.
+    OpenAI-compatible providers (HyperSpeed V2 on vLLM reasons by default): nothing
+    extra while on; with the switch off, the chat-template switch that stops it.
+    Hosted OpenAI-schema providers ("openai") get max_tokens only.
+    """
+    mx = chat_max_tokens(provider or prov_kind, model)
+    if prov_kind == "anthropic":
+        from hyperclaw.anthropic_params import as_sdk_kwargs, thinking_params
+        if not chat_thinking_on():
+            return {"max_tokens": mx}
+        params = thinking_params(model, mx, overrides={"effort": "low"})
+        return as_sdk_kwargs(params, method) if method is not None else params
+    kwargs: dict = {"max_tokens": mx}
+    if prov_kind == "openai_compat" and not chat_thinking_on():
+        kwargs["extra_body"] = {"chat_template_kwargs": {"enable_thinking": False}}
+    return kwargs
+
+# Context files to load (in order, skip if missing)
+CONTEXT_FILES = [
+    "ASSISTANT.md",  # AI personality and name
+    "USER.md",       # User preferences
+    "MEMORY.md",     # Working memory
+]
+
+
+def _get_identity() -> tuple:
+    """(ai_name, user_name) — onboarding writes ~/.hyperclaw/config.json;
+    older builds used config/settings.json. Check both, in that order."""
+    import json
+    for cf in (HYPERCLAW_ROOT / "config.json",
+               HYPERCLAW_ROOT / "config" / "settings.json"):
+        if cf.exists():
+            try:
+                config = json.loads(cf.read_text())
+                return (config.get("ai_name") or os.environ.get("HYPERCLAW_AI_NAME", "Assistant"),
+                        config.get("user_name") or "")
+            except Exception:
+                continue
+    return (os.environ.get("HYPERCLAW_AI_NAME", "Assistant"), "")
+
+
+def _get_ai_name() -> str:
+    return _get_identity()[0]
+
+
+def _model_family(model: str) -> str:
+    """Human-readable family for a model id, or "" if unknown."""
+    m = model.lower()
+    if "hyperspeed" in m or m.startswith("hyper-nimbus/"):
+        return "HyperAI"
+    if "claude" in m:
+        return "Claude"
+    return ""
+
+
+class ChatAgent:
+    """Chat agent - manages conversation and context."""
+
+    def __init__(self):
+        if _USE_OPENAI_COMPAT:
+            import openai
+            self._oai = guard_client(openai.AsyncOpenAI(
+                api_key=os.environ.get("OPENAI_API_KEY", ""),
+                base_url=_OPENAI_API_BASE,
+            ))
+            self.client = None
+        else:
+            self._oai = None
+            self.client = guard_client(
+                anthropic.Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY", "")), "anthropic")
+        self.ai_name, self.user_name = _get_identity()
+        self.system_prompt = self._load_system_prompt()
+
+    def _load_system_prompt(self, model: str = "", scope: str = GUEST) -> str:
+        """Build the system prompt (hyperclaw.prompt_assembly order).
+
+        model: the model id actually serving the conversation; defaults to
+        the configured MODEL so callers routing to another provider can
+        rebuild the prompt with the real model.
+        scope: chat_scope.OWNER or GUEST. Anything but OWNER gets the guest
+        prompt: no persona, no standing instructions, no USER/MEMORY files,
+        no daily log, no owner name (spec §6 guest fence; benchmark 4.1).
+        Truth rules and the access manifest always come first (spec §14)."""
+        from hyperclaw.prompt_assembly import assemble, identity_block, persona_for
+        from hyperclaw.truth_guard import TRUTH_RULES, access_manifest
+
+        model = model or MODEL
+        scope = normalize_scope(scope)
+        owner = scope == OWNER
+        identity = identity_block(self.ai_name, self.user_name if owner else "",
+                                  scope, model=model, family=_model_family(model))
+        surface = "\n".join([
+            "## Core Behaviors",
+            "- Be helpful, accurate, and concise",
+            "- Execute tasks proactively when given clear instructions",
+            "- Ask clarifying questions when needed",
+            "- Be honest about limitations",
+            "",
+            f"Current date: {datetime.now().strftime('%Y-%m-%d %H:%M')}",
+        ])
+        access = access_manifest("chat_only", surface="telegram", scope=scope)
+        if not owner:
+            # Guest fence: nothing from the owner's workspace or memory.
+            return assemble(truth_rules=TRUTH_RULES, access=access, identity=identity,
+                            scope=scope, surface_instructions=surface)
+
+        # Legacy persona file from older onboarding: kept as the owner's
+        # standing instructions, below the truth rules.
+        standing = ""
+        claude_md = HYPERCLAW_ROOT / "CLAUDE.md"
+        if claude_md.exists():
+            try:
+                standing = claude_md.read_text(encoding="utf-8")
+            except Exception:
+                standing = ""
+
+        context = []
+        for filename in CONTEXT_FILES:
+            filepath = WORKSPACE_PATH / filename
+            if filepath.exists():
+                try:
+                    content = filepath.read_text(encoding="utf-8")
+                    context.append(f"## {filename}\n{content}")
+                except Exception:
+                    pass
+
+        today = datetime.now().strftime("%Y-%m-%d")
+        log_path = MEMORY_PATH / f"{today}.md"
+        if log_path.exists():
+            try:
+                content = log_path.read_text(encoding="utf-8")
+                context.append(f"## Today's Log ({today})\n{content}")
+            except Exception:
+                pass
+
+        return assemble(truth_rules=TRUTH_RULES, access=access, identity=identity,
+                        scope=scope, surface_instructions=surface,
+                        persona=persona_for(scope), standing=standing, context=context)
+
+    async def chat(self, message: str, history: list[dict], scope: str = GUEST,
+                   unattended: Optional[bool] = None) -> str:
+        """Send a message and get a response. scope defaults to GUEST
+        (fail closed); owner-only callers such as the scheduler pass OWNER.
+
+        Goes through the provider registry like stream_events, so the
+        scheduler works on a HyperSpeed V2-only install and honours a
+        Hyper-deployed install's V2-only rule.
+
+        unattended: a job with nobody waiting on the answer (the scheduler).
+        None means "owner scope with no conversation", which is how the
+        scheduler calls this. At a cost cap an unattended job stops and
+        returns a notice for the owner only (scheduler output goes only to
+        the owner's chat); it never gets a cheaper model."""
+        if unattended is None:
+            unattended = normalize_scope(scope) == OWNER and not history
+        out = []
+        try:
+            with cost_guard.task(surface="scheduler" if unattended else "chat", request=message,
+                                 unattended=unattended, owner=normalize_scope(scope) == OWNER):
+                async for kind, chunk in self.stream_events(message, history, scope=scope):
+                    if kind == "text":
+                        out.append(chunk)
+        except Exception as e:
+            # In-band marker: consumers strip it (strip_internal_errors) and
+            # show a notices.py failure notice; the detail is logged here.
+            logging.getLogger("hyperclaw.solomon").error("chat failed: %s", e, exc_info=True)
+            return f"[Error: {e}]"
+        return "".join(out)
+
+    async def _attempt_stream(self, prov, model, messages,
+                              scope: str = GUEST) -> AsyncIterator[tuple]:
+        """One provider attempt for stream_events — yields ("thinking"|"text", delta)."""
+        system = self._load_system_prompt(model, scope=scope)
+        if prov.kind == "anthropic":
+            from hyperclaw.model_catalog import TELEGRAM, is_selected
+            if not is_selected(TELEGRAM, getattr(prov, "name", ""), model):  # /model wins
+                model = os.environ.get("HYPERCLAW_MODEL", "").strip() or model
+            async_client = guard_client(anthropic.AsyncAnthropic(api_key=prov.api_key),
+                                        getattr(prov, "name", None))
+            async with async_client.messages.stream(
+                model=model,
+                system=system,
+                messages=messages,
+                **chat_request_kwargs(prov.kind, model, async_client.messages.stream,
+                                      provider=getattr(prov, "name", "") or ""),
+            ) as stream:
+                async for event in stream:
+                    if event.type == "content_block_delta":
+                        dtype = getattr(event.delta, "type", "")
+                        if dtype == "thinking_delta":
+                            yield ("thinking", event.delta.thinking)
+                        elif dtype == "text_delta":
+                            yield ("text", event.delta.text)
+            return
+        # openai_compat / openai: chat-completions schema, text content only
+        from openai import AsyncOpenAI
+        client = guard_client(AsyncOpenAI(api_key=prov.api_key, base_url=prov.base_url or None),
+                              getattr(prov, "name", None))
+        oai = [{"role": "system", "content": system}]
+        for m in messages:
+            c = m.get("content")
+            if isinstance(c, list):
+                c = "\n".join(b.get("text", "") for b in c
+                              if isinstance(b, dict) and b.get("type") == "text")
+            if c:
+                oai.append({"role": m["role"], "content": c})
+        from hyperclaw.xai import clean_request
+        stream = await client.chat.completions.create(
+            model=model, messages=oai, stream=True,
+            **clean_request(getattr(prov, "name", ""), getattr(prov, "base_url", ""), model,
+                            chat_request_kwargs(prov.kind, model,
+                                                provider=getattr(prov, "name", "") or "")),
+        )
+        # Reasoning (vLLM reasoning_content / inline <think>) -> "thinking",
+        # answer -> "text" with its leading blank lines dropped.
+        from hyperclaw.oai_stream import DeltaSplitter
+        splitter = DeltaSplitter()
+        async for chunk in stream:
+            if not chunk.choices:
+                continue   # e.g. the trailing usage-only chunk
+            # reasoning_content / reasoning -> ("thinking", ...); content -> ("text", ...)
+            for item in splitter.feed(chunk.choices[0].delta):
+                yield item
+        for item in splitter.flush():
+            yield item
+
+    async def stream_events(self, message: str, history: list[dict],
+                            attachments: list | None = None,
+                            scope: str = GUEST, _unattended: bool = False) -> AsyncIterator[tuple]:
+        """Stream ("thinking", delta) and ("text", delta) tuples.
+
+        Routes by capability: plain text turns use the `primary` slot,
+        attachment turns need documents/images and use `vision`. Failover
+        walks the slot ladder before the first token; a mid-stream death is
+        marked, never re-answered.
+
+        One call is one task for the cost guard (spec §9). At a cap no model
+        call is made: the owner gets the stop-and-ask message, a guest a
+        neutral reply (the owner is notified), an unattended job a notice
+        for the owner. Owner answers above the threshold end with a spend line.
+        """
+        owner = normalize_scope(scope) == OWNER
+        with cost_guard.task(surface="chat", request=message, owner=owner,
+                             unattended=_unattended) as task:
+            if owner and not task.unattended:
+                notices = cost_guard.take_owner_notices()
+                if notices:
+                    yield ("text", "\n".join(notices) + "\n\n")
+            answered = False
+            try:
+                async for item in self._stream_events(message, history, attachments, scope):
+                    answered = answered or item[0] == "text"
+                    yield item
+            except client_guard_blocked() as blocked:
+                # The final check stopped an outside-model request: nothing was sent.
+                yield ("text", ("\n\n" if answered else "") + blocked.user_message)
+                return
+            except cost_guard.CostCapReached as cap:
+                if task.unattended:
+                    yield ("text", cost_guard.unattended_message(cap))
+                else:
+                    yield ("text", ("\n\n" if answered else "")
+                           + cost_guard.stop_message(cap, owner=owner))
+                return
+            # Restricted-client guard: say plainly what was left out (and that
+            # HyperSpeed V2 includes it), on every answer that withheld something.
+            from hyperclaw import client_guard
+            note = client_guard.reply_note(task)
+            if note:
+                yield ("text", "\n\n" + note)
+            if owner and answered and not task.unattended:
+                line = cost_guard.spend_line(task)
+                if line:
+                    yield ("text", "\n\n" + line)
+
+    async def _stream_events(self, message: str, history: list[dict],
+                             attachments: list | None = None,
+                             scope: str = GUEST) -> AsyncIterator[tuple]:
+        from hyperclaw.providers import registry, stream_with_failover
+
+        messages = self._prepare_messages(message, history, attachments)
+        kinds = {b.get("type") for b in (attachments or []) if isinstance(b, dict)}
+        if kinds & {"document", "image"}:
+            # Native file blocks need a provider that reads them. Text-only
+            # attachments (inlined files, locally extracted PDF text) ride
+            # the primary slot like any chat turn — HyperSpeed V2 included.
+            need = {"chat"} | ({"documents"} if "document" in kinds else set()) \
+                | ({"images"} if "image" in kinds else set())
+            slot = "vision"
+        else:
+            slot, need = "primary", {"chat", "streaming"}
+        # /model on Telegram (docs/MODEL-SWITCHING.md): the chosen model first.
+        from hyperclaw.model_catalog import TELEGRAM, prefer_selected
+        reg = registry()
+        candidates = prefer_selected(reg, TELEGRAM, reg.resolve(slot, need), need)
+        # No automatic fallback to a third-party provider without the owner's
+        # consent (model_policy); the allowed list already filtered resolve().
+        from hyperclaw.model_policy import fallback_ladder
+        candidates = fallback_ladder(candidates)
+        if not candidates:
+            yield ("text", f"[Error: no configured provider supports this turn ({slot})]")
+            return
+
+        async def attempt(prov, model):
+            async for item in self._attempt_stream(prov, model, messages, scope=scope):
+                yield item
+
+        async for item in stream_with_failover(candidates, attempt):
+            yield item
+
+    async def stream_chat(self, message: str, history: list[dict],
+                          scope: str = GUEST) -> AsyncIterator[str]:
+        """Stream a response token by token."""
+        messages = self._prepare_messages(message, history)
+        system_prompt = self._load_system_prompt(scope=scope)
+        try:
+            if _USE_OPENAI_COMPAT:
+                stream = await self._oai.chat.completions.create(
+                    model=MODEL,
+                    max_tokens=chat_max_tokens("openai", MODEL),
+                    messages=[{"role": "system", "content": system_prompt}] + messages,
+                    stream=True,
+                )
+                async for chunk in stream:
+                    delta = chunk.choices[0].delta.content
+                    if delta:
+                        yield delta
+            else:
+                async_client = guard_client(anthropic.AsyncAnthropic(
+                    api_key=os.environ.get("ANTHROPIC_API_KEY", "")), "anthropic")
+                async with async_client.messages.stream(
+                    model=MODEL,
+                    max_tokens=chat_max_tokens("anthropic", MODEL),
+                    system=system_prompt,
+                    messages=messages,
+                ) as stream:
+                    async for text in stream.text_stream:
+                        yield text
+        except Exception as e:
+            yield f"[Error: {e}]"
+
+    def _prepare_messages(self, message: str, history: list[dict],
+                          attachments: list | None = None) -> list[dict]:
+        """Prepare messages for the API call, trimming to MAX_HISTORY.
+
+        attachments: optional Anthropic content blocks (document / image)
+        that ride along with the user's text — how Telegram file uploads
+        reach the model."""
+        recent = history[-MAX_HISTORY:] if len(history) > MAX_HISTORY else history
+        if attachments:
+            content = list(attachments) + [{"type": "text", "text": message or "(see attached)"}]
+            return list(recent) + [{"role": "user", "content": content}]
+        return list(recent) + [{"role": "user", "content": message}]
+
+    def reload_context(self) -> None:
+        """Reload the system prompt (hot-reload without restart)."""
+        self.ai_name = _get_ai_name()
+        self.system_prompt = self._load_system_prompt()
+
+
+# Singleton instance
+_agent: Optional[ChatAgent] = None
+
+
+def get_chat_agent() -> ChatAgent:
+    """Get or create the chat agent singleton."""
+    global _agent
+    if _agent is None:
+        _agent = ChatAgent()
+    return _agent
+
+
+# Backwards compatibility aliases
+Solomon = ChatAgent
+get_solomon = get_chat_agent
+
+
+def client_guard_blocked():
+    from hyperclaw.client_guard import RestrictedContentBlocked
+    return RestrictedContentBlocked