thought-fork 0.6.0__py3-none-any.whl

thought_fork/__init__.py

@@ -0,0 +1,165 @@
+# Copyright 2026 Ameen Saeed
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Thought Fork — Branch your AI's reasoning like Git branches.
+
+Thought Fork spawns N parallel reasoning paths ("forks") from a single prompt,
+each biased by a different stance, then merges them into a synthesis with
+explicit attribution.
+
+Concept and vocabulary by Ameen Saeed, June 2026.
+
+Simple usage::
+
+    from thought_fork import synthesize
+
+    result = await synthesize("Should I migrate to microservices?", fork_count=3)
+    print(result.synthesis)          # Attributed final answer
+    print(result.forks["cautious"])  # Individual fork output
+    print(result.token_usage)        # {"forks": ..., "synthesis": ..., "total": ...}
+
+Advanced usage with custom stances::
+
+    from thought_fork import Fork, synthesize
+
+    result = await synthesize(
+        "Review this architecture",
+        forks=[
+            Fork(id="A", stance="security",     system_prompt="Find vulnerabilities"),
+            Fork(id="B", stance="performance",  system_prompt="Find bottlenecks"),
+            Fork(id="C", stance="maintainability", system_prompt="Find complexity risks"),
+        ]
+    )
+"""
+
+from __future__ import annotations
+
+import time
+
+__version__ = "0.6.0"
+__author__ = "Ameen Saeed"
+
+from thought_fork.config import BUILT_IN_STANCES, ForkConfig
+from thought_fork.fork import Fork, get_stance_prompt
+from thought_fork.manager import ForkManager
+from thought_fork.message import Message
+from thought_fork.result import ForkResult
+from thought_fork.stance_selector import SelectedStance, StanceSelector
+from thought_fork.synthesis import (
+    FORK_OUTPUT_TEMPLATE,
+    SYNTHESIS_SYSTEM_PROMPT,
+    SYNTHESIS_USER_TEMPLATE,
+    SynthesisEngine,
+)
+
+
+async def synthesize(
+    prompt: str,
+    fork_count: int = 3,
+    stances: list[str] | None = None,
+    forks: list[Fork] | None = None,
+    history: list[Message] | None = None,
+    config: ForkConfig | None = None,
+) -> ForkResult:
+    """Fork a prompt into parallel reasoning paths and synthesize.
+
+    This is the main entry point for the Thought Fork library.
+    It wraps ForkManager + SynthesisEngine into a single async call.
+
+    Args:
+        prompt: The question or problem to fork.
+        fork_count: Number of forks to spawn (ignored if ``forks`` is provided).
+        stances: List of stance names. Defaults to the first N built-in stances.
+        forks: Advanced — provide pre-built Fork objects with custom system prompts.
+        history: Optional list of previous Message objects for multi-turn context.
+        config: Optional ForkConfig to override model selection and limits.
+
+    Returns:
+        A ForkResult containing the synthesis, individual fork outputs,
+        and token usage statistics.
+    """
+    config = config or ForkConfig()
+    manager = ForkManager(config)
+    engine = SynthesisEngine(config)
+
+    overall_start = time.perf_counter()
+
+    # Create or use provided forks
+    if forks is not None:
+        # Advanced: caller provided pre-built Fork objects
+        fork_list = forks
+    elif stances is not None:
+        # Caller specified explicit stance names → use built-ins / custom prompts
+        fork_list = manager.create_forks(prompt, stances)
+    elif config.use_dynamic_stances:
+        # Default: let AI invent the best stances for this prompt
+        selector = StanceSelector(config)
+        selected = await selector.select(prompt, fork_count, history)
+        fork_list = selector.to_forks(selected)
+    else:
+        # Dynamic stances disabled → use configured default stances
+        resolved_stances = list(BUILT_IN_STANCES.keys())[:fork_count]
+        fork_list = manager.create_forks(prompt, resolved_stances)
+
+    # Run forks in parallel
+    fork_list = await manager.run_parallel(fork_list, prompt, history)
+
+    # Synthesize
+    synthesis_text, synthesis_tokens, synthesis_duration = (
+        await engine.synthesize(prompt, fork_list, history)
+    )
+
+    # Build result
+    total_fork_tokens = sum(f.token_count for f in fork_list)
+    total_tokens = total_fork_tokens + synthesis_tokens
+    overall_duration = int((time.perf_counter() - overall_start) * 1000)
+
+    return ForkResult(
+        synthesis=synthesis_text,
+        forks={f.stance: f.output for f in fork_list},
+        fork_details=[
+            {
+                "id": f.id,
+                "stance": f.stance,
+                "output": f.output,
+                "token_count": f.token_count,
+                "duration_ms": f.duration_ms,
+            }
+            for f in fork_list
+        ],
+        token_usage={
+            "forks": total_fork_tokens,
+            "synthesis": synthesis_tokens,
+            "total": total_tokens,
+        },
+        duration_ms=overall_duration,
+    )
+
+
+__all__ = [
+    "synthesize",
+    "Fork",
+    "ForkConfig",
+    "ForkManager",
+    "ForkResult",
+    "SelectedStance",
+    "StanceSelector",
+    "SynthesisEngine",
+    "BUILT_IN_STANCES",
+    "FORK_OUTPUT_TEMPLATE",
+    "SYNTHESIS_SYSTEM_PROMPT",
+    "SYNTHESIS_USER_TEMPLATE",
+    "get_stance_prompt",
+]

thought_fork/cli.py

@@ -0,0 +1,175 @@
+# Copyright 2026 Ameen Saeed
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Thought Fork — Command-line interface.
+
+Usage:
+    thought-fork "Should I use microservices?" --forks 3
+    thought-fork "Review this architecture" --forks 4 --static
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+import time
+
+from dotenv import load_dotenv
+
+
+# Fork colors for terminal output (ANSI escape codes)
+FORK_COLORS = [
+    "\033[94m",   # Blue
+    "\033[93m",   # Yellow/Amber
+    "\033[91m",   # Red
+    "\033[92m",   # Green
+    "\033[95m",   # Magenta
+    "\033[96m",   # Cyan
+    "\033[90m",   # Gray
+]
+RESET = "\033[0m"
+BOLD = "\033[1m"
+DIM = "\033[2m"
+
+
+def _print_banner() -> None:
+    """Print the Thought Fork banner."""
+    print()
+    print(f"{BOLD}🔀 Thought Fork — Branch your AI's reasoning{RESET}")
+    print()
+
+
+def _print_fork_result(fork_detail: dict, color: str) -> None:
+    """Print a single fork's output with styled header."""
+    print()
+    print(f"{color}{BOLD}{'═' * 60}{RESET}")
+    print(f"{color}{BOLD}  Fork {fork_detail['id']} — {fork_detail['stance']}{RESET}")
+    print(f"{color}{BOLD}{'═' * 60}{RESET}")
+    print()
+    print(fork_detail["output"])
+    print()
+
+
+def _print_synthesis(synthesis_text: str) -> None:
+    """Print the synthesis output with styled header."""
+    print()
+    print(f"{BOLD}{'═' * 60}{RESET}")
+    print(f"{BOLD}  ✦ Synthesis (Convergence){RESET}")
+    print(f"{BOLD}{'═' * 60}{RESET}")
+    print()
+    print(synthesis_text)
+    print()
+
+
+def _print_summary(fork_details: list[dict], token_usage: dict, duration_ms: int) -> None:
+    """Print token usage summary."""
+    print(f"{BOLD}📊 Token Usage Summary{RESET}")
+    print(f"┌──────┬──────────────────────────────┬────────┬──────────┐")
+    print(f"│ Fork │ Stance                       │ Tokens │ Duration │")
+    print(f"├──────┼──────────────────────────────┼────────┼──────────┤")
+
+    for detail in fork_details:
+        duration_s = detail["duration_ms"] / 1000
+        stance = detail["stance"][:28]
+        print(
+            f"│ {detail['id']:<4} │ {stance:<28} │ {detail['token_count']:>6} │ {duration_s:>6.1f}s  │"
+        )
+
+    print(f"├──────┼──────────────────────────────┼────────┼──────────┤")
+    total_s = duration_ms / 1000
+    print(
+        f"│ {'ALL':<4} │ {'TOTAL':<28} │ {token_usage['total']:>6} │ {total_s:>6.1f}s  │"
+    )
+    print(f"└──────┴──────────────────────────────┴────────┴──────────┘")
+    print()
+
+
+async def _run(prompt: str, fork_count: int, use_dynamic: bool) -> None:
+    """Execute a Thought Fork session."""
+    from thought_fork import ForkConfig, synthesize
+
+    config = ForkConfig(use_dynamic_stances=use_dynamic)
+
+    _print_banner()
+    print(f"{BOLD}Prompt:{RESET} {prompt}")
+    print(f"{DIM}Forks: {fork_count} | Dynamic stances: {'on' if use_dynamic else 'off'}{RESET}")
+    print()
+    print("⏳ Forking...")
+
+    result = await synthesize(prompt, fork_count=fork_count, config=config)
+
+    # Print each fork
+    for i, detail in enumerate(result.fork_details):
+        color = FORK_COLORS[i % len(FORK_COLORS)]
+        _print_fork_result(detail, color)
+
+    # Print synthesis
+    _print_synthesis(result.synthesis)
+
+    # Print summary
+    _print_summary(result.fork_details, result.token_usage, result.duration_ms)
+
+    print(
+        f"{DIM}Forks ran in parallel — wall-clock time is the slowest fork, "
+        f"not the sum.{RESET}"
+    )
+    print()
+
+
+def main() -> None:
+    """CLI entry point for Thought Fork."""
+    # Ensure UTF-8 output on Windows terminals
+    if sys.platform == "win32":
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+        sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+
+    load_dotenv()
+
+    parser = argparse.ArgumentParser(
+        prog="thought-fork",
+        description="🔀 Thought Fork — Branch your AI's reasoning like Git branches.",
+        epilog="Example: thought-fork \"Should I use microservices?\" --forks 3",
+    )
+    parser.add_argument(
+        "prompt",
+        help="The question or problem to fork into parallel reasoning paths.",
+    )
+    parser.add_argument(
+        "--forks", "-n",
+        type=int,
+        default=3,
+        help="Number of parallel forks to spawn (default: 3).",
+    )
+    parser.add_argument(
+        "--static",
+        action="store_true",
+        help="Use static built-in stances instead of AI-selected dynamic stances.",
+    )
+
+    args = parser.parse_args()
+
+    try:
+        asyncio.run(_run(args.prompt, args.forks, use_dynamic=not args.static))
+    except KeyboardInterrupt:
+        print(f"\n{DIM}Cancelled.{RESET}")
+        sys.exit(0)
+    except ValueError as e:
+        print(f"\n❌ {e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

thought_fork/config.py

@@ -0,0 +1,171 @@
+# Copyright 2026 Ameen Saeed
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Thought Fork — Configuration and built-in stance definitions.
+
+This module defines the ForkConfig dataclass for controlling fork/synthesis
+behavior, and the BUILT_IN_STANCES dictionary mapping stance names to their
+system prompts.
+"""
+
+import os
+from dataclasses import dataclass, field
+from typing import Any
+
+
+# ---------------------------------------------------------------------------
+# Built-in Stances
+# ---------------------------------------------------------------------------
+# Each stance is a system prompt that biases a fork's reasoning toward a
+# specific perspective. These are the stances defined as part of the
+# Thought Fork framework (see CONCEPT.md).
+
+BUILT_IN_STANCES: dict[str, str] = {
+    "cautious": (
+        "You are a seasoned risk analyst and cautious strategist. "
+        "Your methodology: identify every risk, edge case, failure mode, and second-order consequence BEFORE considering benefits. "
+        "You think in terms of 'what kills us?' not 'what helps us?' "
+        "Reason with precision. Use specific examples of real-world failures to ground your analysis. "
+        "Provide concrete safeguards and mitigation strategies, not vague warnings. "
+        "Your standard of evidence is high — demand data, precedent, or logical proof for every claim."
+    ),
+    "creative": (
+        "You are a lateral thinker and innovation strategist with deep expertise in analogical reasoning. "
+        "Your methodology: actively reject the first 3 obvious answers and force yourself to explore non-obvious angles. "
+        "Draw analogies from completely different domains — biology, game theory, art, history, physics — to illuminate the problem from unexpected directions. "
+        "Challenge the framing of the question itself. Propose solutions that feel counterintuitive but are logically sound. "
+        "Your output should make the reader say 'I never would have thought of that.' "
+        "Be specific and substantive — creative does NOT mean vague."
+    ),
+    "critical": (
+        "You are an adversarial critic and intellectual stress-tester. "
+        "Your methodology: assume the prevailing answer is wrong and rigorously argue why. "
+        "Challenge every premise, every assumption, every piece of 'conventional wisdom.' "
+        "Use formal logical analysis — identify specific fallacies, hidden assumptions, and gaps in evidence. "
+        "You are not cynical; you are surgically precise. Your goal is to make the argument stronger by finding its weakest links. "
+        "Quote specific claims and show exactly where they fail under scrutiny."
+    ),
+    "pragmatic": (
+        "You are a battle-tested execution strategist and operational pragmatist. "
+        "Your methodology: ruthlessly filter for what actually works in practice given real-world constraints. "
+        "Ignore theoretical elegance — focus on implementation complexity, resource requirements, timeline, and ROI. "
+        "Provide concrete action plans with specific steps, not abstract frameworks. "
+        "Draw on real examples of successful execution in similar situations. "
+        "Your output should be immediately actionable by someone with a budget and a deadline."
+    ),
+    "first-principles": (
+        "You are a first-principles thinker in the tradition of Feynman and Musk. "
+        "Your methodology: strip away every assumption, convention, and inherited belief until you reach bedrock truths. "
+        "Then rebuild the answer from those fundamentals using rigorous logical chains. "
+        "Explicitly name each assumption you're discarding and explain why it might be wrong. "
+        "Your reasoning should be transparent — show every step from axiom to conclusion. "
+        "If the conventional answer happens to be right, prove it from first principles rather than accepting it on authority."
+    ),
+    "optimistic": (
+        "You are a strategic optimist and opportunity analyst. "
+        "Your methodology: map the full landscape of upside potential, best-case trajectories, and compounding advantages. "
+        "Identify catalysts and tailwinds that others miss because they're focused on risks. "
+        "Your optimism is NOT naive — it is grounded in specific evidence, precedent, and logical reasoning about why things could go right. "
+        "Provide a concrete roadmap for capturing the identified opportunities. "
+        "Show how small advantages compound into transformative outcomes."
+    ),
+    "contrarian": (
+        "You are a professional contrarian and independent thinker. "
+        "Your methodology: identify the consensus view, then rigorously build the strongest possible case for the opposite position. "
+        "Find historical examples where the contrarian view was correct and the consensus was catastrophically wrong. "
+        "You are not being contrarian for its own sake — you genuinely believe the best insights hide in unpopular positions. "
+        "Steel-man the opposing view before attacking the consensus. "
+        "Your output should make the reader seriously reconsider what they thought they knew."
+    ),
+}
+
+
+# ---------------------------------------------------------------------------
+# ForkConfig
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ForkConfig:
+    """Configuration for the Thought Fork engine.
+
+    Attributes:
+        fork_model: Model identifier for fork reasoning (fast/cheap).
+        synthesis_model: Model identifier for synthesis (quality).
+        stance_selector_model: Model used for dynamic stance selection (fast/cheap).
+        default_stances: List of stance names used when none are specified and
+            dynamic stances are disabled.
+        max_tokens: Maximum tokens per fork/synthesis response.
+        api_base_url: Base URL for the API (default: OpenRouter).
+        api_key: API key for the provider. If None, attempts to resolve from
+            OPENAI_API_KEY or OPENROUTER_API_KEY environment variables.
+        use_dynamic_stances: If True (default), uses AI to invent custom stances
+            for each prompt. If False, uses default_stances (static built-ins).
+        timeout_seconds: Maximum time in seconds to wait for a single API call.
+        max_concurrent_forks: Maximum number of forks to run simultaneously.
+        max_retries: Maximum number of times to retry a failed API call.
+        client: Optional pre-configured AsyncOpenAI client instance.
+    """
+
+    fork_model: str = "anthropic/claude-haiku-4.5"
+    synthesis_model: str = "anthropic/claude-sonnet-4-6"
+    stance_selector_model: str = "anthropic/claude-haiku-4.5"
+    default_stances: list[str] = field(
+        default_factory=lambda: ["cautious", "creative", "critical"]
+    )
+    available_models: list[str] = field(default_factory=list)
+    max_tokens: int = 2048
+    synthesis_max_tokens: int = 6144
+    api_base_url: str = "https://openrouter.ai/api/v1"
+    api_key: str | None = None
+    use_dynamic_stances: bool = True
+    timeout_seconds: float = 120.0
+    max_concurrent_forks: int = 5
+    max_retries: int = 2
+    client: Any | None = None
+
+    def __post_init__(self):
+        """Resolve API key and overrides from environment if not explicitly provided."""
+        if not self.api_key:
+            self.api_key = os.getenv("THOUGHT_FORK_API_KEY") or os.getenv("OPENROUTER_API_KEY") or os.getenv("OPENAI_API_KEY")
+            
+        if os.getenv("THOUGHT_FORK_API_BASE"):
+            self.api_base_url = os.getenv("THOUGHT_FORK_API_BASE")
+            
+        if os.getenv("THOUGHT_FORK_MODEL"):
+            self.fork_model = os.getenv("THOUGHT_FORK_MODEL")
+            
+        if os.getenv("THOUGHT_FORK_SYNTHESIS_MODEL"):
+            self.synthesis_model = os.getenv("THOUGHT_FORK_SYNTHESIS_MODEL")
+        elif os.getenv("THOUGHT_FORK_MODEL"):
+            self.synthesis_model = os.getenv("THOUGHT_FORK_MODEL")
+            
+        if os.getenv("THOUGHT_FORK_SELECTOR_MODEL"):
+            self.stance_selector_model = os.getenv("THOUGHT_FORK_SELECTOR_MODEL")
+        elif os.getenv("THOUGHT_FORK_MODEL"):
+            self.stance_selector_model = os.getenv("THOUGHT_FORK_MODEL")
+            
+        if os.getenv("THOUGHT_FORK_AVAILABLE_MODELS"):
+            models = os.getenv("THOUGHT_FORK_AVAILABLE_MODELS").split(",")
+            self.available_models = [m.strip() for m in models if m.strip()]
+        
+        # Check if URL is local (Ollama/vLLM)
+        is_local = any(host in self.api_base_url for host in ["localhost", "127.0.0.1", "0.0.0.0"])
+        
+        if not self.api_key and not is_local:
+            raise ValueError(
+                "No API key found. Set OPENROUTER_API_KEY or OPENAI_API_KEY "
+                "in your environment, or pass api_key= to ForkConfig(). "
+                "Note: API key is not required for local URLs (localhost/127.0.0.1)."
+            )

thought_fork/fork.py

@@ -0,0 +1,61 @@
+# Copyright 2026 Ameen Saeed
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Thought Fork — Fork dataclass and stance resolution.
+
+A Fork represents a single parallel reasoning path. Each fork has a stance
+(its reasoning perspective) and a system prompt that biases the AI toward
+that stance.
+"""
+
+from dataclasses import dataclass
+
+from thought_fork.config import BUILT_IN_STANCES
+
+
+@dataclass
+class Fork:
+    """A single parallel reasoning path in the Thought Fork framework.
+
+    Attributes:
+        id: Letter identifier for this fork ("A", "B", "C", ...).
+        stance: The reasoning perspective (e.g., "cautious", "creative").
+        system_prompt: The full system prompt that biases reasoning.
+        output: The fork's generated reasoning output (populated after execution).
+        token_count: Number of tokens used in the response (populated after execution).
+        duration_ms: Execution time in milliseconds (populated after execution).
+    """
+
+    id: str
+    stance: str
+    system_prompt: str
+    output: str = ""
+    token_count: int = 0
+    duration_ms: int = 0
+
+
+def get_stance_prompt(stance: str) -> str:
+    """Resolve a stance name to its system prompt.
+
+    If the stance name matches a built-in stance, returns that prompt.
+    Otherwise, treats the stance string itself as a custom system prompt.
+
+    Args:
+        stance: A built-in stance name (e.g., "cautious") or a custom prompt string.
+
+    Returns:
+        The resolved system prompt for the given stance.
+    """
+    return BUILT_IN_STANCES.get(stance, stance)