deepseek-harness 0.2.0__tar.gz

deepseek_harness-0.2.0/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: deepseek-harness
+Version: 0.2.0
+Summary: Protocol-aware client for DeepSeek V4-Pro / V4-Flash. Survives the 16 documented quirks; ships the cache discount.
+Author: Henry Zhang
+License: MIT
+Project-URL: Homepage, https://github.com/HenryZ838978/deepseek-harness
+Project-URL: Reports, https://github.com/HenryZ838978/deepseek-harness/tree/main/reports
+Project-URL: Spec, https://github.com/HenryZ838978/deepseek-harness/tree/main/spec
+Keywords: deepseek,llm,openai,agent,harness,mcp
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: openai>=1.50.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: tiktoken>=0.7.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: ruff>=0.5.0; extra == "dev"
+Provides-Extra: dotenv
+Requires-Dist: python-dotenv>=1.0.0; extra == "dotenv"
+
+# `deepseek-harness`
+
+Protocol-aware Python client for **DeepSeek V4-Pro / V4-Flash**.
+Survives the [16 documented quirks](https://github.com/HenryZ838978/deepseek-harness/blob/main/reports/REPORT_2026-05-09.md); ships the 50× cache discount.
+
+```bash
+pip install deepseek-harness
+```
+
+```python
+from deepseek_harness import DeepSeekHarness
+
+c = DeepSeekHarness(disable_thinking_by_default=True)
+out = c.chat(
+    model="deepseek-v4-pro",
+    messages=[{"role": "user", "content": "Hello"}],
+    max_tokens=4096,
+)
+print(out["message"]["content"])
+print(f"cost: ${out['usage']['estimated_cost_usd']:.6f}  ·  cache hit: {out['usage']['cache_hit_rate']:.0%}")
+```
+
+The harness wraps `openai.OpenAI` and enforces 10 contract rules by default. See the [main repository](https://github.com/HenryZ838978/deepseek-harness) for the full spec, probe corpus, and three other distribution forms (`dsh` CLI, `@deepseek-harness/mcp` server, Anthropic `SKILL.md`).
+
+License: MIT.

deepseek_harness-0.2.0/README.md

@@ -0,0 +1,25 @@
+# `deepseek-harness`
+
+Protocol-aware Python client for **DeepSeek V4-Pro / V4-Flash**.
+Survives the [16 documented quirks](https://github.com/HenryZ838978/deepseek-harness/blob/main/reports/REPORT_2026-05-09.md); ships the 50× cache discount.
+
+```bash
+pip install deepseek-harness
+```
+
+```python
+from deepseek_harness import DeepSeekHarness
+
+c = DeepSeekHarness(disable_thinking_by_default=True)
+out = c.chat(
+    model="deepseek-v4-pro",
+    messages=[{"role": "user", "content": "Hello"}],
+    max_tokens=4096,
+)
+print(out["message"]["content"])
+print(f"cost: ${out['usage']['estimated_cost_usd']:.6f}  ·  cache hit: {out['usage']['cache_hit_rate']:.0%}")
+```
+
+The harness wraps `openai.OpenAI` and enforces 10 contract rules by default. See the [main repository](https://github.com/HenryZ838978/deepseek-harness) for the full spec, probe corpus, and three other distribution forms (`dsh` CLI, `@deepseek-harness/mcp` server, Anthropic `SKILL.md`).
+
+License: MIT.

deepseek_harness-0.2.0/deepseek_harness/__init__.py

@@ -0,0 +1,41 @@
+"""deepseek-harness · core — protocol-aware client for DeepSeek V4-Pro / V4-Flash.
+
+Validated by 16 probes documented in `reports/REPORT_2026-05-09.md`.
+
+Public API::
+
+    from deepseek_harness import DeepSeekHarness, normalize_usage, estimate_cache_hit
+"""
+
+from .client import DeepSeekHarness
+from .cache import estimate_cache_hit, normalize_usage
+from .reasoning import ReasoningLifecycle
+from .tool_calls import salvage_tool_calls_from_content
+from .exceptions import (
+    HarnessError,
+    ReasoningContentMissingError,
+    ToolCallLeakageError,
+    StrictModeCorruptionError,
+    StreamShapeError,
+)
+
+# Backwards-compatible alias (transitional, kept for one minor release).
+DeepSeekClient = DeepSeekHarness
+DeepSeekKitError = HarnessError
+
+__all__ = [
+    "DeepSeekHarness",
+    "DeepSeekClient",
+    "ReasoningLifecycle",
+    "salvage_tool_calls_from_content",
+    "estimate_cache_hit",
+    "normalize_usage",
+    "HarnessError",
+    "DeepSeekKitError",
+    "ReasoningContentMissingError",
+    "ToolCallLeakageError",
+    "StrictModeCorruptionError",
+    "StreamShapeError",
+]
+
+__version__ = "0.2.0"

deepseek_harness-0.2.0/deepseek_harness/cache.py

@@ -0,0 +1,198 @@
+"""Cache-hit field bridging + a local prefix-cache estimator.
+
+Two concrete pains:
+
+1. Field naming mismatch (pi-mono#3880):
+   - DeepSeek puts cache-hit token count in `usage.prompt_cache_hit_tokens`
+   - OpenAI puts it in   `usage.prompt_tokens_details.cached_tokens`
+   - Vanilla OpenAI parsers see 0% cache hit even when DeepSeek is happily charging
+     you the cached price. `normalize_usage()` below back-fills both fields.
+
+2. The DeepSeek cache only triggers on **byte-for-byte prefix match starting from
+   token 0**, with a practical minimum prefix of ~1024 tokens. `estimate_cache_hit()`
+   is a local pre-flight estimator: feed it the messages you are about to send +
+   the prefix you saw "stick" in the previous request, and it tells you the longest
+   common prefix in tokens.
+
+References:
+    deepseek-ai/DeepSeek-V3#1261 (V3.2→V4 cache hit rate regression 92%→35%)
+    pi-mono#3880 (field mismatch fix)
+    DeepSeek docs: https://api-docs.deepseek.com/guides/kv_cache
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+try:
+    import tiktoken
+except ImportError:  # pragma: no cover
+    tiktoken = None
+
+
+# DeepSeek V4-Flash quoted prices, USD per million tokens.
+PRICE_PER_M_INPUT_MISS = 0.14
+PRICE_PER_M_INPUT_HIT = 0.0028
+PRICE_PER_M_OUTPUT = 0.28
+
+
+def normalize_usage(usage: dict | Any) -> dict:
+    """Return a dict that has BOTH field shapes filled in.
+
+    Accepts the raw `usage` dict from a DeepSeek response (or an OpenAI usage object).
+    Output always includes:
+        - prompt_cache_hit_tokens (int)
+        - prompt_cache_miss_tokens (int)
+        - prompt_tokens_details.cached_tokens (int)   # OpenAI shape
+        - completion_tokens, prompt_tokens, total_tokens (passthrough)
+        - estimated_cost_usd (float, V4-Flash pricing)
+    """
+    if usage is None:
+        return {}
+    u = _to_dict(usage)
+
+    prompt_total = int(u.get("prompt_tokens") or 0)
+    completion = int(u.get("completion_tokens") or 0)
+
+    # DeepSeek native field
+    hit = u.get("prompt_cache_hit_tokens")
+    miss = u.get("prompt_cache_miss_tokens")
+
+    # OpenAI shape
+    details = u.get("prompt_tokens_details") or {}
+    if isinstance(details, dict):
+        cached_oa = details.get("cached_tokens")
+    else:
+        cached_oa = getattr(details, "cached_tokens", None)
+
+    if hit is None and cached_oa is not None:
+        hit = int(cached_oa)
+        miss = max(prompt_total - hit, 0)
+    elif hit is not None and cached_oa is None:
+        cached_oa = int(hit)
+    elif hit is None and cached_oa is None:
+        hit, miss, cached_oa = 0, prompt_total, 0
+
+    cost = (
+        (miss / 1_000_000) * PRICE_PER_M_INPUT_MISS
+        + (hit / 1_000_000) * PRICE_PER_M_INPUT_HIT
+        + (completion / 1_000_000) * PRICE_PER_M_OUTPUT
+    )
+
+    return {
+        "prompt_tokens": prompt_total,
+        "completion_tokens": completion,
+        "total_tokens": int(u.get("total_tokens") or (prompt_total + completion)),
+        "prompt_cache_hit_tokens": int(hit),
+        "prompt_cache_miss_tokens": int(miss),
+        "prompt_tokens_details": {"cached_tokens": int(cached_oa)},
+        "estimated_cost_usd": round(cost, 8),
+        "cache_hit_rate": round(hit / prompt_total, 4) if prompt_total else 0.0,
+    }
+
+
+def _to_dict(obj: Any) -> dict:
+    if isinstance(obj, dict):
+        return obj
+    if hasattr(obj, "model_dump"):
+        return obj.model_dump()
+    if hasattr(obj, "to_dict"):
+        return obj.to_dict()
+    if hasattr(obj, "__dict__"):
+        return {k: v for k, v in obj.__dict__.items() if not k.startswith("_")}
+    return {}
+
+
+# ---------------------------------------------------------------------------
+# Pre-flight estimator
+# ---------------------------------------------------------------------------
+
+
+def _encode(text: str) -> list[int]:
+    if tiktoken is None:
+        # crude byte-pair fallback so the kit still imports without tiktoken
+        return list(text.encode("utf-8"))
+    enc = tiktoken.get_encoding("cl100k_base")
+    return enc.encode(text)
+
+
+def estimate_cache_hit(
+    new_messages: list[dict],
+    previous_prefix_messages: list[dict] | None = None,
+    *,
+    minimum_prefix_tokens: int = 1024,
+    cache_block_size: int = 256,
+) -> dict:
+    """Estimate how much of `new_messages` will be a cache hit on DeepSeek.
+
+    DeepSeek's cache rule (validated by probe_5 on 2026-05-09):
+      - prefix-from-0 match
+      - bucketed by ~256-token blocks (cached tokens are always multiples of 256)
+      - minimum prefix length to BEGIN caching ≈ 1024 tokens
+      - tail edits preserve head cache; mid-prefix edits invalidate from the edit
+        point onwards (NOT the entire prefix)
+
+    We serialise both message lists deterministically (role + content + tool_calls
+    + reasoning_content), tokenise with cl100k_base (close enough; DeepSeek
+    tokenizer is ~3.6 chars/token for English ASCII vs cl100k's 4), and find the
+    longest common token prefix, rounded DOWN to the nearest cache_block_size
+    boundary. The estimator does NOT replace the server's truth — it is a
+    pre-flight sanity check, e.g. "is my client about to invalidate the
+    99-cent prefix by re-ordering tool messages?".
+    """
+    new_text = _serialize_messages(new_messages)
+    prev_text = _serialize_messages(previous_prefix_messages or [])
+
+    new_tokens = _encode(new_text)
+    prev_tokens = _encode(prev_text)
+
+    common = 0
+    for a, b in zip(new_tokens, prev_tokens):
+        if a != b:
+            break
+        common += 1
+
+    if common < minimum_prefix_tokens:
+        eligible = 0
+    else:
+        # Server rounds cached tokens DOWN to the nearest cache_block_size (256).
+        eligible = (common // cache_block_size) * cache_block_size
+
+    return {
+        "common_prefix_tokens": common,
+        "eligible_cached_tokens": eligible,
+        "new_total_tokens": len(new_tokens),
+        "estimated_hit_rate": round(eligible / len(new_tokens), 4) if new_tokens else 0.0,
+        "minimum_prefix_threshold": minimum_prefix_tokens,
+        "cache_block_size": cache_block_size,
+        "explanation": (
+            f"common < {minimum_prefix_tokens} → server will NOT cache this request"
+            if common < minimum_prefix_tokens
+            else f"ok — {eligible} tokens (rounded to {cache_block_size}-block) will be discounted at $0.0028/M"
+        ),
+    }
+
+
+def _serialize_messages(messages: list[dict]) -> str:
+    """Deterministic flattening used by both prefix estimator and cache-debug helpers.
+
+    Layout mirrors OpenAI chat-completions JSON ordering: role → content → tool_calls
+    → tool_call_id → reasoning_content. ANY field reorder by your agent code will
+    bust the prefix.
+    """
+    parts: list[str] = []
+    for msg in messages:
+        parts.append(f"<role>{msg.get('role', '')}</role>")
+        content = msg.get("content")
+        if isinstance(content, list):
+            for c in content:
+                parts.append(f"<part>{c}</part>")
+        elif content:
+            parts.append(f"<content>{content}</content>")
+        for tc in msg.get("tool_calls") or []:
+            parts.append(f"<tc>{tc.get('id','')}|{tc.get('function',{}).get('name','')}|{tc.get('function',{}).get('arguments','')}</tc>")
+        if msg.get("tool_call_id"):
+            parts.append(f"<tcid>{msg['tool_call_id']}</tcid>")
+        if msg.get("reasoning_content"):
+            parts.append(f"<rc>{msg['reasoning_content']}</rc>")
+    return "\n".join(parts)

deepseek_harness-0.2.0/deepseek_harness/client.py

@@ -0,0 +1,259 @@
+"""Drop-in OpenAI-compat client for DeepSeek V4-Pro / V4-Flash with all known protocol salvages enabled.
+
+Replace::
+
+    from openai import OpenAI
+    client = OpenAI(api_key=..., base_url="https://api.deepseek.com")
+
+with::
+
+    from deepseek_harness import DeepSeekHarness
+    client = DeepSeekHarness(api_key=..., base_url="https://api.deepseek.com")
+
+The surface is `client.chat.completions.create(...)` — same as OpenAI — but every
+response goes through:
+
+  - `from_deepseek_response`  (preserves reasoning_content on the message dict)
+  - `salvage_tool_calls_from_content`  (rescues 11% leaked tool calls)
+  - `normalize_usage`  (back-fills both cache-hit field shapes + cost estimate)
+
+Streaming uses `stream_chat()` which absorbs reasoning chunks via `ReasoningLifecycle`
+and tolerates the empty-final-chunk shape (cline #1594).
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Iterator
+
+from openai import OpenAI
+
+from .cache import normalize_usage
+from .exceptions import StreamShapeError, ToolCallLeakageError
+from .normalize import from_deepseek_response, strip_kit_warnings, to_deepseek_history
+from .reasoning import ReasoningLifecycle
+from .tool_calls import salvage_tool_calls_from_content
+
+
+class DeepSeekHarness:
+    """Thin wrapper around `openai.OpenAI` with DeepSeek V4-specific safety guards.
+
+    Implements the 10 contract rules documented in `spec/` and validated by the
+    16 probes in `reports/`. See `__init__.py` for the public re-export.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        *,
+        salvage_tool_calls: bool = True,
+        normalize_cache_fields: bool = True,
+        warn_on_missing_reasoning: bool = True,
+        disable_thinking_by_default: bool = False,
+        raw_dump_path: str | None = None,
+    ) -> None:
+        """Construct a DeepSeek-aware OpenAI-compatible client.
+
+        Args:
+            disable_thinking_by_default: If True, every request gets
+              `extra_body={"thinking":{"type":"disabled"}}` UNLESS the caller
+              explicitly passes their own `extra_body`. Recommended for cost-
+              sensitive deployments because `deepseek-v4-pro` defaults to
+              thinking-enabled (probe_0 finding 2026-05-09: ~30 reasoning
+              tokens are billed even on trivial prompts).
+        """
+        self._oai = OpenAI(
+            api_key=api_key or os.getenv("DEEPSEEK_API_KEY"),
+            base_url=base_url or os.getenv("DEEPSEEK_BASE_URL", "https://api.deepseek.com"),
+        )
+        self._salvage = salvage_tool_calls
+        self._normalize_cache = normalize_cache_fields
+        self._warn = warn_on_missing_reasoning
+        self._disable_thinking = disable_thinking_by_default
+        self._raw_dump = raw_dump_path
+
+    def _maybe_inject_thinking_off(self, kwargs: dict) -> dict:
+        if self._disable_thinking and "extra_body" not in kwargs:
+            kwargs = dict(kwargs)
+            kwargs["extra_body"] = {"thinking": {"type": "disabled"}}
+        return kwargs
+
+    # ------------------------------------------------------------------
+    # Non-streaming
+    # ------------------------------------------------------------------
+    def chat(
+        self,
+        *,
+        model: str,
+        messages: list[dict],
+        tools: list[dict] | None = None,
+        tool_choice: str | dict | None = None,
+        **kwargs: Any,
+    ) -> dict:
+        """Returns a dict with keys:
+            message:      OpenAI-shaped assistant message (incl. reasoning_content if any)
+            usage:        normalised usage (both cache-field shapes filled in)
+            finish_reason: passthrough
+            salvage:      None if no tool-call salvage happened, else {pattern, original_content}
+            raw:          the raw SDK response (for debugging)
+        """
+        normalized_in = strip_kit_warnings(to_deepseek_history(messages))
+        kwargs = self._maybe_inject_thinking_off(kwargs)
+        resp = self._oai.chat.completions.create(
+            model=model,
+            messages=normalized_in,
+            tools=tools,
+            tool_choice=tool_choice,
+            **kwargs,
+        )
+
+        msg = from_deepseek_response(resp)
+        finish_reason = msg.pop("_dsk_kit_finish_reason", None)
+        salvage = None
+
+        if self._salvage and not msg.get("tool_calls"):
+            tool_calls, residual, reason = salvage_tool_calls_from_content(
+                msg.get("content"), finish_reason
+            )
+            if tool_calls is not None:
+                salvage = {
+                    "pattern": reason,
+                    "original_content": msg.get("content"),
+                }
+                msg["tool_calls"] = tool_calls
+                msg["content"] = residual
+
+        usage = normalize_usage(getattr(resp, "usage", None)) if self._normalize_cache else None
+
+        return {
+            "message": msg,
+            "usage": usage,
+            "finish_reason": finish_reason,
+            "salvage": salvage,
+            "raw": resp,
+        }
+
+    # ------------------------------------------------------------------
+    # Streaming
+    # ------------------------------------------------------------------
+    def stream_chat(
+        self,
+        *,
+        model: str,
+        messages: list[dict],
+        tools: list[dict] | None = None,
+        tool_choice: str | dict | None = None,
+        **kwargs: Any,
+    ) -> Iterator[dict]:
+        """Yields **structured events** (not raw chunks) so callers don't have to re-implement
+        the cline #1594 / hermes #15353 mitigations.
+
+        Event types:
+          {"type": "content_delta",   "data": str}
+          {"type": "reasoning_delta", "data": str}
+          {"type": "tool_call_delta", "data": {"index": int, "id": str|None, "name": str|None, "arguments": str}}
+          {"type": "done", "message": {...}, "usage": {...}, "finish_reason": str, "salvage": dict|None}
+        """
+        normalized_in = strip_kit_warnings(to_deepseek_history(messages))
+        kwargs = self._maybe_inject_thinking_off(kwargs)
+        stream = self._oai.chat.completions.create(
+            model=model,
+            messages=normalized_in,
+            tools=tools,
+            tool_choice=tool_choice,
+            stream=True,
+            stream_options={"include_usage": True},
+            **kwargs,
+        )
+
+        rl = ReasoningLifecycle()
+        content_buf: list[str] = []
+        tool_call_acc: dict[int, dict] = {}
+        finish_reason: str | None = None
+        usage_raw: Any | None = None
+
+        for chunk in stream:
+            choices = getattr(chunk, "choices", None) or []
+            # DeepSeek emits a final chunk with empty choices but populated usage —
+            # cline #1594 was the upstream bug from indexing into [0] blindly.
+            if not choices:
+                if getattr(chunk, "usage", None) is not None:
+                    usage_raw = chunk.usage
+                continue
+
+            choice = choices[0]
+            delta = getattr(choice, "delta", None)
+            if delta is None:
+                # malformed chunk — neither delta nor finish_reason; skip rather than throw
+                continue
+
+            # reasoning_content goes through the lifecycle helper (also yields out for visibility)
+            rc = getattr(delta, "reasoning_content", None)
+            if rc:
+                rl.absorb_chunk(chunk)
+                yield {"type": "reasoning_delta", "data": rc}
+
+            content_piece = getattr(delta, "content", None)
+            if content_piece:
+                content_buf.append(content_piece)
+                yield {"type": "content_delta", "data": content_piece}
+
+            for tc in getattr(delta, "tool_calls", None) or []:
+                idx = getattr(tc, "index", 0)
+                slot = tool_call_acc.setdefault(
+                    idx, {"id": None, "name": None, "arguments": ""}
+                )
+                if getattr(tc, "id", None):
+                    slot["id"] = tc.id
+                fn = getattr(tc, "function", None)
+                if fn is not None:
+                    if getattr(fn, "name", None):
+                        slot["name"] = fn.name
+                    if getattr(fn, "arguments", None):
+                        slot["arguments"] += fn.arguments
+                yield {
+                    "type": "tool_call_delta",
+                    "data": {
+                        "index": idx,
+                        "id": slot["id"],
+                        "name": slot["name"],
+                        "arguments": slot["arguments"],
+                    },
+                }
+
+            if getattr(choice, "finish_reason", None):
+                finish_reason = choice.finish_reason
+
+        content_str = "".join(content_buf) or None
+        message: dict[str, Any] = {"role": "assistant", "content": content_str}
+        if tool_call_acc:
+            message["tool_calls"] = [
+                {
+                    "id": v["id"] or f"call_{i}",
+                    "type": "function",
+                    "function": {"name": v["name"] or "", "arguments": v["arguments"] or "{}"},
+                }
+                for i, v in sorted(tool_call_acc.items())
+            ]
+        message = rl.finalize_assistant_message(message)
+
+        salvage = None
+        if self._salvage and not message.get("tool_calls"):
+            tool_calls, residual, reason = salvage_tool_calls_from_content(
+                message.get("content"), finish_reason
+            )
+            if tool_calls is not None:
+                salvage = {"pattern": reason, "original_content": message.get("content")}
+                message["tool_calls"] = tool_calls
+                message["content"] = residual
+
+        usage = normalize_usage(usage_raw) if (self._normalize_cache and usage_raw) else None
+
+        yield {
+            "type": "done",
+            "message": message,
+            "usage": usage,
+            "finish_reason": finish_reason,
+            "salvage": salvage,
+        }

deepseek_harness-0.2.0/deepseek_harness/exceptions.py

@@ -0,0 +1,36 @@
+"""Typed errors so callers can branch on the specific quirk that fired."""
+
+
+class HarnessError(Exception):
+    """Base for every protocol-quirk we detect."""
+
+
+class ReasoningContentMissingError(HarnessError):
+    """Server returned 400 because the previous turn's reasoning_content was not echoed back.
+
+    Reference: microsoft/agent-framework#5538, NousResearch/hermes-agent#15353.
+    Probe: reports/probes/probe_2_reasoning_lifecycle.py (3/3 reproduction on V4-Pro).
+    """
+
+
+class ToolCallLeakageError(HarnessError):
+    """finish_reason='stop' but content carried a DSML / JSON tool call payload.
+
+    Reference: deepseek-ai/DeepSeek-V3#1244, NousResearch/hermes-agent#15453.
+    Probe: reports/probes/probe_3_tool_call_leakage.py (0/50 on V4 official endpoint).
+    """
+
+
+class StrictModeCorruptionError(HarnessError):
+    """beta/strict path produced unparseable JSON (missing quote on first key).
+
+    Reference: deepseek-ai/DeepSeek-V3#1069 (closed as not-planned).
+    Probe: reports/probes/probe_4_strict_mode_corruption.py (0/32 on V4 series).
+    """
+
+
+class StreamShapeError(HarnessError):
+    """Final SSE chunk lacked `choices`, or `delta` was undefined where indexed.
+
+    Reference: cline/cline#1594.
+    """