quickthink 0.2.1__py3-none-any.whl

quickthink/__init__.py

@@ -0,0 +1,6 @@
+"""quickthink package."""
+
+from .config import QuickThinkConfig
+from .engine import QuickThinkEngine
+
+__all__ = ["QuickThinkConfig", "QuickThinkEngine"]

quickthink/cli.py

@@ -0,0 +1,187 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from importlib.metadata import version as package_version
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from .config import MODEL_PROFILES, PRESET_PROFILES, SUPPORTED_MODELS, QuickThinkConfig
+from .engine import QuickThinkEngine
+from .ui_server import serve_ui
+
+app = typer.Typer(help="Compressed planning scaffold for local LLMs")
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(package_version("quickthink"))
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show the installed quickthink version and exit.",
+    ),
+) -> None:
+    """Compressed planning scaffold for local LLMs."""
+
+
+@app.command()
+def list_models() -> None:
+    for model, profile in MODEL_PROFILES.items():
+        typer.echo(f"{model} -> {json.dumps(profile)}")
+
+
+@app.command()
+def list_presets() -> None:
+    for preset, profile in PRESET_PROFILES.items():
+        typer.echo(f"{preset} -> {json.dumps(profile)}")
+
+
+@app.command()
+def compatibility() -> None:
+    for model in SUPPORTED_MODELS:
+        typer.echo(model)
+
+
+@app.command()
+def ask(
+    prompt: str = typer.Argument(..., help="User prompt"),
+    model: str = typer.Option("qwen2.5:1.5b", help="Ollama model"),
+    ollama_url: str = typer.Option("http://localhost:11434", help="Ollama base URL"),
+    mode: str = typer.Option("lite", help="Execution mode: lite or two_pass"),
+    preset: str = typer.Option("balanced", help="Preset profile: fast, balanced, strict"),
+    show_plan: bool = typer.Option(False, help="Show compressed plan in terminal output"),
+    show_route: bool = typer.Option(False, help="Show routing diagnostics"),
+    log_file: Optional[Path] = typer.Option(None, help="Optional JSONL log file"),
+    bypass_short_prompts: bool = typer.Option(True, help="Skip plan stage for short prompts"),
+    continuity_hint: Optional[str] = typer.Option(None, help="Optional tiny continuity hint"),
+    lane_policy: str = typer.Option("default", help="Lane policy: default or strict_safe"),
+) -> None:
+    if mode not in {"lite", "two_pass"}:
+        raise typer.BadParameter("mode must be 'lite' or 'two_pass'")
+    if preset not in PRESET_PROFILES:
+        raise typer.BadParameter("preset must be one of: fast, balanced, strict")
+    if lane_policy not in {"default", "strict_safe"}:
+        raise typer.BadParameter("lane-policy must be 'default' or 'strict_safe'")
+    config = QuickThinkConfig.with_model_profile(model=model, ollama_url=ollama_url)
+    config.apply_preset(preset)
+    config.bypass_short_prompts = bypass_short_prompts
+    config.mode = mode
+    config.continuity_hint = continuity_hint
+    config.lane_policy = lane_policy
+    engine = QuickThinkEngine(config)
+
+    result = engine.run(prompt)
+
+    if show_route:
+        typer.echo(
+            f"[route] mode={result.mode} bypassed={result.bypassed} score={result.route_score} "
+            f"plan_budget={result.selected_plan_budget} repaired={result.plan_repaired}"
+        )
+    if show_plan and result.plan:
+        typer.echo(f"[plan] {result.plan}")
+    typer.echo(result.answer)
+
+    if log_file:
+        log_file.parent.mkdir(parents=True, exist_ok=True)
+        with log_file.open("a", encoding="utf-8") as fh:
+            fh.write(
+                json.dumps(
+                    {
+                        "prompt": prompt,
+                        "model": model,
+                        "preset": config.preset,
+                        "mode": result.mode,
+                        "timestamp": datetime.now(timezone.utc).replace(microsecond=0).isoformat(),
+                        "answer": result.answer,
+                        "plan": result.plan,
+                        "bypassed": result.bypassed,
+                        "route_score": result.route_score,
+                        "selected_plan_budget": result.selected_plan_budget,
+                        "plan_repaired": result.plan_repaired,
+                        "plan_latency_ms": round(result.plan_latency_ms, 2),
+                        "answer_latency_ms": round(result.answer_latency_ms, 2),
+                        "total_latency_ms": round(result.total_latency_ms, 2),
+                    }
+                )
+                + "\n"
+            )
+
+
+@app.command()
+def bench(
+    prompt: str = typer.Argument(..., help="Benchmark prompt"),
+    model: str = typer.Option("qwen2.5:1.5b", help="Ollama model"),
+    ollama_url: str = typer.Option("http://localhost:11434", help="Ollama base URL"),
+    runs: int = typer.Option(3, min=1, max=20, help="Number of runs per mode"),
+    preset: str = typer.Option("balanced", help="Preset profile: fast, balanced, strict"),
+    lane_policy: str = typer.Option("default", help="Lane policy: default or strict_safe"),
+) -> None:
+    if preset not in PRESET_PROFILES:
+        raise typer.BadParameter("preset must be one of: fast, balanced, strict")
+    if lane_policy not in {"default", "strict_safe"}:
+        raise typer.BadParameter("lane-policy must be 'default' or 'strict_safe'")
+    lite_latencies: list[float] = []
+    two_pass_latencies: list[float] = []
+    direct_latencies: list[float] = []
+
+    config_lite = QuickThinkConfig.with_model_profile(model=model, ollama_url=ollama_url)
+    config_lite.apply_preset(preset)
+    config_lite.mode = "lite"
+    config_lite.lane_policy = lane_policy
+    engine_lite = QuickThinkEngine(config_lite)
+    for _ in range(runs):
+        lite_latencies.append(engine_lite.run(prompt).total_latency_ms)
+
+    config_two_pass = QuickThinkConfig.with_model_profile(model=model, ollama_url=ollama_url)
+    config_two_pass.apply_preset(preset)
+    config_two_pass.mode = "two_pass"
+    config_two_pass.lane_policy = lane_policy
+    engine_two_pass = QuickThinkEngine(config_two_pass)
+    for _ in range(runs):
+        two_pass_latencies.append(engine_two_pass.run(prompt).total_latency_ms)
+
+    config_direct = QuickThinkConfig.with_model_profile(model=model, ollama_url=ollama_url)
+    config_direct.apply_preset(preset)
+    config_direct.mode = "lite"
+    config_direct.lane_policy = lane_policy
+    config_direct.bypass_short_prompts = True
+    config_direct.adaptive_routing = False
+    config_direct.bypass_char_threshold = 100_000
+    engine_direct = QuickThinkEngine(config_direct)
+    for _ in range(runs):
+        direct_latencies.append(engine_direct.run(prompt).total_latency_ms)
+
+    avg_lite = sum(lite_latencies) / len(lite_latencies)
+    avg_two_pass = sum(two_pass_latencies) / len(two_pass_latencies)
+    avg_direct = sum(direct_latencies) / len(direct_latencies)
+
+    typer.echo(f"model={model}")
+    typer.echo(f"preset={preset}")
+    typer.echo(f"avg_lite_ms={avg_lite:.2f}")
+    typer.echo(f"avg_two_pass_ms={avg_two_pass:.2f}")
+    typer.echo(f"avg_direct_ms={avg_direct:.2f}")
+    typer.echo(f"lite_overhead_ms={avg_lite-avg_direct:.2f}")
+    typer.echo(f"two_pass_overhead_ms={avg_two_pass-avg_direct:.2f}")
+
+
+@app.command()
+def ui(
+    host: str = typer.Option("127.0.0.1", help="Bind host"),
+    port: int = typer.Option(7860, min=1, max=65535, help="Bind port"),
+    open_browser: bool = typer.Option(True, help="Open UI in browser on startup"),
+) -> None:
+    serve_ui(host=host, port=port, open_browser=open_browser)
+
+
+if __name__ == "__main__":
+    app()

quickthink/config.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+SUPPORTED_MODELS = (
+    "qwen2.5:1.5b",
+    "mistral:7b",
+    "gemma3:27b",
+)
+
+MODEL_PROFILES = {
+    "qwen2.5:1.5b": {
+        "plan_budget_tokens": 8,
+        "min_plan_budget_tokens": 6,
+        "max_plan_budget_tokens": 12,
+        "temperature": 0.3,
+        "top_p": 0.9,
+    },
+    "mistral:7b": {
+        "plan_budget_tokens": 10,
+        "min_plan_budget_tokens": 8,
+        "max_plan_budget_tokens": 16,
+        "temperature": 0.25,
+        "top_p": 0.9,
+    },
+    "gemma3:27b": {
+        "plan_budget_tokens": 8,
+        "min_plan_budget_tokens": 6,
+        "max_plan_budget_tokens": 14,
+        "temperature": 0.2,
+        "top_p": 0.85,
+    },
+}
+
+PRESET_PROFILES = {
+    "fast": {
+        "min_plan_budget_tokens": 4,
+        "max_plan_budget_tokens": 8,
+        "route_skip_score_threshold": 2,
+        "bypass_char_threshold": 180,
+        "temperature": 0.2,
+        "top_p": 0.85,
+    },
+    "balanced": {
+        "min_plan_budget_tokens": 6,
+        "max_plan_budget_tokens": 12,
+        "route_skip_score_threshold": 1,
+        "bypass_char_threshold": 120,
+        "temperature": 0.3,
+        "top_p": 0.9,
+    },
+    "strict": {
+        "min_plan_budget_tokens": 8,
+        "max_plan_budget_tokens": 16,
+        "route_skip_score_threshold": 0,
+        "bypass_char_threshold": 80,
+        "temperature": 0.15,
+        "top_p": 0.8,
+    },
+}
+
+
+@dataclass
+class QuickThinkConfig:
+    model: str = "qwen2.5:1.5b"
+    ollama_url: str = "http://localhost:11434"
+    provider: str = "ollama"
+    plan_budget_tokens: int = 8
+    min_plan_budget_tokens: int = 6
+    max_plan_budget_tokens: int = 12
+    temperature: float = 0.3
+    top_p: float = 0.9
+    bypass_short_prompts: bool = True
+    bypass_char_threshold: int = 120
+    adaptive_routing: bool = True
+    route_skip_score_threshold: int = 1
+    mode: str = "lite"
+    continuity_hint: str | None = None
+    preset: str = "balanced"
+    request_timeout_s: float = 180.0
+    think: bool | str | None = None
+    scaffold_rules: str | None = None
+    lane_policy: str = "default"
+
+    @classmethod
+    def with_model_profile(cls, model: str, ollama_url: str = "http://localhost:11434") -> "QuickThinkConfig":
+        profile = MODEL_PROFILES.get(model, {})
+        return cls(
+            model=model,
+            ollama_url=ollama_url,
+            plan_budget_tokens=profile.get("plan_budget_tokens", 8),
+            min_plan_budget_tokens=profile.get("min_plan_budget_tokens", 6),
+            max_plan_budget_tokens=profile.get("max_plan_budget_tokens", 12),
+            temperature=profile.get("temperature", 0.3),
+            top_p=profile.get("top_p", 0.9),
+        )
+
+    def apply_preset(self, preset: str) -> None:
+        profile = PRESET_PROFILES.get(preset)
+        if not profile:
+            raise ValueError(f"Unknown preset '{preset}'")
+        self.preset = preset
+        self.min_plan_budget_tokens = int(profile["min_plan_budget_tokens"])
+        self.max_plan_budget_tokens = int(profile["max_plan_budget_tokens"])
+        self.route_skip_score_threshold = int(profile["route_skip_score_threshold"])
+        self.bypass_char_threshold = int(profile["bypass_char_threshold"])
+        self.temperature = float(profile["temperature"])
+        self.top_p = float(profile["top_p"])

quickthink/engine.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from time import perf_counter
+
+from .config import QuickThinkConfig
+from .inline_protocol import extract_plan_and_answer
+from .ollama_client import OllamaClient
+from .plan_grammar import is_valid_plan, normalize_plan
+from .prompts import (
+    make_answer_prompt,
+    make_inline_plan_answer_prompt,
+    make_plan_prompt,
+    make_plan_repair_prompt,
+)
+from .routing import infer_task_class, should_bypass
+
+
+@dataclass
+class QuickThinkResult:
+    answer: str
+    plan: str | None
+    mode: str
+    bypassed: bool
+    route_score: int
+    selected_plan_budget: int
+    plan_repaired: bool
+    plan_latency_ms: float
+    answer_latency_ms: float
+
+    @property
+    def total_latency_ms(self) -> float:
+        return self.plan_latency_ms + self.answer_latency_ms
+
+
+class QuickThinkEngine:
+    def __init__(self, config: QuickThinkConfig) -> None:
+        self.config = config
+        self.client = OllamaClient(config.ollama_url, timeout_s=config.request_timeout_s)
+
+    def run(self, prompt: str) -> QuickThinkResult:
+        if self.config.lane_policy == "strict_safe" and infer_task_class(prompt) == "strict_format":
+            return self._run_direct(prompt=prompt, route_score=-1, selected_budget=self.config.min_plan_budget_tokens)
+
+        bypass, route_score, selected_budget = should_bypass(prompt, self.config)
+        if bypass:
+            return self._run_direct(prompt=prompt, route_score=route_score, selected_budget=selected_budget)
+
+        if self.config.mode == "two_pass":
+            return self._run_two_pass(prompt, route_score, selected_budget)
+        if self.config.mode == "direct":
+            return self._run_direct(prompt=prompt, route_score=route_score, selected_budget=selected_budget)
+        return self._run_lite(prompt, route_score, selected_budget)
+
+    def _run_direct(self, prompt: str, route_score: int, selected_budget: int) -> QuickThinkResult:
+        start = perf_counter()
+        answer_raw = self.client.generate(
+            model=self.config.model,
+            prompt=prompt,
+            temperature=self.config.temperature,
+            top_p=self.config.top_p,
+            max_tokens=512,
+            think=self.config.think,
+        )
+        answer_ms = (perf_counter() - start) * 1000
+        return QuickThinkResult(
+            answer=answer_raw.get("response", "").strip(),
+            plan=None,
+            mode=self.config.mode,
+            bypassed=True,
+            route_score=route_score,
+            selected_plan_budget=selected_budget,
+            plan_repaired=False,
+            plan_latency_ms=0.0,
+            answer_latency_ms=answer_ms,
+        )
+
+    def _run_lite(self, prompt: str, route_score: int, selected_budget: int) -> QuickThinkResult:
+        inline_prompt = make_inline_plan_answer_prompt(
+            prompt,
+            selected_budget,
+            continuity_hint=self.config.continuity_hint,
+            scaffold_rules=self.config.scaffold_rules,
+        )
+        start = perf_counter()
+        raw = self.client.generate(
+            model=self.config.model,
+            prompt=inline_prompt,
+            temperature=self.config.temperature,
+            top_p=self.config.top_p,
+            max_tokens=768,
+            think=self.config.think,
+        )
+        answer_ms = (perf_counter() - start) * 1000
+
+        raw_text = raw.get("response", "")
+        plan, answer = extract_plan_and_answer(raw_text)
+        repaired = False
+
+        if plan and not is_valid_plan(plan, selected_budget):
+            repaired = True
+            plan = "g:solve;c:constraints;s:direct_reasoning;r:verify_output"
+        if plan is None:
+            repaired = True
+
+        return QuickThinkResult(
+            answer=answer.strip(),
+            plan=plan,
+            mode="lite",
+            bypassed=False,
+            route_score=route_score,
+            selected_plan_budget=selected_budget,
+            plan_repaired=repaired,
+            plan_latency_ms=0.0,
+            answer_latency_ms=answer_ms,
+        )
+
+    def _run_two_pass(self, prompt: str, route_score: int, selected_budget: int) -> QuickThinkResult:
+        plan_prompt = make_plan_prompt(prompt, selected_budget)
+        start = perf_counter()
+        plan_raw = self.client.generate(
+            model=self.config.model,
+            prompt=plan_prompt,
+            temperature=min(self.config.temperature, 0.3),
+            top_p=self.config.top_p,
+            max_tokens=selected_budget,
+            think=self.config.think,
+        )
+        plan_ms = (perf_counter() - start) * 1000
+        plan = normalize_plan(plan_raw.get("response", ""))
+        repaired = False
+
+        if not is_valid_plan(plan, selected_budget):
+            repaired = True
+            repair_prompt = make_plan_repair_prompt(prompt, plan, selected_budget)
+            start = perf_counter()
+            repair_raw = self.client.generate(
+                model=self.config.model,
+                prompt=repair_prompt,
+                temperature=0.1,
+                top_p=self.config.top_p,
+                max_tokens=selected_budget + 8,
+                think=self.config.think,
+            )
+            plan_ms += (perf_counter() - start) * 1000
+            repaired_plan = normalize_plan(repair_raw.get("response", ""))
+            if is_valid_plan(repaired_plan, selected_budget):
+                plan = repaired_plan
+            else:
+                plan = "g:solve;c:constraints;s:direct_reasoning;r:verify_output"
+
+        answer_prompt = make_answer_prompt(prompt, plan)
+        start = perf_counter()
+        answer_raw = self.client.generate(
+            model=self.config.model,
+            prompt=answer_prompt,
+            temperature=self.config.temperature,
+            top_p=self.config.top_p,
+            max_tokens=768,
+            think=self.config.think,
+        )
+        answer_ms = (perf_counter() - start) * 1000
+
+        return QuickThinkResult(
+            answer=answer_raw.get("response", "").strip(),
+            plan=plan,
+            mode="two_pass",
+            bypassed=False,
+            route_score=route_score,
+            selected_plan_budget=selected_budget,
+            plan_repaired=repaired,
+            plan_latency_ms=plan_ms,
+            answer_latency_ms=answer_ms,
+        )

quickthink/inline_protocol.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import re
+
+from .plan_grammar import normalize_plan
+
+_INLINE_RE = re.compile(r"\[P\](.*?)\[A\](.*)", re.DOTALL)
+
+
+def extract_plan_and_answer(raw: str) -> tuple[str | None, str]:
+    text = raw.strip()
+    match = _INLINE_RE.search(text)
+    if not match:
+        return None, text
+
+    plan = normalize_plan(match.group(1))
+    answer = match.group(2).strip()
+    return plan, answer

quickthink/ollama_client.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+class OllamaClient:
+    def __init__(self, base_url: str, timeout_s: float = 180.0) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.timeout_s = timeout_s
+
+    def generate(
+        self,
+        *,
+        model: str,
+        prompt: str,
+        temperature: float,
+        top_p: float,
+        max_tokens: int,
+        think: bool | str | None = None,
+    ) -> dict[str, Any]:
+        payload = {
+            "model": model,
+            "prompt": prompt,
+            "stream": False,
+            "options": {
+                "temperature": temperature,
+                "top_p": top_p,
+                "num_predict": max_tokens,
+            },
+        }
+        if think is not None:
+            payload["think"] = think
+        with httpx.Client(timeout=self.timeout_s) as client:
+            response = client.post(f"{self.base_url}/api/generate", json=payload)
+            response.raise_for_status()
+            return response.json()

quickthink/plan_grammar.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import re
+
+_PLAN_RE = re.compile(
+    r"^g:([a-z0-9_,-]{1,64});c:([a-z0-9_,-]{1,64});s:([a-z0-9_,-]{1,64});r:([a-z0-9_,-]{1,64})$"
+)
+_TOKEN_RE = re.compile(r"[a-z0-9_]+")
+
+
+def estimate_plan_tokens(plan: str) -> int:
+    return len(_TOKEN_RE.findall(plan.lower()))
+
+
+def normalize_plan(raw: str) -> str:
+    line = raw.strip().splitlines()[0] if raw.strip() else ""
+    return line.strip().lower().replace(" ", "")
+
+
+def is_valid_plan(plan: str, budget_tokens: int) -> bool:
+    normalized = normalize_plan(plan)
+    if not _PLAN_RE.match(normalized):
+        return False
+    return estimate_plan_tokens(normalized) <= budget_tokens

quickthink/prompts.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+
+def make_plan_prompt(user_prompt: str, budget: int) -> str:
+    return (
+        "You are a compressed planning module. Produce only one ultra-compact plan line.\n"
+        "Rules:\n"
+        f"- Max keyword tokens: {budget}\n"
+        "- Lowercase only\n"
+        "- No spaces\n"
+        "- No prose\n"
+        "- No markdown\n"
+        "- Exactly this format and key order: g:<...>;c:<...>;s:<...>;r:<...>\n"
+        "- Use slugs with [a-z0-9_,-]\n\n"
+        f"User task:\n{user_prompt}\n"
+    )
+
+
+def make_answer_prompt(user_prompt: str, plan: str) -> str:
+    return (
+        "You are an assistant. Use the compact plan internally and answer directly.\n"
+        "Do not reveal internal planning.\n"
+        "Return only the final answer.\n\n"
+        f"Internal plan:\n{plan}\n\n"
+        f"User task:\n{user_prompt}\n"
+    )
+
+
+def make_plan_repair_prompt(user_prompt: str, bad_plan: str, budget: int) -> str:
+    return (
+        "Repair the plan to valid compact grammar. Return one line only.\n"
+        f"Budget: {budget} keyword tokens max.\n"
+        "Required format: g:<...>;c:<...>;s:<...>;r:<...>\n"
+        "Rules: lowercase, no spaces, keys in exact order, [a-z0-9_,-] only.\n\n"
+        f"User task:\n{user_prompt}\n\n"
+        f"Invalid plan:\n{bad_plan}\n"
+    )
+
+
+def make_inline_plan_answer_prompt(
+    user_prompt: str,
+    budget: int,
+    continuity_hint: str | None = None,
+    scaffold_rules: str | None = None,
+) -> str:
+    hint_line = ""
+    if continuity_hint:
+        hint_line = (
+            "Optional continuity hint is provided below. Use it only if clearly useful.\n"
+            f"Hint: {continuity_hint}\n"
+        )
+    rules_line = ""
+    if scaffold_rules:
+        rules_line = f"Additional scaffold rules:\n- {scaffold_rules}\n"
+    return (
+        "Generate a compact internal plan prefix and then the answer in one response.\n"
+        "Output format must be exactly:\n"
+        "[P]g:<...>;c:<...>;s:<...>;r:<...>\n"
+        "[A]<final answer text>\n"
+        "Rules for [P]:\n"
+        f"- max keyword tokens: {budget}\n"
+        "- lowercase\n"
+        "- no spaces\n"
+        "- grammar keys in order: g,c,s,r\n"
+        "- chars allowed: [a-z0-9_,-:;]\n"
+        "Rules for [A]:\n"
+        "- direct final answer\n"
+        "- do not mention internal planning\n"
+        "- no extra section headers\n"
+        f"{rules_line}"
+        f"{hint_line}\n"
+        f"User task:\n{user_prompt}\n"
+    )