couplet-core 0.1.0__tar.gz

couplet_core-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+.npmrc
+
+node_modules/
+.next/
+dist/
+.turbo/
+.env
+.env.local
+.test-token
+tests/RESULTS.md
+*.pyc
+__pycache__/
+.ruff_cache/
+.venv/
+uv.lock
+.DS_Store
+.source/
+*.tsbuildinfo

couplet_core-0.1.0/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2026 Couplet Contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

couplet_core-0.1.0/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: couplet-core
+Version: 0.1.0
+Summary: Couplet agent engine — ACS v1, harness, LLM client, tools, and skills
+Project-URL: Homepage, https://github.com/turbomesh/couplet
+Project-URL: Documentation, https://github.com/turbomesh/couplet/tree/main/packages/core
+Project-URL: Repository, https://github.com/turbomesh/couplet
+Project-URL: Issues, https://github.com/turbomesh/couplet/issues
+Author: Couplet Contributors
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: acs,agent,harness,llm,streaming
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.28.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# couplet-core
+
+Framework-agnostic Couplet agent engine for Python.
+
+## Install
+
+```bash
+pip install couplet-core
+```
+
+## What's included
+
+- **ACS v1** — typed streaming events and SSE serialization
+- **Agent harness** — tool loop with context compaction
+- **LLM client** — OpenAI-compatible API with retry/resilience
+- **Tools & skills** — handler registry and skill pack loader
+
+## Minimal embed
+
+```python
+from couplet_core.acs import event_to_sse
+from couplet_core.agent.harness import run_agent_turn
+from couplet_core.agent.types import AgentTurn
+
+async for event in run_agent_turn(turn, store=my_session_store):
+    print(event_to_sse(event))
+```
+
+See [couplet-runtime](https://github.com/turbomesh/couplet) for the reference FastAPI service.

couplet_core-0.1.0/README.md

@@ -0,0 +1,29 @@
+# couplet-core
+
+Framework-agnostic Couplet agent engine for Python.
+
+## Install
+
+```bash
+pip install couplet-core
+```
+
+## What's included
+
+- **ACS v1** — typed streaming events and SSE serialization
+- **Agent harness** — tool loop with context compaction
+- **LLM client** — OpenAI-compatible API with retry/resilience
+- **Tools & skills** — handler registry and skill pack loader
+
+## Minimal embed
+
+```python
+from couplet_core.acs import event_to_sse
+from couplet_core.agent.harness import run_agent_turn
+from couplet_core.agent.types import AgentTurn
+
+async for event in run_agent_turn(turn, store=my_session_store):
+    print(event_to_sse(event))
+```
+
+See [couplet-runtime](https://github.com/turbomesh/couplet) for the reference FastAPI service.

couplet_core-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[project]
+name = "couplet-core"
+version = "0.1.0"
+description = "Couplet agent engine — ACS v1, harness, LLM client, tools, and skills"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.11"
+authors = [{ name = "Couplet Contributors" }]
+keywords = ["agent", "llm", "acs", "streaming", "harness"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.28.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/turbomesh/couplet"
+Documentation = "https://github.com/turbomesh/couplet/tree/main/packages/core"
+Repository = "https://github.com/turbomesh/couplet"
+Issues = "https://github.com/turbomesh/couplet/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0.0", "pytest-asyncio>=0.24.0", "ruff>=0.8.0"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/couplet_core"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/couplet_core", "README.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"

couplet_core-0.1.0/src/couplet_core/__init__.py

@@ -0,0 +1,3 @@
+"""Couplet agent engine — ACS, harness, LLM, tools, and skills."""
+
+__version__ = "0.1.0"

couplet_core-0.1.0/src/couplet_core/_log.py

@@ -0,0 +1,3 @@
+import logging
+
+logger = logging.getLogger("couplet_core")

couplet_core-0.1.0/src/couplet_core/acs.py

@@ -0,0 +1,231 @@
+"""Structured streaming events — the agent→frontend delivery contract.
+
+Defines a typed event vocabulary that names *what happened* without
+prescribing *how it is rendered*. The frontend consumes these events to
+update the conversation view, tool progress, task board, and goal state.
+
+Backward compatibility: existing OpenAI-style SSE chunks are still emitted
+as `MessageChunk` events (or passed through directly), while these events
+provide richer presentation-layer state.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from typing import Any, Union
+
+
+# ── Message (assistant text) events ──────────────────────────────────────────
+
+@dataclass(frozen=True)
+class MessageChunk:
+    """A delta of streamed assistant text."""
+    text: str
+
+
+@dataclass(frozen=True)
+class MessageStop:
+    """The current assistant message segment is complete."""
+    final: bool = False
+
+
+@dataclass(frozen=True)
+class Commentary:
+    """A complete interim assistant message emitted between tool iterations."""
+    text: str
+
+
+# ── Tool-call events ─────────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class ToolCallChunk:
+    """A tool invocation has started or its arguments are still streaming."""
+    tool_name: str
+    preview: str | None = None
+    args: dict[str, Any] | None = None
+    index: int = 0
+
+
+@dataclass(frozen=True)
+class ToolCallFinished:
+    """A tool invocation completed."""
+    tool_name: str
+    duration: float = 0.0
+    ok: bool = True
+    index: int = 0
+
+
+# ── Chain events ─────────────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class ThinkingChunk:
+    """Incremental or final reasoning content."""
+    content: str
+    node_id: str | None = None
+
+
+@dataclass(frozen=True)
+class ToolCallEvent:
+    """A tool call persisted as a chain node."""
+    node_id: str
+    tool_name: str
+    tool_input: dict[str, Any] | None = None
+    title: str | None = None
+
+
+@dataclass(frozen=True)
+class ToolResultEvent:
+    """A tool result persisted as a chain node."""
+    node_id: str
+    tool_name: str
+    tool_output: dict[str, Any] | None = None
+    title: str | None = None
+
+
+@dataclass(frozen=True)
+class UserReplyEvent:
+    """A user reply to a clarify option, persisted as a chain node."""
+    node_id: str
+    content: str
+    parent_id: str | None = None
+
+
+@dataclass(frozen=True)
+class FinalEvent:
+    """The final summary (e.g. task_done) persisted as a chain node."""
+    node_id: str
+    content: str
+
+
+# ── Task / Goal events ───────────────────────────────────────────────────────
+
+# ── Error recovery events ────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class Retrying:
+    """An LLM call is being retried after a recoverable error."""
+    attempt: int
+    max_retries: int
+    delay: float
+    reason: str
+
+
+@dataclass(frozen=True)
+class ContextUsageCategory:
+    """A slice of the context window budget."""
+    id: str
+    label: str
+    tokens: int
+
+
+@dataclass(frozen=True)
+class ContextUsageEvent:
+    """Current context window usage (display-only for the frontend ring)."""
+    budget_tokens: int
+    used_tokens: int
+    used_percent: int
+    categories: list[dict[str, Any]] = field(default_factory=list)
+    source: str = "estimated"
+    estimated_tokens: int | None = None
+    prompt_tokens: int | None = None
+
+
+@dataclass(frozen=True)
+class ContextCompressed:
+    """Context was compressed before retry."""
+    pass
+
+
+@dataclass(frozen=True)
+class FallbackModel:
+    """A fallback model/provider was selected."""
+    model: str | None = None
+
+
+@dataclass(frozen=True)
+class FatalError:
+    """An unrecoverable error occurred."""
+    message: str
+
+
+# ── Gateway control / lifecycle events ───────────────────────────────────────
+
+@dataclass(frozen=True)
+class LongToolHint:
+    """A tool has been running for a while."""
+    tool_name: str = ""
+    duration: float = 0.0
+
+
+@dataclass(frozen=True)
+class ClarifyEvent:
+    """Agent needs user input before continuing."""
+    node_id: str
+    question: str
+    options: list[str] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class GatewayNotice:
+    """A gateway-originated control message."""
+    kind: str
+    text: str = ""
+    extra: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class OpenPageEvent:
+    """Open a console page in the right-side iframe panel."""
+    url: str
+    title: str | None = None
+
+
+@dataclass(frozen=True)
+class OpenExternalLinkEvent:
+    """Open an external URL in a new browser tab."""
+    url: str
+    title: str | None = None
+
+
+# ── Union type ───────────────────────────────────────────────────────────────
+
+StreamEvent = Union[
+    MessageChunk,
+    MessageStop,
+    Commentary,
+    ToolCallChunk,
+    ToolCallFinished,
+    ThinkingChunk,
+    ToolCallEvent,
+    ToolResultEvent,
+    UserReplyEvent,
+    FinalEvent,
+    ClarifyEvent,
+    ContextUsageEvent,
+    Retrying,
+    ContextCompressed,
+    FallbackModel,
+    FatalError,
+    LongToolHint,
+    GatewayNotice,
+    OpenPageEvent,
+    OpenExternalLinkEvent,
+]
+
+
+def event_to_sse(event: StreamEvent) -> str:
+    """Serialize a StreamEvent to an SSE data line.
+
+    Output shape: data: {"type":"event","event":{"kind":"...","...":"..."}}\n\n
+    """
+    payload = _event_to_payload(event)
+    return f'data: {json.dumps({"type": "event", "event": payload}, ensure_ascii=False)}\n\n'
+
+
+def _event_to_payload(event: StreamEvent) -> dict[str, Any]:
+    """Convert a dataclass event to a frontend-friendly dict with a `kind`."""
+    data = asdict(event)
+    kind = type(event).__name__
+    # Remove leading underscore if any and ensure camelCase-ish consistency.
+    return {"kind": kind, **data}

couplet_core-0.1.0/src/couplet_core/agent/compact.py

@@ -0,0 +1,209 @@
+"""Automatic context compaction — transparent to the user."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+from couplet_core.agent.config import (
+    COMPACT_RECENT_MESSAGES,
+    COMPACT_SUMMARY_MAX_CHARS,
+    COMPACT_THRESHOLD_RATIO,
+    COMPACTED_TOOL_MAX_CHARS,
+    MAX_CONTEXT_TOKENS,
+    STORED_SUMMARY_PREFIX,
+)
+from couplet_core.agent.tokens import approx_tokens, fit_context_budget
+
+
+@dataclass
+class CompactStats:
+    compacted: bool = False
+    tool_results_slimmed: int = 0
+    messages_replaced: int = 0
+    summary_generated: bool = False
+    summary_text: str = ""
+
+
+def is_stored_summary_message(msg: dict[str, Any]) -> bool:
+    content = msg.get("content") or ""
+    return isinstance(content, str) and content.startswith(STORED_SUMMARY_PREFIX)
+
+
+def merge_compact_summaries(existing: str | None, delta: str) -> str:
+    """Merge persisted and newly generated summaries into one block."""
+    parts = [part.strip() for part in (existing or "", delta) if part and part.strip()]
+    if not parts:
+        return ""
+    merged = "\n".join(parts)
+    if len(merged) <= COMPACT_SUMMARY_MAX_CHARS:
+        return merged
+    return merged[: COMPACT_SUMMARY_MAX_CHARS - 1] + "…"
+
+
+def inject_compact_summary(
+    messages: list[dict[str, Any]],
+    summary: str,
+) -> list[dict[str, Any]]:
+    """Ensure exactly one stored-summary user message after system prompts."""
+    if not summary.strip():
+        return messages
+
+    system_msgs = [m for m in messages if m.get("role") == "system"]
+    rest = [m for m in messages if m.get("role") != "system" and not is_stored_summary_message(m)]
+    summary_msg = {
+        "role": "user",
+        "content": f"{STORED_SUMMARY_PREFIX}\n{summary.strip()}",
+    }
+    return system_msgs + [summary_msg] + rest
+
+
+def build_compact_goal_state_patch(existing_goal_state: dict[str, Any] | None, summary: str) -> dict[str, Any]:
+    """Return goal_state fields to persist after generating a compact summary."""
+    if not summary:
+        return {}
+    state = dict(existing_goal_state or {})
+    state["compact_summary"] = summary
+    state["compact_version"] = int(state.get("compact_version") or 0) + 1
+    return state
+
+
+def _slim_tool_content(tool_name: str, raw: str, *, compact: bool) -> str:
+    if not compact:
+        return raw
+    limit = COMPACTED_TOOL_MAX_CHARS
+    if len(raw) <= limit:
+        return raw
+
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError:
+        return raw[:limit] + f"\n...[compacted, omitted {len(raw) - limit} chars]"
+
+    if isinstance(data, dict):
+        if data.get("error"):
+            return raw[:limit]
+        slim: dict[str, Any] = {"_compacted": True, "tool": tool_name}
+        for key in ("summary", "message", "detail", "job_id", "system_id", "id", "url", "status"):
+            if key in data and data[key] is not None:
+                slim[key] = data[key]
+        if isinstance(data.get("result"), (dict, list, str)):
+            slim["result"] = str(data["result"])[:200]
+        if len(slim) <= 2 and "result" not in slim:
+            slim["preview"] = str(data)[:300]
+        return json.dumps(slim, ensure_ascii=False)
+
+    if isinstance(data, list):
+        preview = data[:5]
+        slim = {
+            "_compacted": True,
+            "tool": tool_name,
+            "count": len(data),
+            "preview": preview,
+        }
+        return json.dumps(slim, ensure_ascii=False)
+
+    return raw[:limit] + "\n...[compacted]"
+
+
+def _build_rule_summary(messages: list[dict[str, Any]]) -> str:
+    """Extract salient points from older messages for a compact summary."""
+    lines: list[str] = []
+    for msg in messages:
+        role = msg.get("role")
+        content = (msg.get("content") or "").strip()
+        if not content or is_stored_summary_message(msg):
+            continue
+
+        if role == "user":
+            if len(content) <= 300:
+                lines.append(f"• 用户: {content}")
+        elif role == "assistant" and content and not msg.get("tool_calls"):
+            snippet = content.replace("\n", " ")
+            if len(snippet) > 220:
+                snippet = snippet[:220] + "…"
+            lines.append(f"• 助手: {snippet}")
+        elif role == "tool":
+            name = msg.get("name") or "tool"
+            try:
+                data = json.loads(content)
+                if isinstance(data, dict) and data.get("error"):
+                    lines.append(f"• 工具 {name} 失败: {data.get('error')}")
+                elif isinstance(data, list):
+                    lines.append(f"• 工具 {name} 返回 {len(data)} 条记录")
+                elif isinstance(data, dict):
+                    keys = ", ".join(list(data.keys())[:6])
+                    lines.append(f"• 工具 {name} 已完成 ({keys})")
+                else:
+                    lines.append(f"• 工具 {name} 已执行")
+            except json.JSONDecodeError:
+                lines.append(f"• 工具 {name} 已执行")
+
+    if not lines:
+        return ""
+    summary = "\n".join(lines[-12:])
+    if len(summary) > COMPACT_SUMMARY_MAX_CHARS:
+        summary = summary[: COMPACT_SUMMARY_MAX_CHARS - 1] + "…"
+    return summary
+
+
+def apply_smart_compact(
+    messages: list[dict[str, Any]],
+    budget: int = MAX_CONTEXT_TOKENS,
+    *,
+    aggressive: bool = False,
+) -> tuple[list[dict[str, Any]], CompactStats]:
+    """Compact context for LLM without mutating stored chat history."""
+    stats = CompactStats()
+    if not messages:
+        return messages, stats
+
+    threshold = budget if aggressive else int(budget * COMPACT_THRESHOLD_RATIO)
+    if approx_tokens(messages) <= threshold and not aggressive:
+        return messages, stats
+
+    system_msgs = [m for m in messages if m.get("role") == "system"]
+    rest = [m for m in messages if m.get("role") != "system" and not is_stored_summary_message(m)]
+    stored_summary_msgs = [m for m in messages if is_stored_summary_message(m)]
+
+    boundary = max(0, len(rest) - COMPACT_RECENT_MESSAGES)
+    if boundary <= 0 and not aggressive:
+        trimmed = fit_context_budget(messages, budget)
+        if len(trimmed) < len(messages):
+            stats.compacted = True
+            stats.messages_replaced = len(messages) - len(trimmed)
+        return trimmed, stats
+
+    slimmed_rest: list[dict[str, Any]] = []
+    for idx, msg in enumerate(rest):
+        if msg.get("role") == "tool" and idx < boundary:
+            raw = msg.get("content") or ""
+            new_content = _slim_tool_content(msg.get("name") or "tool", raw, compact=True)
+            if new_content != raw:
+                stats.tool_results_slimmed += 1
+                stats.compacted = True
+            slimmed_rest.append({**msg, "content": new_content})
+        else:
+            slimmed_rest.append(msg)
+
+    combined = system_msgs + stored_summary_msgs + slimmed_rest
+    target = budget if aggressive else int(budget * COMPACT_THRESHOLD_RATIO)
+
+    if approx_tokens(combined) > target or aggressive:
+        older = slimmed_rest[:boundary]
+        recent = slimmed_rest[boundary:]
+        summary = _build_rule_summary(older)
+        if summary and older:
+            slimmed_rest = recent
+            stats.summary_generated = True
+            stats.summary_text = summary
+            stats.messages_replaced = len(older)
+            stats.compacted = True
+            combined = system_msgs + stored_summary_msgs + slimmed_rest
+
+    trimmed = fit_context_budget(combined, budget)
+    if len(trimmed) < len(messages):
+        stats.compacted = True
+
+    return trimmed, stats

couplet_core-0.1.0/src/couplet_core/agent/config.py

@@ -0,0 +1,20 @@
+"""Agent runtime configuration."""
+
+from __future__ import annotations
+
+import os
+
+MAX_TOOL_ROUNDS = int(os.getenv("AGENT_MAX_TOOL_ROUNDS", "12"))
+MAX_CONTEXT_TOKENS = int(os.getenv("AGENT_MAX_CONTEXT_TOKENS", "80000"))
+MAX_TOOL_RESULT_CHARS = int(os.getenv("AGENT_MAX_TOOL_RESULT_CHARS", "8000"))
+TOOL_TIMEOUT_SECONDS = float(os.getenv("AGENT_TOOL_TIMEOUT_SECONDS", "60"))
+LONG_TOOL_HINT_SECONDS = float(os.getenv("AGENT_LONG_TOOL_HINT_SECONDS", "3"))
+DEFAULT_SKILL = os.getenv("DEFAULT_AGENT_SKILL", "baremetal")
+
+# Smart compact (automatic, no user action)
+COMPACT_RECENT_MESSAGES = int(os.getenv("AGENT_COMPACT_RECENT_MESSAGES", "24"))
+COMPACT_THRESHOLD_RATIO = float(os.getenv("AGENT_COMPACT_THRESHOLD_RATIO", "0.65"))
+COMPACTED_TOOL_MAX_CHARS = int(os.getenv("AGENT_COMPACTED_TOOL_MAX_CHARS", "1200"))
+COMPACT_SUMMARY_MAX_CHARS = int(os.getenv("AGENT_COMPACT_SUMMARY_MAX_CHARS", "2500"))
+
+STORED_SUMMARY_PREFIX = "[会话背景摘要]"