spl-agent-engine 0.2.0__tar.gz → 0.4.0__tar.gz

{spl_agent_engine-0.2.0/spl_agent_engine.egg-info → spl_agent_engine-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spl-agent-engine
-Version: 0.2.0
+Version: 0.4.0
 Summary: Anthropomorphic psychology engine built on SPL Pure Core V8.0 — deterministic emotion, trauma, memory, trust, and defense mechanisms.
 Author-email: NOHN-AI <ai@nohnlins.com>
 Maintainer-email: NOHN-AI <ai@nohnlins.com>

{spl_agent_engine-0.2.0 → spl_agent_engine-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "spl-agent-engine"
-version = "0.2.0"
+version = "0.4.0"
 description = "Anthropomorphic psychology engine built on SPL Pure Core V8.0 — deterministic emotion, trauma, memory, trust, and defense mechanisms."
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.8"

{spl_agent_engine-0.2.0 → spl_agent_engine-0.4.0}/spl_agent_engine/__init__.py

@@ -19,10 +19,26 @@ Usage:
     print(core.fluid)
 """
 
-from .core import AuditLogger, SPLPureCoreV7_3, NarrativeMapper
+from .core import (
+    AuditLogger,
+    SPLPureCoreV7_3,
+    NarrativeMapper,
+    TokenUsage,
+    TokenStats,
+    LLMAdapter,
+    OpenAIAdapter,
+    ClaudeAdapter,
+    ChainAdapter,
+    generate_line_with_llm,
+)
 
 # Canonical name for V8.0 (class name kept for backward compatibility)
 SPLPureCore = SPLPureCoreV7_3
 
-__version__ = "0.2.0"
-__all__ = ["SPLPureCore", "SPLPureCoreV7_3", "NarrativeMapper", "AuditLogger"]
+__version__ = "0.4.0"
+__all__ = [
+    "SPLPureCore", "SPLPureCoreV7_3", "NarrativeMapper", "AuditLogger",
+    "TokenUsage", "TokenStats",
+    "LLMAdapter", "OpenAIAdapter", "ClaudeAdapter", "ChainAdapter",
+    "generate_line_with_llm",
+]

{spl_agent_engine-0.2.0 → spl_agent_engine-0.4.0}/spl_agent_engine/core.py

@@ -4,7 +4,7 @@ import json
 import os
 import datetime
 from dataclasses import dataclass, field
-from typing import Dict, Any, List, Optional
+from typing import Dict, Any, List, Optional, Tuple, Union
 
 
 # ================================================================
@@ -75,10 +75,162 @@ class AuditLogger:
                 "memory_count", "expected_count")
         return {k: snap.get(k) for k in keys if k in snap}
 
+    def log_llm_call(self, model: str, prompt_preview: str,
+                     usage: Optional["TokenUsage"] = None,
+                     duration_ms: float = 0.0,
+                     success: bool = True,
+                     error: str = "") -> None:
+        """记录一次 LLM 调用（token 用量、耗时、成功/失败）。
+
+        写入失败静默跳过，绝不阻断引擎核心。
+        """
+        if not self.enabled:
+            return
+        try:
+            entry = {
+                "seq": self._entry_count,
+                "ts": datetime.datetime.now().isoformat(timespec="milliseconds"),
+                "engine": self.ENGINE_VERSION,
+                "session": self.session_id,
+                "event": "llm_call",
+                "model": model,
+                "prompt_preview": prompt_preview[:200],
+                "success": success,
+                "duration_ms": round(duration_ms, 2),
+                "usage": {
+                    "prompt_tokens": usage.prompt_tokens if usage else 0,
+                    "completion_tokens": usage.completion_tokens if usage else 0,
+                    "total_tokens": usage.total_tokens if usage else 0,
+                } if usage else None,
+                "error": error or None,
+            }
+            with open(self.log_file, "a", encoding="utf-8") as f:
+                f.write(json.dumps(entry, ensure_ascii=False, default=str) + "\n")
+            self._entry_count += 1
+        except Exception:
+            pass
+
     def export_path(self) -> Optional[str]:
         return self.log_file if os.path.exists(self.log_file) else None
 
 
+@dataclass
+class TokenUsage:
+    """LLM 调用 token 用量统计。"""
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    total_tokens: int = 0
+    model: str = ""
+
+
+# ================================================================
+# Token 累计统计器 — 跨调用汇总 token 用量
+# ================================================================
+class TokenStats:
+    """跨多次 LLM 调用累计统计 token 用量。
+
+    功能：
+      - 累计 prompt / completion / total tokens
+      - 按模型分别统计
+      - 记录每次调用明细
+      - 导出 JSON 汇总报告
+
+    用法：
+        stats = TokenStats()
+        stats.record(usage)                # 传入 TokenUsage
+        stats.record(usage2)
+        stats.summary()                    # 汇总 dict
+        stats.export_json("stats.json")    # 导出文件
+    """
+
+    def __init__(self):
+        self._total_prompt: int = 0
+        self._total_completion: int = 0
+        self._total_tokens: int = 0
+        self._call_count: int = 0
+        self._by_model: Dict[str, Dict[str, int]] = {}
+        self._history: List[Dict[str, Any]] = []
+
+    def record(self, usage: TokenUsage) -> None:
+        """记录一次 LLM 调用的 token 用量。"""
+        if usage is None:
+            return
+        self._total_prompt += usage.prompt_tokens
+        self._total_completion += usage.completion_tokens
+        self._total_tokens += usage.total_tokens
+        self._call_count += 1
+
+        model = usage.model or "unknown"
+        if model not in self._by_model:
+            self._by_model[model] = {
+                "prompt_tokens": 0,
+                "completion_tokens": 0,
+                "total_tokens": 0,
+                "call_count": 0,
+            }
+        m = self._by_model[model]
+        m["prompt_tokens"] += usage.prompt_tokens
+        m["completion_tokens"] += usage.completion_tokens
+        m["total_tokens"] += usage.total_tokens
+        m["call_count"] += 1
+
+        self._history.append({
+            "seq": self._call_count,
+            "model": model,
+            "prompt_tokens": usage.prompt_tokens,
+            "completion_tokens": usage.completion_tokens,
+            "total_tokens": usage.total_tokens,
+        })
+
+    def summary(self) -> Dict[str, Any]:
+        """返回累计统计汇总。"""
+        return {
+            "call_count": self._call_count,
+            "total_prompt_tokens": self._total_prompt,
+            "total_completion_tokens": self._total_completion,
+            "total_tokens": self._total_tokens,
+            "by_model": dict(self._by_model),
+        }
+
+    def history(self) -> List[Dict[str, Any]]:
+        """返回每次调用的明细记录。"""
+        return list(self._history)
+
+    def reset(self) -> None:
+        """清空所有统计。"""
+        self._total_prompt = 0
+        self._total_completion = 0
+        self._total_tokens = 0
+        self._call_count = 0
+        self._by_model.clear()
+        self._history.clear()
+
+    def export_json(self, path: str) -> None:
+        """将统计汇总 + 明细导出为 JSON 文件。"""
+        data = {
+            "summary": self.summary(),
+            "history": self.history(),
+        }
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(data, f, ensure_ascii=False, indent=2)
+
+    @property
+    def total_tokens(self) -> int:
+        return self._total_tokens
+
+    @property
+    def total_prompt_tokens(self) -> int:
+        return self._total_prompt
+
+    @property
+    def total_completion_tokens(self) -> int:
+        return self._total_completion
+
+    @property
+    def call_count(self) -> int:
+        return self._call_count
+
+
 # ================================================================
 # 1. 外部叙事映射器（"自设：偏见/世界观/价值观"——纯外部策略）
 #    用户可随意替换，无需修改核心代码。
@@ -1309,7 +1461,9 @@ class LLMAdapter(ABC):
                  style_example: str = "",
                  system_prompt: str = "",
                  temperature: float = 0.7,
-                 max_tokens: int = 500) -> Optional[str]:
+                 max_tokens: int = 500,
+                 return_usage: bool = False
+                 ) -> Union[Optional[str], Tuple[Optional[str], Optional["TokenUsage"]]]:
         """
         根据 prompt_injection 生成台词。
 
@@ -1319,9 +1473,11 @@ class LLMAdapter(ABC):
             system_prompt: 可选系统提示词，覆盖默认
             temperature: 采样温度
             max_tokens: 最大生成 token 数
+            return_usage: True 时返回 (台词, TokenUsage) 元组
 
         Returns:
-            生成的台词字符串，失败返回 None
+            return_usage=False: 生成的台词字符串，失败返回 None
+            return_usage=True:  (台词, TokenUsage) 元组
         """
         ...
 
@@ -1350,7 +1506,9 @@ class OpenAIAdapter(LLMAdapter):
                  style_example: str = "",
                  system_prompt: str = "",
                  temperature: float = 0.7,
-                 max_tokens: int = 500) -> Optional[str]:
+                 max_tokens: int = 500,
+                 return_usage: bool = False
+                 ) -> Union[Optional[str], Tuple[Optional[str], Optional[TokenUsage]]]:
         import urllib.request
         import urllib.error
 
@@ -1383,8 +1541,22 @@ class OpenAIAdapter(LLMAdapter):
                 body = json.loads(resp.read().decode("utf-8"))
                 choice = body.get("choices", [{}])[0]
                 content = choice.get("message", {}).get("content", "")
-                return content.strip() if content else None
+                result = content.strip() if content else None
+
+                usage_data = body.get("usage", {}) or {}
+                usage = TokenUsage(
+                    prompt_tokens=usage_data.get("prompt_tokens", 0),
+                    completion_tokens=usage_data.get("completion_tokens", 0),
+                    total_tokens=usage_data.get("total_tokens", 0),
+                    model=body.get("model", self.model),
+                ) if usage_data else None
+
+                if return_usage:
+                    return result, usage
+                return result
         except (urllib.error.URLError, json.JSONDecodeError, KeyError) as e:
+            if return_usage:
+                return None, None
             return None
 
 
@@ -1412,7 +1584,9 @@ class ClaudeAdapter(LLMAdapter):
                  style_example: str = "",
                  system_prompt: str = "",
                  temperature: float = 0.7,
-                 max_tokens: int = 500) -> Optional[str]:
+                 max_tokens: int = 500,
+                 return_usage: bool = False
+                 ) -> Union[Optional[str], Tuple[Optional[str], Optional[TokenUsage]]]:
         import urllib.request
         import urllib.error
 
@@ -1445,8 +1619,24 @@ class ClaudeAdapter(LLMAdapter):
             with urllib.request.urlopen(req, timeout=self.timeout) as resp:
                 body = json.loads(resp.read().decode("utf-8"))
                 content = body.get("content", [{}])[0].get("text", "")
-                return content.strip() if content else None
+                result = content.strip() if content else None
+
+                usage_data = body.get("usage", {}) or {}
+                prompt_tok = usage_data.get("input_tokens", 0)
+                completion_tok = usage_data.get("output_tokens", 0)
+                usage = TokenUsage(
+                    prompt_tokens=prompt_tok,
+                    completion_tokens=completion_tok,
+                    total_tokens=prompt_tok + completion_tok,
+                    model=body.get("model", self.model),
+                ) if usage_data else None
+
+                if return_usage:
+                    return result, usage
+                return result
         except (urllib.error.URLError, json.JSONDecodeError, KeyError) as e:
+            if return_usage:
+                return None, None
             return None
 
 
@@ -1472,24 +1662,45 @@ class ChainAdapter(LLMAdapter):
                  style_example: str = "",
                  system_prompt: str = "",
                  temperature: float = 0.7,
-                 max_tokens: int = 500) -> Optional[str]:
-        result = self.primary.generate(
+                 max_tokens: int = 500,
+                 return_usage: bool = False
+                 ) -> Union[Optional[str], Tuple[Optional[str], Optional[TokenUsage]]]:
+        result, usage = self.primary.generate(
             prompt_injection=prompt_injection,
             style_example=style_example,
             system_prompt=system_prompt,
             temperature=temperature,
             max_tokens=max_tokens,
+            return_usage=True,
         )
         if result is not None:
+            if return_usage:
+                return result, usage
             return result
         if self.fallback is not None:
-            return self.fallback.generate(
+            result2, usage2 = self.fallback.generate(
                 prompt_injection=prompt_injection,
                 style_example=style_example,
                 system_prompt=system_prompt,
                 temperature=temperature,
                 max_tokens=max_tokens,
+                return_usage=True,
             )
+            if return_usage:
+                # 合并两次调用的 token 用量
+                if usage and usage2:
+                    merged = TokenUsage(
+                        prompt_tokens=usage.prompt_tokens + usage2.prompt_tokens,
+                        completion_tokens=usage.completion_tokens + usage2.completion_tokens,
+                        total_tokens=usage.total_tokens + usage2.total_tokens,
+                        model=f"{usage.model}->{usage2.model}",
+                    )
+                else:
+                    merged = usage2 or usage
+                return result2, merged
+            return result2
+        if return_usage:
+            return None, usage
         return None
 
 
@@ -1501,6 +1712,7 @@ def generate_line_with_llm(
     core_snapshot: dict,
     expression,
     adapter: LLMAdapter,
+    audit_logger: Optional["AuditLogger"] = None,
 ) -> str:
     """
     便利函数：引擎渲染风格 → LLM 生成台词 → 失败回退到确定性生成。
@@ -1510,18 +1722,38 @@ def generate_line_with_llm(
         core_snapshot: SPL 核心快照（含 fluid/mood/self_esteem 等）
         expression: 表达意图对象（含 expression_mode / emotion_hidden / silence 等）
         adapter: LLMAdapter 实例
+        audit_logger: 可选 AuditLogger，传入则记录 LLM 调用与 token 用量
 
     Returns:
         台词字符串（LLM 成功=LLM 产出，失败=引擎确定性产出）
     """
+    import time as _time
+
     rendered = engine.render_style(core_snapshot, expression)
     if rendered.silence_hint:
         return rendered.silence_hint
 
-    line = adapter.generate(
+    t0 = _time.perf_counter()
+    line, usage = adapter.generate(
         prompt_injection=rendered.prompt_injection,
         style_example=rendered.style_example,
+        return_usage=True,
     )
+    duration_ms = (_time.perf_counter() - t0) * 1000
+
+    if audit_logger is not None:
+        model = getattr(adapter, "model", "") or (
+            usage.model if usage else ""
+        )
+        audit_logger.log_llm_call(
+            model=model,
+            prompt_preview=rendered.prompt_injection,
+            usage=usage,
+            duration_ms=duration_ms,
+            success=line is not None,
+            error="" if line is not None else "llm_failed",
+        )
+
     if line is not None:
         return line
 

{spl_agent_engine-0.2.0 → spl_agent_engine-0.4.0/spl_agent_engine.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spl-agent-engine
-Version: 0.2.0
+Version: 0.4.0
 Summary: Anthropomorphic psychology engine built on SPL Pure Core V8.0 — deterministic emotion, trauma, memory, trust, and defense mechanisms.
 Author-email: NOHN-AI <ai@nohnlins.com>
 Maintainer-email: NOHN-AI <ai@nohnlins.com>