kc-beta 0.7.5 → 0.8.3

package/template/workflows/common/llm_client.py

@@ -0,0 +1,168 @@
+"""KC worker-LLM client (v0.8.1 P10-A canonical shim).
+
+Distilled workflows use this module to call worker LLMs. Provider-agnostic:
+reads connection info from workspace `.env` so the same workflow can run
+against SiliconFlow, OpenAI, Anthropic, Aliyun, Volcanocloud, etc.
+
+Two modes:
+  - Inside a KC session: the engine's `worker_llm_call` tool is preferred
+    for new code (it tracks cost, applies rate limiting, and writes to
+    events.jsonl). This shim is fine if the workflow needs to be
+    portable to standalone (no-KC) deployment.
+  - Standalone (deployed release bundle): this shim is the only LLM
+    access path. Every call writes a line to `output/llm_ledger.jsonl`
+    so post-hoc analysis can reconstruct cost and traffic.
+
+Required `.env` fields:
+  LLM_API_KEY     API key for the provider
+  LLM_BASE_URL    Provider base URL (e.g. https://api.siliconflow.cn/v1)
+  TIER1..TIER4    Comma-separated model names per tier
+
+Optional:
+  LLM_AUTH_TYPE   "bearer" (default) | "x-api-key" (Anthropic native)
+  LLM_API_FORMAT  "openai" (default) — only OpenAI-format chat completions
+                  are supported by this shim. Use worker_llm_call for
+                  non-OpenAI-format providers (e.g. Anthropic native).
+
+If LLM_BASE_URL is missing, the shim raises explicitly — no silent
+fallback to a hardcoded vendor URL. This avoids accidentally sending
+traffic to siliconflow.cn from an OpenAI-configured workspace.
+
+Migration aliases:
+  SILICONFLOW_API_KEY → falls back to LLM_API_KEY if the canonical
+  name is missing (for workspaces predating v0.8.1).
+"""
+import json
+import os
+import time
+import urllib.error
+import urllib.request
+
+_LEDGER_PATH = os.path.join("output", "llm_ledger.jsonl")
+
+
+def call(tier="tier2", prompt="", system_prompt=None, max_tokens=4096, timeout_s=120):
+    """Single-prompt chat-completions call.
+
+    Returns: {response, model_used, tier, tokens_in, tokens_out}.
+    Raises: RuntimeError on missing config; urllib HTTPError on transport.
+    """
+    if not prompt:
+        raise RuntimeError("call() requires a non-empty `prompt`")
+
+    api_key = _env("LLM_API_KEY") or _env("SILICONFLOW_API_KEY")
+    if not api_key:
+        raise RuntimeError(
+            "LLM_API_KEY not configured. Set it in .env or run `kc-beta onboard`."
+        )
+
+    base_url = _env("LLM_BASE_URL") or _env("SILICONFLOW_BASE_URL")
+    if not base_url:
+        raise RuntimeError(
+            "LLM_BASE_URL not configured. Set the canonical name in .env "
+            "(e.g. https://api.openai.com/v1 for OpenAI; "
+            "https://api.siliconflow.cn/v1 for SiliconFlow). "
+            "Run `kc-beta onboard` to configure interactively."
+        )
+    base_url = base_url.rstrip("/")
+
+    auth_type = (_env("LLM_AUTH_TYPE") or "bearer").lower()
+    api_format = (_env("LLM_API_FORMAT") or "openai").lower()
+    if api_format != "openai":
+        raise RuntimeError(
+            f"LLM_API_FORMAT={api_format} not supported by this shim. "
+            f"Only `openai` chat-completions wire format is implemented. "
+            f"Use the engine's `worker_llm_call` tool for native non-OpenAI providers."
+        )
+
+    tier_models = _load_tier_models(tier)
+    if not tier_models:
+        raise RuntimeError(f"No models configured for {tier.upper()}; check .env TIER1-TIER4")
+
+    messages = []
+    if system_prompt:
+        messages.append({"role": "system", "content": system_prompt})
+    messages.append({"role": "user", "content": prompt})
+
+    body = json.dumps(
+        {"model": tier_models[0], "messages": messages, "max_tokens": max_tokens}
+    ).encode("utf-8")
+
+    headers = {"Content-Type": "application/json"}
+    if auth_type == "x-api-key":
+        headers["x-api-key"] = api_key
+        headers["anthropic-version"] = "2023-06-01"
+    else:
+        headers["Authorization"] = f"Bearer {api_key}"
+
+    req = urllib.request.Request(f"{base_url}/chat/completions", data=body, headers=headers)
+    t0 = time.time()
+    try:
+        with urllib.request.urlopen(req, timeout=timeout_s) as resp:
+            data = json.loads(resp.read())
+    except urllib.error.HTTPError as e:
+        # Preserve the body for debugging — providers often return useful errors
+        err_body = e.read().decode("utf-8", errors="replace")[:500] if e.fp else ""
+        raise RuntimeError(f"LLM call HTTP {e.code} from {base_url}: {err_body}") from e
+
+    usage = data.get("usage") or {}
+    result = {
+        "response": data["choices"][0]["message"]["content"],
+        "model_used": tier_models[0],
+        "tier": tier,
+        "tokens_in": usage.get("prompt_tokens", 0),
+        "tokens_out": usage.get("completion_tokens", 0),
+    }
+    _write_ledger({
+        **result,
+        "duration_s": round(time.time() - t0, 3),
+        "ts": time.time(),
+        "base_url": base_url,
+        "auth_type": auth_type,
+    })
+    return result
+
+
+def _env(key):
+    """Read `key` from process env first, then workspace .env file."""
+    v = os.environ.get(key)
+    if v:
+        return v
+    if os.path.exists(".env"):
+        try:
+            with open(".env", "r", encoding="utf-8") as f:
+                for raw in f:
+                    line = raw.strip()
+                    if not line or line.startswith("#"):
+                        continue
+                    if "=" not in line:
+                        continue
+                    k, val = line.split("=", 1)
+                    if k.strip() == key:
+                        val = val.strip()
+                        if (val.startswith('"') and val.endswith('"')) or (
+                            val.startswith("'") and val.endswith("'")
+                        ):
+                            val = val[1:-1]
+                        return val
+        except OSError:
+            return None
+    return None
+
+
+def _load_tier_models(tier):
+    raw = _env(tier.upper()) or ""
+    return [m.strip() for m in raw.split(",") if m.strip()]
+
+
+def _write_ledger(record):
+    try:
+        os.makedirs(os.path.dirname(_LEDGER_PATH), exist_ok=True)
+        with open(_LEDGER_PATH, "a", encoding="utf-8") as f:
+            f.write(json.dumps(record, ensure_ascii=False) + "\n")
+    except OSError:
+        # Ledger is best-effort; never break the workflow over a write failure.
+        pass
+
+
+__all__ = ["call"]

package/template/workflows/common/utils.py

@@ -0,0 +1,132 @@
+"""KC workflow helpers (v0.8.1 P10-B).
+
+Common utilities for distilled workflows. Provider-agnostic, no
+external dependencies. Reusable across rule check.py / workflow.py
+files so that per-rule scripts stay focused on rule-specific logic.
+
+Currently:
+  strip_annotations(text)     — drop reviewer-annotation footers
+                                from sample documents so per-rule
+                                check.py regex doesn't false-positive
+                                on the annotation itself
+
+  detect_report_type(text)    — light-touch report-type classifier
+                                (年报 / 季报 / 月报 / 周报 / 其他)
+                                used by rules that gate on report type
+
+  make_result(rule_id, verdict, evidence, confidence, **kwargs)
+                              — standardized result dict factory
+"""
+import re
+
+
+# Annotation prefixes that mark reviewer-added footers in sample docs.
+# These should be stripped before keyword/regex matching so per-rule
+# check.py doesn't match the annotation as if it were document content.
+#
+# Added based on E2E #11 贷款 v0.8 audit § 9: 4/14 spot-checks
+# false-positive PASS because samples contain `预期命中点: ...年化利率`
+# footers that the rule's keyword regex matches.
+_ANNOTATION_PREFIXES = (
+    "预期命中点",
+    "预期结果",
+    "预期判定",
+    "预期验证",
+    "标注",
+    "审核标注",
+    "Expected",
+    "expected",
+    "EXPECTED",
+    "Annotation",
+    "annotation",
+)
+
+
+def strip_annotations(text, extra_prefixes=None):
+    """Remove reviewer-annotation footers from document text.
+
+    A line is dropped if it starts with one of the recognized
+    annotation prefixes followed by `:` or `：` (Chinese full-width
+    colon). All subsequent lines until a blank line or end of text
+    are also dropped (annotations are typically multi-line trailing
+    blocks).
+
+    Pass `extra_prefixes` (iterable of strings) to add project-specific
+    annotation labels.
+
+    Returns the cleaned text. Input is never mutated.
+    """
+    if not text:
+        return text
+    prefixes = tuple(_ANNOTATION_PREFIXES)
+    if extra_prefixes:
+        prefixes = prefixes + tuple(extra_prefixes)
+    # Build a pattern matching `<prefix>` + colon (half or full-width)
+    pattern = "|".join(re.escape(p) for p in prefixes)
+    anno_start = re.compile(rf"^\s*(?:{pattern})\s*[::]")
+
+    out_lines = []
+    in_anno_block = False
+    for line in text.split("\n"):
+        if anno_start.match(line):
+            in_anno_block = True
+            continue
+        if in_anno_block:
+            # End block on a blank line OR a line that doesn't look
+            # like annotation continuation (no leading whitespace).
+            if not line.strip() or not line.startswith((" ", "\t", "-", "*", "·")):
+                in_anno_block = False
+                if line.strip():
+                    out_lines.append(line)
+            # Otherwise still inside the annotation block — drop.
+            continue
+        out_lines.append(line)
+    return "\n".join(out_lines)
+
+
+_REPORT_TYPE_PATTERNS = [
+    ("年报", re.compile(r"年报|年度报告|annual report", re.IGNORECASE)),
+    ("半年报", re.compile(r"半年报|半年度报告|interim report", re.IGNORECASE)),
+    ("季报", re.compile(r"季报|季度报告|quarterly report", re.IGNORECASE)),
+    ("月报", re.compile(r"月报|月度报告|monthly report", re.IGNORECASE)),
+    ("周报", re.compile(r"周报|周度报告|weekly report", re.IGNORECASE)),
+]
+
+
+def detect_report_type(text):
+    """Light-touch report-type classifier.
+
+    Returns one of: "年报", "半年报", "季报", "月报", "周报", "其他".
+    Scans only the first 2000 chars (report-type identifiers usually
+    appear in the title or cover page). Used by rules that gate on
+    report type (e.g. R02-06/R02-08 are NOT_APPLICABLE for 季报).
+    """
+    if not text:
+        return "其他"
+    head = text[:2000]
+    for kind, pattern in _REPORT_TYPE_PATTERNS:
+        if pattern.search(head):
+            return kind
+    return "其他"
+
+
+def make_result(rule_id, verdict, evidence, confidence=0.7, **kwargs):
+    """Build a standardized check result dict.
+
+    Required: rule_id, verdict ("PASS" / "FAIL" / "WARNING" / "NOT_APPLICABLE"),
+    evidence (string explaining the verdict).
+
+    Optional: confidence (0.0-1.0), plus any extra fields the rule
+    needs (model_used, llm_calls, llm_tokens, comment, etc.).
+    """
+    result = {
+        "rule_id": rule_id,
+        "verdict": verdict,
+        "evidence": evidence,
+        "confidence": confidence,
+    }
+    result.update(kwargs)
+    return result
+
+
+__all__ = ["strip_annotations", "detect_report_type", "make_result"]