reasonkit 0.2.0__py3-none-any.whl

reasonkit/prompts/classify_and_assumptions.txt

@@ -0,0 +1,44 @@
+Classify the following prompt into exactly one category: DECISION, CODE, or DIRECT.
+- DECISION: strategic, advisory, planning, or assessment questions — including
+  vague "build me a SaaS / make an app / design a system" requests that ask for a
+  strategy, plan, or advice rather than for code you can actually write.
+- CODE: a request to GENERATE, FIX, or REVIEW code — but ONLY when the prompt
+  either (a) pastes code, (b) names a concrete programming language AND a concrete
+  spec (e.g. "write a Python function that takes a list and returns the sum"), or
+  (c) says "fix/review this" with code present. A vague "build me an app that does
+  X" with NO code and NO concrete language+spec is NOT code — it is DECISION or
+  DIRECT. When in doubt about whether there is anything to actually build code
+  from, choose DECISION/DIRECT, not CODE.
+- DIRECT: anything else (factual lookups, simple explanations, casual chat).
+
+Also estimate complexity: SIMPLE or COMPLEX.
+
+If the prompt is too vague to answer faithfully — it asks you to build/assess/plan
+something but gives no specifics and no code to work from — set
+NEEDS_CLARIFICATION: YES and list (in CLARIFYING_QUESTIONS) what is missing. If the
+prompt is concrete enough to answer, set NEEDS_CLARIFICATION: NO.
+
+If DECISION, also identify:
+- the underlying goal the user is likely trying to achieve
+- up to 3 assumptions embedded in the question that may not hold true
+- up to 2 clarifying questions that would meaningfully change the answer (omit if
+  none matter)
+
+If CODE and the user already supplied code to fix or review, paste that exact
+code verbatim in a CODE_INPUT field. If the user only asked to generate code, or
+did not paste code, leave CODE_INPUT empty. The CODE_INPUT field is for pasted
+code ONLY — never write the final answer here.
+
+You are ROUTING ONLY. Do NOT write the final answer. A later, separate call will
+produce the answer; your job is just to categorize and surface context.
+
+Return structured output exactly in this shape:
+CATEGORY: DECISION|CODE|DIRECT
+COMPLEXITY: SIMPLE|COMPLEX
+NEEDS_CLARIFICATION: YES|NO
+GOAL: ...
+ASSUMPTIONS: ...
+CLARIFYING_QUESTIONS: ...
+CODE_INPUT: ...
+
+Prompt: {prompt}

reasonkit/prompts/critique_all.txt

@@ -0,0 +1,50 @@
+Read the reply below as if you are a blunt, practical friend who wants to
+protect the person from bad advice. Your job is to catch things that are wrong,
+misleading, unrealistic, or missing — NOT to score it.
+
+The context block contains a "Goal:" the user is actually trying to achieve, an
+"Assumptions to revisit:" list (things the original question may have taken for
+granted but that may NOT hold), and "Open clarifying questions:" the reply
+genuinely cannot answer yet. USE these. Concretely check:
+
+- Does the reply actually serve the stated goal, or does it avoid the real
+  question with a generic answer?
+- Does the reply silently assume something from "Assumptions to revisit" that
+  the user never confirmed (e.g. assuming they have capital, time, a specific
+  customer, or that the task is well-defined)? Flag it.
+- Does the reply overstate certainty, ignore real costs or risks, or leave out
+  a practical reality that changes the advice?
+- Are there important questions the reply should have admitted it can't answer,
+  but instead guessed at? Flag the guess.
+- Is the reply a disorganized wall of text, or is it well-organized and
+  scannable?
+- Does the reply acknowledge genuine downsides, trade-offs, and alternatives,
+  or is it one-sided advice?
+- Does the reply note the assumptions it's making about the user's situation?
+- Is there anything else important the reply left out?
+
+Respond with EXACTLY one block labelled "ISSUES:", and NOTHING else
+(no preamble, no rewrite, no scoring). Use this exact format:
+
+ISSUES:
+- <one specific, concrete flaw or gap, tied to the goal/assumptions above>
+- <another specific flaw or gap>
+
+Rules:
+- Each issue is ONE short, plain-language bullet about something wrong or
+  missing. No jargon. No prose.
+- Only list issues that genuinely matter. If the reply is basically sound AND
+  already honest about its assumptions and uncertainties, respond with a single
+  line: ISSUES: (none)
+- Do NOT restate the reply or praise it.
+- HONEST "NEED MORE INFO" REPLIES: if the reply is already an honest answer
+  that says plainly it cannot proceed without information the user hasn't given
+  (e.g. "please share the plan", "I need to know X"), that is the CORRECT,
+  honest response — do NOT treat the missing information as a flaw. Return
+  ISSUES: (none) rather than inventing issues like "the reply doesn't address
+  X" when the reply already said it can't until X is provided. Only flag a
+  genuine flaw in HOW it says that (e.g. it fabricated specifics it claimed
+  to need).
+
+Reply to check: {approaches}
+Context: {goal_and_assumptions}

reasonkit/prompts/deepen_concrete.txt

@@ -0,0 +1,29 @@
+The answer below is a good start but can be more specific and concrete. Improve
+it by tightening vague descriptions into specifics.
+
+Specifically:
+- Replace vague or generic descriptions with specific examples, concrete
+  numbers, or named trade-offs where possible. For instance, "costs can be
+  high" might become "rent in a prime location runs $5k-8k/month"; "it takes
+  time" might become "expect 6-12 months to break even".
+- If the answer doesn't already have one, add a concrete first move the user
+  could take in the next 7 days.
+- Strengthen the bottom line — make it more direct and actionable. What should
+  the user actually do or decide?
+- If the answer is missing important trade-offs or risks, add them.
+- If the answer doesn't surface assumptions it's making, note them.
+- If the answer sounds overly certain about things that depend on unconfirmed
+  context, say so openly.
+- Keep the existing structure, headings, section breaks, and organization
+  exactly as they are. Do not flatten, restructure, or add new sections.
+- Use natural, plain language.
+
+Answer:
+{answer}
+
+Goal / things to keep in mind:
+{goal_and_assumptions}
+
+Output ONLY the improved answer. No meta-commentary about what you changed, no
+"Here's the revised version", no "I've improved it by", no explanation. Stop
+writing the moment the answer ends. Do not add process notes.

reasonkit/prompts/fix_code.txt

@@ -0,0 +1,9 @@
+The following code has specific issues that must be fixed. Address EVERY issue
+listed, and return the COMPLETE corrected code (not a diff). Keep the same
+language and overall structure; do not add unrelated changes.
+
+Issues to fix:
+{issues}
+
+Code:
+{code}

reasonkit/prompts/generate_approaches.txt

@@ -0,0 +1,28 @@
+{goal_and_assumptions}
+
+{n_instruction}
+
+General rules for every approach:
+- Give a short, honest bottom line first.
+- Respond to exactly what the user wrote. If their message is vague or asks you
+  to assess, review, or plan something they have not actually shared, say plainly
+  that you need them to provide it — do not invent specifics they never gave.
+- Lay out the real considerations they should weigh: genuine trade-offs, risks,
+  and practical points that matter. Use plain sentences.
+- Offer a concrete recommendation where one is warranted.
+- Suggest a concrete first move the user can take if one follows naturally.
+- Acknowledge downsides and trade-offs candidly — a one-sided answer that hides
+  the hard parts is not helpful.
+- Use natural, specific language. Write the way a knowledgeable person would
+  explain it to someone they care about.
+- Organize your answer so it's easy to follow. Use clear sections to separate
+  different parts of your answer.
+- Surface any assumptions you're making about the user's situation that could
+  change the answer, and note any questions you'd need answered to give a more
+  precise recommendation.
+- If something is unclear or underspecified, say so honestly. Do not guess.
+
+{n_format}
+
+Output ONLY the approaches. Do not include any meta-commentary, reasoning about
+what you should write, or process notes — just the approaches themselves.

reasonkit/prompts/generate_code.txt

@@ -0,0 +1,13 @@
+Write complete, working code for the following request.
+
+Return ONLY the code (you may include brief inline comments), with no extra
+prose, explanation, or markdown code fences unless the language requires them.
+The code should be correct, handle obvious edge cases, and be self-contained.
+
+If the request is too vague to write code for — for example it describes a
+task without defining a key variable or asks for "an app that does X" without
+explaining what X is — do not guess. Instead, return a short, plain-language
+note saying what detail is missing and what you would need to proceed. Only
+write code when the request gives you enough to do so faithfully.
+
+Request: {prompt}

reasonkit/prompts/merge.txt

@@ -0,0 +1,43 @@
+The text below is a draft reply to the user's question, plus a blunt critique
+of what's wrong or missing in it.
+
+Produce the best, most honest version by ADDRESSING the critique — do not
+merely restate the draft:
+- For every issue the critique flagged, either fix it in the body (add the
+  missing point, correct an overclaim, name a cost or risk) or, if it can't be
+  fixed without information the user hasn't given, note that honestly.
+- Keep what's useful. Drop anything misleading. Add the concrete points the
+  critique says were left out.
+- Anchor strictly to the user's actual message and what was actually asked.
+  Never invent details, plans, or specifics they never provided.
+- Keep concrete details that are already there: specific first moves,
+  constraints, trade-offs, or risks. Do not smooth those into generic advice.
+
+Preserve the draft's structure. If the draft is well-organized, keep that
+organization — headings, section breaks, lists, and prose ordinals (First,
+Second, Finally). Do not flatten a structured answer into a generic blob.
+
+Write it the way a smart, plain-spoken person would actually answer a friend:
+- Lead with the bottom line.
+- Use natural, specific, everyday language.
+- Be concrete and admit uncertainty where it exists.
+- Note assumptions you're taking for granted about the user.
+- Include trade-offs and downsides honestly.
+- If there are questions the user would need to answer for a more tailored
+  answer, include those.
+
+Then, at the very end, include a "Worth clarifying:" section containing any
+open questions from the context (and any unresolved critique issues). If there
+are genuinely none, omit the section entirely.
+
+Output ONLY the answer itself. Do not include any meta-commentary, reasoning
+about what you changed, process notes, or phrases like "Here's a refined
+version", "Below is the improved version", "I've revised it", or similar.
+Stop writing immediately after the final section. Do not continue with
+notes about your process, what you considered, or what you chose to do.
+
+Draft reply + critique: {approaches_with_critiques}
+Goal / things to keep in mind: {goal_and_assumptions}
+
+The user's actual message (anchor your answer to this, never to details they
+didn't provide): {goal_and_assumptions}

reasonkit/prompts/refine_direct.txt

@@ -0,0 +1,23 @@
+Refine the draft: make it more honest, concrete, and useful while preserving its
+good substance.
+
+- Check for any assumptions the draft makes about the user's context that it
+  doesn't acknowledge.
+- If the draft references any invented name, product, or specific that the user
+  never gave, either use a generic placeholder or clearly label it as an
+  illustration.
+- If the draft is overly certain about things that depend on unconfirmed input,
+  flag that uncertainty.
+- Keep the bottom line near the front.
+
+Write naturally. End with a "Worth clarifying:" section listing any open
+context questions or unresolved assumptions that would change the answer, if
+there are any. If there are none, omit that section entirely.
+
+Output ONLY the refined answer.
+
+Draft answer:
+{draft}
+
+Context:
+{goal_and_assumptions}

reasonkit/prompts/refine_merge.txt

@@ -0,0 +1,35 @@
+Below is a draft answer. Review it for completeness and strengthen any
+weak dimensions — without rewriting the answer from scratch.
+
+Check for:
+1. **Organization:** Is the answer well-structured and easy to scan? If it's a
+   dense wall of text, add section breaks and clear formatting. Keep any
+   existing structure — only add where it's genuinely missing.
+
+2. **Honest reasoning:** Does the answer acknowledge genuine trade-offs,
+   downsides, risks, and alternatives where appropriate? If it's one-sided
+   advice, add the missing nuance.
+
+3. **Assumptions and clarifying questions:** Does the answer note assumptions
+   it's making about the user's situation? If the answer would change
+   materially under different circumstances, that belongs in the answer (or
+   identified as a question to the user).
+
+4. **Honesty about unknowns:** Does the answer honestly flag what it doesn't
+   know? If it sounds overly certain about things that depend on unconfirmed
+   context, say so. Do not fabricate specificity.
+
+CRITICAL RULES:
+- Keep the existing content, structure, and sections. Only add what's missing.
+- Never flatten, restructure, or replace the existing answer.
+- Use natural, plain language.
+- If all dimensions are already strong, return the answer unchanged.
+
+Draft answer:
+{answer}
+
+Goal / things to keep in mind:
+{goal_and_assumptions}
+
+Output ONLY the strengthened answer. No meta-commentary, no "Here's the revised
+version", no explanation. Stop writing the moment the answer ends.

reasonkit/prompts/verify_code.txt

@@ -0,0 +1,7 @@
+Review this code for correctness issues, edge cases, and bugs.
+
+Respond with ONLY a plain bulleted list of specific issues, and NOTHING else
+(no preamble, no summary, no corrected code). Each issue is ONE short concrete
+bullet. If there are no issues, respond with a single line: (none)
+
+{test_results}Code: {code}

reasonkit/stop_conditions.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from typing import Optional
+
+
+def count_issues(issues_by_approach: list[list[str]]) -> int:
+    # Total number of concrete issues across all approaches.
+    return sum(len(iss) for iss in issues_by_approach)
+
+
+def should_stop(
+    cycle: int,
+    max_cycles: int,
+    issues_by_approach: list[list[str]],
+    previous_issue_count: Optional[int],
+) -> tuple[bool, str]:
+    # Return (stop, reason) with reason in no_issues/no_improvement/max_cycles.
+    total = count_issues(issues_by_approach)
+
+    if total == 0:
+        return True, "no_issues"
+
+    if previous_issue_count is not None and total >= previous_issue_count:
+        return True, "no_improvement"  # list didn't shrink
+
+    if cycle >= max_cycles:
+        return True, "max_cycles"
+
+    return False, ""

reasonkit/trace.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class CallRecord:
+    # One call ReasonKit made through the wrapped function.
+
+    stage: str          # classify | generate | critique | merge | answer
+    prompt: str         # exact prompt sent to fn
+    response: str       # raw string fn returned
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Trace:
+    # Everything that happened inside one enhance() run.
+
+    mode: str = "unknown"                       # decision | code | direct
+    calls: list[CallRecord] = field(default_factory=list)
+    cycles: int = 0
+    stopped_reason: str = "unknown"             # no_issues | no_improvement | max_cycles
+    classification: dict[str, Any] = field(default_factory=dict)
+    notes: list[str] = field(default_factory=list)
+    code_versions: list[str] = field(default_factory=list)  # each draft/fix
+
+    def add_call(self, stage: str, prompt: str, response: str, **metadata: Any) -> CallRecord:
+        rec = CallRecord(stage=stage, prompt=prompt, response=response, metadata=dict(metadata))
+        self.calls.append(rec)
+        return rec
+
+    @property
+    def call_count(self) -> int:
+        return len(self.calls)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "mode": self.mode,
+            "cycles": self.cycles,
+            "stopped_reason": self.stopped_reason,
+            "call_count": self.call_count,
+            "classification": self.classification,
+            "notes": self.notes,
+            "code_versions": self.code_versions,
+            "calls": [
+                {
+                    "stage": c.stage,
+                    "prompt": c.prompt,
+                    "response": c.response,
+                    "metadata": c.metadata,
+                }
+                for c in self.calls
+            ],
+        }