reasonkit 0.2.0__py3-none-any.whl

reasonkit/__init__.py

@@ -0,0 +1,20 @@
+from .core import enhance, EnhanceResult, LLMCallable, AsyncLLMCallable, StreamingLLMCallable
+from .compare import compare, Comparison
+from .trace import Trace
+from .errors import ReasonKitError, ConfigurationError, ModelCallError
+
+__all__ = [
+    "enhance",
+    "EnhanceResult",
+    "compare",
+    "Comparison",
+    "Trace",
+    "ReasonKitError",
+    "ConfigurationError",
+    "ModelCallError",
+    "LLMCallable",
+    "AsyncLLMCallable",
+    "StreamingLLMCallable",
+]
+
+__version__ = "0.2.0"

reasonkit/__main__.py

@@ -0,0 +1,6 @@
+"""Allow python -m reasonkit."""
+
+from . import __version__
+
+if __name__ == "__main__":
+    print(f"reasonkit {__version__}")

reasonkit/_sanitize.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+import re
+
+
+# --------------------------------------------------------------------------- #
+# Preamble patterns -- meta-preambles small models prepend despite the prompt
+# telling them not to.
+# --------------------------------------------------------------------------- #
+
+_PREAMBLE_RE = re.compile(
+    r"^\s*(?:"
+    r"here(?:'s| is)|below is|this is|"
+    r"i'?ve\s+(?:revised|improved|updated|corrected|rewritten|reworked)|"
+    r"after\s+(?:considering|reviewing|reading|analyzing)|"
+    r"based\s+on\s+(?:the\s+)?(?:critique|above|draft|issues|feedback)|"
+    r"here'?s\s+my\s+(?:revised|improved|refined|better|updated)"
+    r")\b[^\n:]{0,80}:\s*",
+    re.IGNORECASE,
+)
+
+
+# --------------------------------------------------------------------------- #
+# Scaffold labels from _goal_and_assumptions that leak into the final answer.
+# --------------------------------------------------------------------------- #
+
+_SCAFFOLD_LINE_RE = re.compile(
+    r"^\s*(?:the user's actual message|assumptions to revisit|"
+    r"open clarifying questions?|draft reply(?: \+ critique)?|"
+    r"goal / things to keep in mind)\s*:.*$",
+    re.IGNORECASE,
+)
+
+
+# --------------------------------------------------------------------------- #
+# Post-answer meta-commentary: after the actual answer, some models continue
+# with reasoning about their own writing process ("We need to...", "We must...",
+# "Let's produce..."). These phrases would never be in a real answer (they
+# address the writer, not the user), so we can safely strip everything from the
+# first such marker onwards.
+# --------------------------------------------------------------------------- #
+
+# "we (need to|must|should|can|can now) [not] <action verb>"
+# Handles "we should not claim", "we can provide", "we can say", etc.
+_META_WE_ACTION_RE = re.compile(
+    r"\n{2,}we\s+(?:need\s+to|must|should|can(?:\s+now)?)\s+"
+    r"(?:not\s+)?(?:produce|create|write|generate|output|"
+    r"craft|do|make|put|try|go\s+ahead|wrap|start|give|summarize|"
+    r"fix|repair|correct|revise|rewrite|rework|begin|improve|keep|"
+    r"add|include|ask|ensure|mention|consider|note|be|talk|"
+    r"say|provide|claim)\b.*",
+    re.IGNORECASE | re.DOTALL,
+)
+
+# "we must preserve|keep|maintain|..." -- a different class of instruction
+_META_WE_MUST_RE = re.compile(
+    r"\n{2,}we\s+must\s+(?:preserve|keep|maintain|include|add|use|follow|adhere|"
+    r"comply|obey|respect|retain|not|avoid|never)\b.*",
+    re.IGNORECASE | re.DOTALL,
+)
+
+# "let's <action verb>" (with optional interjection prefix like "ok. let's")
+_META_LET_RE = re.compile(
+    r"\n{2,}(?:ok[a-z]*[.!?]+\s+)?let['´`]?s\s+(?:produce|output|write|craft|do|make|put|try|"
+    r"go\s+ahead|wrap|start|give|summarize|begin|get|work|fix|create|"
+    r"repair|correct|revise|rewrite|rework|answer)\b.*",
+    re.IGNORECASE | re.DOTALL,
+)
+
+# "i/we (will|shall|'ll) [not|also|...] <action verb>"
+_META_PERSONAL_WILL_RE = re.compile(
+    r"\n{2,}(?:i|we)(?:['´`]?\s+(?:will|shall)|['´`]ll)\s+"
+    r"(?:\w+\s+)*?(?:"
+    r"output|produce|write|provide|give|craft|fix|revise|rewrite|"
+    r"present|offer|explain|keep|mention|make|comply|answer|try|do|"
+    r"add|include|ensure|note|consider|ask"
+    r")\b.*",
+    re.IGNORECASE | re.DOTALL,
+)
+
+# "however|but,? the instruction|the prompt|the rules|..."
+_META_INSTRUCTION_RE = re.compile(
+    r"\n{2,}(?:however|but)\s*,?\s*(?:the instruction|the prompt|the rules|"
+    r"the guidelines|our task|i(?:'m|\s+am)\s+(?:supposed|asked|told|instructed)"
+    r"|as\s+(?:an?\s+)?(?:AI|language\s+model|assistant)).*",
+    re.IGNORECASE | re.DOTALL,
+)
+
+# Revision / process notes: "i've revised...", "after considering...", etc.
+_META_REVISION_RE = re.compile(
+    r"\n{2,}"
+    r"(?:"
+    r"i'?ve\s+(?:revised|improved|updated|corrected|rewritten|reworked)\s+"
+    r"(?:the|this|it|above|answer|draft)"
+    r"|after\s+(?:considering|reviewing|reading)\s+(?:the\s+)?"
+    r"(?:critique|above|draft|issues|feedback|analysis)"
+    r"|here'?s\s+my\s+(?:revised|improved|refined|better|updated|answer)"
+    r"|the\s+(?:user|prompt|request|question)\s+(?:asks|wants|says|needs|requests)\s+(?:(?:me\s+)?to\b)?"
+    r"|User\s+wants\s+(?:a|an|the|to|me)\b"
+    r"|User's\s+(?:request|question|prompt)\s+"
+    r"|(?:now|so)\s+(?:let\s+me|i['´`]?ll)\s+(?:provide|give|present|offer|"
+    r"produce|write|craft|explain)"
+    r"|i['´`]?ll\s+(?:provide|give|present|offer|produce|write|craft|explain|revise)"
+    r"|my\s+(?:revised|improved|refined|final)\s+(?:answer|draft|version)"
+    r").*",
+    re.IGNORECASE | re.DOTALL,
+)
+
+# All post-answer meta patterns, applied in order.
+_POST_ANSWER_PATTERNS = (
+    _META_WE_ACTION_RE,
+    _META_WE_MUST_RE,
+    _META_LET_RE,
+    _META_INSTRUCTION_RE,
+    _META_REVISION_RE,
+    _META_PERSONAL_WILL_RE,
+)
+
+
+# --------------------------------------------------------------------------- #
+# Public helpers
+# --------------------------------------------------------------------------- #
+
+def strip_preamble(text: str) -> str:
+    """Strip leading meta-preambles like 'Here is my revised answer:'."""
+    if not text:
+        return text
+    return _PREAMBLE_RE.sub("", text, count=1)
+
+
+def strip_scaffold_lines(text: str) -> str:
+    """Strip lines that look like internal pipeline context labels (Goal:,
+    Assumptions to revisit:, etc.)."""
+    if not text:
+        return text
+    kept = [ln for ln in text.splitlines() if not _SCAFFOLD_LINE_RE.match(ln)]
+    return "\n".join(kept).strip()
+
+
+def strip_post_answer_meta(text: str) -> str:
+    """Strip post-answer meta-commentary about the writing process.
+
+    Applies all known meta-commentary patterns in order and returns the
+    clean text. Each pattern strips from its match to the end of the string,
+    so the first hit removes everything after it.
+    """
+    if not text:
+        return text
+    for pattern in _POST_ANSWER_PATTERNS:
+        text = pattern.sub("", text)
+    return text.strip()
+
+
+def sanitize_final(text: str) -> str:
+    """Full sanitization: preambles, scaffold lines, and post-answer meta.
+
+    This is the main entry point for final-answer sanitization. Strips:
+    1. Leading meta-preambles ("Here is my revised answer:")
+    2. Internal scaffold labels ("Goal:", "Assumptions to revisit:")
+    3. Post-answer commentary ("We need to fix...", "Let's rewrite...")
+    """
+    if not text:
+        return text
+    text = strip_preamble(text)
+    text = strip_scaffold_lines(text)
+    text = strip_post_answer_meta(text)
+    return text.strip()

reasonkit/_utils.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+import re
+
+
+# --------------------------------------------------------------------------- #
+# Code-detection helpers (extracted from codegen.py to break circular imports)
+# --------------------------------------------------------------------------- #
+
+def _line_looks_code(line: str) -> bool:
+    """Heuristic: does a single line look like source code?"""
+    low = line.strip().lower()
+    if not low:
+        return False
+    starters = (
+        "def ", "class ", "if ", "for ", "while ", "try:", "except", "return ",
+        "import ", "from ", "#include", "public ", "private ", "fn ", "let ",
+        "const ", "var ", "function ", "package ", "interface ", "struct ",
+    )
+    if any(low.startswith(s) for s in starters):
+        return True
+    return any(ch in line for ch in ("{", "}", "(", ")", "=>", "::", ";", "[", "]"))
+
+
+def _looks_like_code(text: str) -> bool:
+    """Heuristic: is this source code, or prose the classifier dumped into
+    CODE_INPUT? A "the user did not provide code" sentence must not be treated
+    as code to verify/fix -- that's what makes the pipeline hallucinate."""
+    if not text:
+        return False
+    if "```" in text or text.lstrip().startswith("#!"):
+        return True
+    low = text.lower()
+    seen = sum(
+        1
+        for kw in (
+            "def ", "class ", "func ", "function ", "public ", "private ",
+            "void ", "int ", "return ", "import ", "include", "package ",
+            "fn ", "let ", "var ", "const ", "struct ", "end", "begin",
+        )
+        if kw in low
+    )
+    prose_markers = sum(
+        1 for m in ("note:", "since the user", "please provide", "it's essential")
+        if m in low
+    )
+    # Need >= 2 code-ish keywords and no prose markers, so a plain sentence isn't
+    # misread as code but short snippets (def add(a,b): return a+b) still pass.
+    return seen >= 2 and prose_markers == 0
+
+
+# --------------------------------------------------------------------------- #
+# Heuristic scoring helpers (extracted from merge.py)
+# --------------------------------------------------------------------------- #
+
+def _specificity(text: str) -> float:
+    """Cheap proxy for how concrete an answer is: length + developed points +
+    a bottom-line marker. Used only to catch clear merge regressions, not to
+    judge quality in general."""
+    if not text:
+        return 0.0
+    low = text.lower()
+    sentences = text.count(".") + text.count("!") + text.count("?")
+    bottom_line = 1.0 if any(
+        k in low for k in ("bottom line", "recommend", "in short", "overall,")
+    ) else 0.0
+    return float(len(text)) + sentences * 8.0 + bottom_line * 40.0
+
+
+# Markers a well-organized answer carries (headings, bullets, ordinals, bold).
+# A merge that collapses a 40-section draft into 4 items has lost structure even
+# if still "long enough"; _structure_score catches that where length alone won't.
+_STRUCTURE_RE = re.compile(
+    r"^\s*(?:"
+    r"#{1,6}\s+"
+    r"|[-*]\s+\S"
+    r"|\d+[.)]\s+\S"
+    r"|\*\*[^*]+\*\*"
+    r"|(?i:first|second|third|fourth|fifth|next|then|finally|lastly)\b[,:.\s]"
+    r")",
+    re.MULTILINE,
+)
+
+
+def _structure_score(text: str) -> float:
+    """Count of structural markers per line. 0 for a flat prose blob."""
+    if not text:
+        return 0.0
+    return float(len(_STRUCTURE_RE.findall(text)))
+
+
+# Flag only clear regressions: merged below 0.5x on either axis, or below 0.7x
+# on both at once. A merge that tightens a few sentences but keeps structure
+# stays strictly better and is not flagged.
+def _regressed(merged: str, best: str) -> bool:
+    if not merged:
+        return True
+    spec_ratio = _specificity(merged) / max(_specificity(best), 1.0)
+    struct_ratio = _structure_score(merged) / max(_structure_score(best), 1.0)
+    if spec_ratio < 0.5 or struct_ratio < 0.5:
+        return True
+    if spec_ratio < 0.7 and struct_ratio < 0.7:
+        return True
+    return False

reasonkit/branching.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from ._sanitize import strip_post_answer_meta
+from .trace import Trace
+
+_PROMPT_PATH = Path(__file__).parent / "prompts" / "generate_approaches.txt"
+
+
+def _load_prompt() -> str:
+    return _PROMPT_PATH.read_text(encoding="utf-8")
+
+
+def build_generate_prompt(
+    goal_and_assumptions: str,
+    n: int,
+    previous_issues: list[str] | None = None,
+) -> str:
+    if n > 1:
+        instruction = (
+            f"Generate {n} GENUINELY DISTINCT approaches to address it -- real "
+            "alternative strategies, not rephrasings of each other. Each must "
+            "take a different angle (e.g. different audience, different risk "
+            "posture, different first move)."
+        )
+        fmt = (
+            "Label each approach exactly 'APPROACH 1:', 'APPROACH 2:', etc., in "
+            "order, with a blank line between them. Do not wrap them in extra "
+            "sections or a summary."
+        )
+        # Feed previous-cycle critique back into generation so new approaches
+        # avoid known flaws.
+        if previous_issues:
+            bullets = "\n".join(f"- {iss}" for iss in previous_issues[:8])
+            instruction += (
+                "\n\n**Avoid previous mistakes.** The previous cycle's approaches "
+                "had these issues. Your NEW approaches must NOT repeat them:\n"
+                f"{bullets}"
+            )
+    else:
+        instruction = (
+            "Write ONE direct, human reply to that message in plain language "
+            "(the way a knowledgeable friend would answer)."
+        )
+        fmt = "Write the reply as a single continuous answer. No 'APPROACH' labels."
+    return _load_prompt().format(
+        goal_and_assumptions=goal_and_assumptions,
+        n_instruction=instruction,
+        n_format=fmt,
+    )
+
+
+def _split_approaches(raw: str) -> list[str]:
+    # Split the numbered output into distinct approach blocks.
+    parts = re.split(r"(?im)^\s*APPROACH\s*\d+\s*[:.)-]?\s*", raw)
+    approaches = [p.strip() for p in parts[1:] if p.strip()]
+    if not approaches:
+        return [raw.strip()] if raw.strip() else []  # no markers: one approach
+    # Strip meta-commentary that leaks into any approach.
+    return [strip_post_answer_meta(a) for a in approaches]
+
+
+async def generate_approaches(
+    fn,
+    goal_and_assumptions: str,
+    n: int,
+    trace: Trace,
+    previous_issues: list[str] | None = None,
+) -> list[str]:
+    rendered = build_generate_prompt(goal_and_assumptions, n, previous_issues=previous_issues)
+    raw = await fn(rendered)
+    trace.add_call("generate", rendered, raw)
+    return _split_approaches(raw)

reasonkit/classifier.py

@@ -0,0 +1,200 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from .trace import Trace
+
+_PROMPT_PATH = Path(__file__).parent / "prompts" / "classify_and_assumptions.txt"
+
+
+def _load_prompt() -> str:
+    return _PROMPT_PATH.read_text(encoding="utf-8")
+
+
+def build_classify_prompt(prompt: str) -> str:
+    return _load_prompt().format(prompt=prompt)
+
+
+# Structured-output field headers the classify prompt asks for. DIRECT_ANSWER is
+# intentionally absent -- the classifier routes only.
+_FIELD_NAMES = (
+    "CATEGORY",
+    "COMPLEXITY",
+    "NEEDS_CLARIFICATION",
+    "GOAL",
+    "ASSUMPTIONS",
+    "CLARIFYING_QUESTIONS",
+    "CODE_INPUT",
+)
+
+
+def _read_field(text: str, field_name: str) -> str:
+    # Extract FIELD_NAME: up to the next known field header. '' if absent.
+    import re
+
+    others = [f for f in _FIELD_NAMES if f != field_name]
+    stop = r"|".join(re.escape(o) for o in others)
+    pattern = (
+        rf"^\s*{re.escape(field_name)}\s*:\s*(.*?)"
+        rf"(?=^\s*(?:{stop})\s*:|\Z)"
+    )
+    m = re.search(pattern, text, re.IGNORECASE | re.MULTILINE | re.DOTALL)
+    return m.group(1).strip() if m else ""
+
+
+def _normalize_category(value: str) -> str:
+    v = value.strip().upper()
+    if v in ("DECISION", "CODE", "DIRECT"):
+        return v
+    if "CODE" in v:
+        return "CODE"
+    if "DECIS" in v:
+        return "DECISION"
+    return "DIRECT"  # safest fallback
+
+
+def _normalize_complexity(value: str) -> str:
+    return "COMPLEX" if "COMPLEX" in value.upper() else "SIMPLE"
+
+
+def _normalize_needs_clarification(value: str) -> bool:
+    v = value.strip().upper()
+    if v.startswith("Y"):
+        return True
+    if v.startswith("N"):
+        return False
+    return "YES" in v and "NO" not in v  # tolerate free text
+
+
+def _try_parse_json(text: str) -> dict | None:
+    # Try to parse text as JSON. Handles ```json fences and bare objects.
+    import json
+    import re
+
+    t = text.strip()
+
+    # Strip ```json ... ``` fences if present.
+    m = re.search(r"```(?:json)?\s*\n?([\s\S]*?)```", t)
+    if m:
+        t = m.group(1).strip()
+
+    # Strip outer code fences without language tag.
+    m = re.search(r"```\s*\n?([\s\S]*?)```", t)
+    if m:
+        t = m.group(1).strip()
+
+    try:
+        obj = json.loads(t)
+        if isinstance(obj, dict):
+            return obj
+    except json.JSONDecodeError:
+        pass
+
+    # Also try to find a top-level JSON object anywhere in the text (some models
+    # wrap JSON in prose).
+    m = re.search(r"\{[\s\S]*\}", t)
+    if m:
+        try:
+            obj = json.loads(m.group(0))
+            if isinstance(obj, dict):
+                return obj
+        except json.JSONDecodeError:
+            pass
+
+    return None
+
+
+def parse_classification(raw: str) -> dict:
+    # Parse structured classify output into a dict.
+    # 
+    # Handles BOTH formats models actually output:
+    #   1. Field-per-line  (CATEGORY: DECISION\\nGOAL: ...)
+    #   2. JSON             ({"CATEGORY": "DECISION", "goal": "..."})
+    # The classify prompt asks for format 1, but many models (codestral, deepseek)
+    # emit JSON, sometimes inside a ```json code block. JSON keys can be uppercase
+    # (CATEGORY) or lowercase (category); we accept both.
+    import re
+
+    # Try JSON parsing first (handles ```json blocks, bare JSON, prose-wrapped).
+    json_obj = _try_parse_json(raw)
+
+    if json_obj is not None:
+        # Normalise: accept both "CATEGORY" and "category" as keys.
+        def _jget(*keys: str) -> str:
+            for k in keys:
+                v = json_obj.get(k)
+                if v is not None and v != "":
+                    return str(v).strip()
+            return ""
+
+        def _jget_list(*keys: str) -> list[str]:
+            for k in keys:
+                v = json_obj.get(k)
+                if isinstance(v, list):
+                    return [str(x).strip() for x in v if x]
+            return []
+
+        category = _normalize_category(_jget("CATEGORY", "category"))
+        complexity = _normalize_complexity(_jget("COMPLEXITY", "complexity"))
+        needs_clar = _jget("NEEDS_CLARIFICATION", "needs_clarification")
+        assumptions = _jget_list("ASSUMPTIONS", "assumptions")
+        clarifying = _jget_list("CLARIFYING_QUESTIONS", "clarifying_questions")
+        goal = _jget("GOAL", "goal")
+        code_input = _jget("CODE_INPUT", "code_input")
+
+        if not code_input:
+            code_input = _read_field(raw, "CODE_INPUT")  # fallback: regex
+
+        return {
+            "category": category,
+            "complexity": complexity,
+            "needs_clarification": _normalize_needs_clarification(needs_clar),
+            "goal": goal,
+            "assumptions": assumptions if assumptions else _split_list(_read_field(raw, "ASSUMPTIONS")),
+            "clarifying_questions": clarifying if clarifying else _split_list(_read_field(raw, "CLARIFYING_QUESTIONS")),
+            "code_input": code_input,
+        }
+
+    # Fall back to line-based field parsing (format 1 in the prompt).
+    category = _normalize_category(_read_field(raw, "CATEGORY"))
+    complexity = _normalize_complexity(_read_field(raw, "COMPLEXITY"))
+    assumptions = _split_list(_read_field(raw, "ASSUMPTIONS"))
+    clarifying = _split_list(_read_field(raw, "CLARIFYING_QUESTIONS"))
+    code_input = _read_field(raw, "CODE_INPUT")
+
+    return {
+        "category": category,
+        "complexity": complexity,
+        "needs_clarification": _normalize_needs_clarification(
+            _read_field(raw, "NEEDS_CLARIFICATION")
+        ),
+        "goal": _read_field(raw, "GOAL"),
+        "assumptions": assumptions,
+        "clarifying_questions": clarifying,
+        "code_input": code_input,
+    }
+
+
+def _split_list(value: str) -> list[str]:
+    # Split a free-form field into list items on newlines or ';' or '-' bullets.
+    if not value:
+        return []
+    items = []
+    for part in value.replace(";", "\n").split("\n"):
+        part = part.strip().lstrip("-").strip()
+        part = part.lstrip("0123456789").lstrip(".)").strip()
+        if part:
+            items.append(part)
+    return items
+
+
+async def classify(fn, prompt: str, trace: Trace) -> dict:
+    rendered = build_classify_prompt(prompt)
+    raw = await fn(rendered)
+    trace.add_call("classify", rendered, raw)
+    result = parse_classification(raw)
+    trace.classification = result
+    trace.mode = result["category"].lower()
+    if result["category"] not in ("DECISION", "CODE", "DIRECT"):
+        trace.notes.append("classify: unrecognized category, fell back to DIRECT")
+    return result