askpanel 0.1.6__py3-none-any.whl

askpanel/__init__.py

@@ -0,0 +1,101 @@
+"""AskPanel — in-app help chat and guided feature requests, grounded in your corpus.
+
+Quickstart::
+
+    from askpanel import AskPanelConfig, create_router
+
+    config = AskPanelConfig(
+        product_name="Orchard",
+        corpus_dir="help/",
+        user_dependency=current_user,
+        on_escalate=save_feedback,
+    )
+    app.include_router(create_router(config), prefix="/api/askpanel")
+"""
+
+from .config import AskPanelConfig
+from .corpus import (
+    DEFAULT_BANNED_WORDS,
+    LintIssue,
+    estimate_tokens,
+    lint_corpus,
+    lint_text,
+    load_corpus,
+    system_blocks,
+)
+from .prompts import DEFAULT_INTERVIEW_AGENDA
+from .protocol import (
+    PROTOCOL_HEADER,
+    PROTOCOL_VERSION,
+    ChatRequest,
+    DeltaFrame,
+    DoneFrame,
+    ErrorFrame,
+    EscalateRequest,
+    EscalationPayload,
+    EscalationResult,
+    Message,
+    StatusOut,
+    SummarizeRequest,
+    SummaryOut,
+    plain_text,
+)
+from .provider import (
+    AnthropicProvider,
+    Provider,
+    ProviderCall,
+    ProviderCheck,
+    ProviderError,
+    StubProvider,
+    Usage,
+)
+from .quota import DailyTurnCap, MemoryCounter
+from .router import QuotaExceeded, call_host, create_router
+from .sinks import github_issue, webhook
+
+__version__ = "0.1.5"
+
+__all__ = [
+    "__version__",
+    "AskPanelConfig",
+    "create_router",
+    "QuotaExceeded",
+    "call_host",
+    # protocol
+    "PROTOCOL_VERSION",
+    "PROTOCOL_HEADER",
+    "Message",
+    "ChatRequest",
+    "SummarizeRequest",
+    "SummaryOut",
+    "EscalateRequest",
+    "EscalationPayload",
+    "EscalationResult",
+    "StatusOut",
+    "DeltaFrame",
+    "DoneFrame",
+    "ErrorFrame",
+    # corpus
+    "load_corpus",
+    "lint_corpus",
+    "lint_text",
+    "LintIssue",
+    "system_blocks",
+    "estimate_tokens",
+    "DEFAULT_BANNED_WORDS",
+    "DEFAULT_INTERVIEW_AGENDA",
+    # providers
+    "Provider",
+    "ProviderCall",
+    "ProviderCheck",
+    "ProviderError",
+    "DailyTurnCap",
+    "MemoryCounter",
+    "plain_text",
+    "AnthropicProvider",
+    "StubProvider",
+    "Usage",
+    # sinks
+    "github_issue",
+    "webhook",
+]

askpanel/cli.py

@@ -0,0 +1,143 @@
+"""``askpanel`` command line: lint a corpus, print the assembled prompt, run the demo."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from . import corpus as corpus_mod
+from . import prompts
+
+
+def _cmd_lint(args: argparse.Namespace) -> int:
+    banned = tuple(args.ban) if args.ban else corpus_mod.DEFAULT_BANNED_WORDS
+    if args.allow:
+        banned = tuple(w for w in banned if w.lower() not in {a.lower() for a in args.allow})
+    try:
+        issues = corpus_mod.lint_corpus(args.dir, banned=banned, min_chars=args.min_chars)
+    except FileNotFoundError as e:
+        print(e, file=sys.stderr)
+        return 2
+    for issue in issues:
+        print(issue)
+    errors = sum(1 for i in issues if i.severity == "error")
+    warnings = len(issues) - errors
+    files = len(corpus_mod.corpus_files(args.dir))
+    print(f"{files} file(s), {errors} error(s), {warnings} warning(s)")
+    return 1 if errors else 0
+
+
+def _cmd_prompt(args: argparse.Namespace) -> int:
+    try:
+        text = corpus_mod.load_corpus(args.dir)
+    except FileNotFoundError as e:
+        print(e, file=sys.stderr)
+        return 2
+    if args.mode == "help":
+        instructions = prompts.help_instructions(args.product)
+    elif args.mode == "interview":
+        instructions = prompts.interview_instructions(args.product)
+    else:
+        instructions = prompts.summarize_instructions(args.product)
+    blocks = corpus_mod.system_blocks(text, args.product, instructions)
+    assembled = corpus_mod.assembled_prompt(blocks)
+    print(assembled)
+    corpus_chars = len(blocks[0]["text"])
+    print(
+        f"\n--- {len(assembled)} characters, ~{corpus_mod.estimate_tokens(assembled)} tokens "
+        f"(cached corpus block: {corpus_chars} characters, "
+        f"~{corpus_mod.estimate_tokens(blocks[0]['text'])} tokens; estimate = chars/4)",
+        file=sys.stderr,
+    )
+    if len(text) < corpus_mod.RECOMMENDED_MIN_CHARS:
+        print(
+            f"warning: corpus is {len(text)} characters; aim above "
+            f"{corpus_mod.RECOMMENDED_MIN_CHARS} so prompt caching engages",
+            file=sys.stderr,
+        )
+    return 0
+
+
+def _find_demo_dir(explicit: str | None) -> Path | None:
+    if explicit:  # an explicit --dir is authoritative; don't fall back to guessing
+        d = Path(explicit)
+        return d if (d / "server.py").is_file() else None
+    candidates: list[Path] = []
+    if os.environ.get("ASKPANEL_DEMO_DIR"):
+        candidates.append(Path(os.environ["ASKPANEL_DEMO_DIR"]))
+    here = Path.cwd()
+    for base in [here, *here.parents]:
+        candidates.append(base / "examples" / "demo")
+    pkg = Path(__file__).resolve()
+    for base in pkg.parents:
+        candidates.append(base / "examples" / "demo")
+    for c in candidates:
+        if (c / "server.py").is_file():
+            return c
+    return None
+
+
+def _cmd_serve_demo(args: argparse.Namespace) -> int:
+    demo = _find_demo_dir(args.dir)
+    if demo is None:
+        print(
+            "Could not find examples/demo/server.py. Run this from a checkout of the "
+            "askpanel repository, pass --dir <path-to-examples/demo>, or set "
+            "ASKPANEL_DEMO_DIR.",
+            file=sys.stderr,
+        )
+        return 2
+    try:
+        import uvicorn
+    except ImportError:
+        print(
+            "uvicorn is not installed. Install with: pip install 'askpanel[demo]'", file=sys.stderr
+        )
+        return 2
+    sys.path.insert(0, str(demo))
+    os.environ.setdefault("ASKPANEL_DEMO_DIR", str(demo))
+    print(f"Serving demo from {demo} on http://{args.host}:{args.port}")
+    if not (demo / "web" / "dist" / "index.html").is_file():
+        print(
+            "note: examples/demo/web/dist is missing; the API works but the page is "
+            "not built. Run `npm install && npm run build` in examples/demo/web.",
+            file=sys.stderr,
+        )
+    uvicorn.run("server:app", host=args.host, port=args.port, reload=False)
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="askpanel", description="AskPanel corpus tools")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    lint = sub.add_parser("lint", help="check a corpus directory; exit 1 on errors")
+    lint.add_argument("dir")
+    lint.add_argument("--ban", action="append", help="replace the banned word list (repeatable)")
+    lint.add_argument("--allow", action="append", help="remove a word from the banned list")
+    lint.add_argument("--min-chars", type=int, default=corpus_mod.RECOMMENDED_MIN_CHARS)
+    lint.set_defaults(func=_cmd_lint)
+
+    prompt = sub.add_parser("prompt", help="print the assembled system prompt and a token estimate")
+    prompt.add_argument("dir")
+    prompt.add_argument("--product", default="the product", help="product name used in the prompt")
+    prompt.add_argument("--mode", choices=["help", "interview", "summarize"], default="help")
+    prompt.set_defaults(func=_cmd_prompt)
+
+    demo = sub.add_parser("serve-demo", help="run the example app (needs uvicorn)")
+    demo.add_argument("--dir", help="path to examples/demo (auto-detected in a checkout)")
+    demo.add_argument("--host", default="127.0.0.1")
+    demo.add_argument("--port", type=int, default=8765)
+    demo.set_defaults(func=_cmd_serve_demo)
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    sys.exit(main())

askpanel/config.py

@@ -0,0 +1,156 @@
+"""``AskPanelConfig`` — every knob of the server side, in one object (SPEC §5)."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Iterable, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from . import corpus as corpus_mod
+from . import prompts
+from .protocol import (
+    DEFAULT_MAX_MESSAGE_CHARS,
+    DEFAULT_MAX_MESSAGES,
+    MAX_CONTEXT_CHARS,
+    MODES,
+)
+from .provider import AnthropicProvider, Provider, Usage, provider_configured
+
+# Host callbacks may be ``async def`` or plain ``def`` (sync ones run in a threadpool).
+OnEscalate = Callable[
+    ..., Awaitable[Any] | Any
+]  # (payload, user[, request]) -> EscalationResult | dict | str | None
+Quota = Callable[..., Awaitable[Any] | Any]  # (user[, mode]) -> bool | str
+OnTurn = Callable[[Any, str, Usage | None], Awaitable[None] | None]
+ContextValidator = Callable[[str], bool]
+
+
+@dataclass
+class AskPanelConfig:
+    """Configuration for ``create_router``. See docs/configuration.md for every option.
+
+    Required: ``product_name``, ``user_dependency``, ``on_escalate``, and one of
+    ``corpus_dir`` / ``corpus_text``.
+    """
+
+    product_name: str
+    user_dependency: Callable[..., Any]
+    on_escalate: OnEscalate
+    corpus_dir: str | Path | None = None
+    corpus_text: str | None = None
+    allowed_contexts: Iterable[str] | None = None
+    context_validator: ContextValidator | None = None
+    provider: Provider | None = None
+    extra_instructions: str = ""
+    interview_agenda: Sequence[str] = prompts.DEFAULT_INTERVIEW_AGENDA
+    interview_max_turns: int = 6
+    max_messages: int = DEFAULT_MAX_MESSAGES
+    max_message_chars: int = DEFAULT_MAX_MESSAGE_CHARS
+    quota: Quota | None = None
+    starters: dict[str, list[str]] = field(default_factory=dict)
+    modes: Iterable[str] = ("help", "interview")
+    on_turn: OnTurn | None = None
+
+    def __post_init__(self) -> None:
+        if not self.product_name or not self.product_name.strip():
+            raise ValueError("product_name is required")
+        if self.corpus_dir is None and self.corpus_text is None:
+            raise ValueError("one of corpus_dir or corpus_text is required")
+        if self.corpus_text is None:
+            self.corpus_text = corpus_mod.load_corpus(self.corpus_dir)  # type: ignore[arg-type]
+        self.corpus_text = self.corpus_text.strip()
+        if self.provider is None:
+            self.provider = AnthropicProvider()
+        bad = [m for m in self.modes if m not in MODES]
+        if bad:
+            raise ValueError(f"unknown modes {bad!r}; valid modes are {list(MODES)}")
+        self.modes = tuple(m for m in MODES if m in set(self.modes))
+        if not self.modes:
+            raise ValueError("at least one mode must be enabled")
+        if self.allowed_contexts is not None:
+            self.allowed_contexts = tuple(self.allowed_contexts)
+        if self.interview_max_turns < 1:
+            raise ValueError("interview_max_turns must be >= 1")
+        if self.max_messages < 1 or self.max_message_chars < 1:
+            raise ValueError("max_messages and max_message_chars must be >= 1")
+        for ctx in self.starters:
+            if len(ctx) > MAX_CONTEXT_CHARS:
+                raise ValueError(f"starters key {ctx!r} exceeds {MAX_CONTEXT_CHARS} chars")
+
+    # -- derived ---------------------------------------------------------------------
+
+    @property
+    def enabled(self) -> bool:
+        """Provider configured AND corpus non-empty. Drives ``/status`` and the 503s.
+
+        "Configured" means credentials are *present*, not valid: no network is touched.
+        Use ``verify()`` at startup to find a revoked key or a wrong model id.
+        """
+        return bool(self.corpus_text) and provider_configured(self.provider)
+
+    def verify(self) -> list[str]:
+        """Check the parts of the configuration that ``enabled`` cannot: an empty corpus,
+        and — when the provider offers ``check()`` — the key and model id, with one
+        free request. Returns a list of problems (empty means everything is fine).
+        Never called by the router; call it at startup, in a health check, or a test."""
+        problems: list[str] = []
+        if not self.corpus_text:
+            problems.append("corpus is empty")
+        if not provider_configured(self.provider):
+            problems.append("provider has no credentials (ANTHROPIC_API_KEY or api_key=)")
+        elif hasattr(self.provider, "check"):
+            result = self.provider.check()
+            if not getattr(result, "ok", False):
+                problems.append(
+                    f"provider check failed for model {getattr(result, 'model', '?')}: "
+                    f"{getattr(result, 'error', 'unknown error')}"
+                )
+        return problems
+
+    def context_ok(self, context: str | None) -> bool:
+        """Is this ``context`` acceptable? ``None`` always is."""
+        if context is None:
+            return True
+        if len(context) > MAX_CONTEXT_CHARS:
+            return False
+        if self.context_validator is not None and not self.context_validator(context):
+            return False
+        if self.allowed_contexts is not None and context not in self.allowed_contexts:
+            return False
+        return True
+
+    def instructions_for(self, mode: str, conversation_mode: str = "interview") -> str:
+        """The instruction block for ``mode`` (``"help"``, ``"interview"``, or
+        ``"summarize"``). For ``"summarize"``, ``conversation_mode`` picks the shape:
+        a question-shaped note for ``"help"``, a request for ``"interview"``."""
+        if mode == "help":
+            return prompts.help_instructions(self.product_name, self.extra_instructions)
+        if mode == "interview":
+            return prompts.interview_instructions(
+                self.product_name,
+                self.interview_agenda,
+                self.interview_max_turns,
+                self.extra_instructions,
+            )
+        if mode == "summarize":
+            return prompts.summarize_instructions(self.product_name, conversation_mode)
+        raise ValueError(f"unknown mode {mode!r}")
+
+    def system_blocks(self, mode: str, conversation_mode: str = "interview") -> list[dict]:
+        """Cached corpus block + instructions for ``mode`` (see ``instructions_for``)."""
+        return corpus_mod.system_blocks(
+            self.corpus_text or "",
+            self.product_name,
+            self.instructions_for(mode, conversation_mode),
+        )
+
+    async def averify(self) -> list[str]:
+        """``verify()`` for async code (a FastAPI lifespan): runs it in a worker thread so
+        the provider round-trip never blocks the event loop."""
+        import asyncio
+
+        return await asyncio.to_thread(self.verify)
+
+
+__all__ = ["AskPanelConfig", "OnEscalate", "Quota", "OnTurn", "ContextValidator"]

askpanel/corpus.py

@@ -0,0 +1,221 @@
+"""Corpus loading, linting, and the cached system block.
+
+The corpus is the feature: a set of markdown files the host writes in its users'
+vocabulary. ``load_corpus`` joins them in filename order; ``lint_corpus`` catches the
+mistakes that make a help assistant confidently wrong; ``system_blocks`` turns the text
+into the cached system prompt prefix, byte-for-byte identical on every call.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from functools import lru_cache
+from pathlib import Path
+
+from . import prompts
+
+CORPUS_SEPARATOR = "\n\n---\n\n"
+CORPUS_GLOB = "*.md"
+
+DEFAULT_BANNED_WORDS: tuple[str, ...] = (
+    "endpoint",
+    "database",
+    "postgres",
+    "jsonb",
+    "migration",
+    "alembic",
+    "api",
+    "backend",
+    "frontend",
+    "deploy",
+    "env var",
+)
+
+#: Below this many characters the assembled prompt is unlikely to reach the provider's
+#: minimum cacheable prefix; the linter warns (does not fail).
+RECOMMENDED_MIN_CHARS = 8000
+
+#: Rough tokens-per-character ratio for English prose. An estimate, not a count.
+CHARS_PER_TOKEN = 4
+
+
+def corpus_files(corpus_dir: str | Path) -> list[Path]:
+    """The markdown files of a corpus directory, sorted by filename."""
+    d = Path(corpus_dir)
+    if not d.is_dir():
+        raise FileNotFoundError(f"corpus directory not found: {d}")
+    return sorted(p for p in d.glob(CORPUS_GLOB) if p.is_file())
+
+
+def load_corpus(corpus_dir: str | Path) -> str:
+    """Read every ``*.md`` in ``corpus_dir`` in filename order, joined by a separator.
+
+    Files are stripped of surrounding whitespace so the result is stable across editors.
+    Returns ``""`` for an empty directory (the module then reports itself disabled).
+    """
+    texts = [p.read_text(encoding="utf-8").strip() for p in corpus_files(corpus_dir)]
+    return CORPUS_SEPARATOR.join(t for t in texts if t)
+
+
+@dataclass(frozen=True)
+class LintIssue:
+    """One finding from ``lint_corpus``. ``severity`` is ``"error"`` or ``"warning"``."""
+
+    file: str
+    line: int  # 1-based; 0 when the finding is about the whole file or corpus
+    message: str
+    severity: str = "error"
+
+    def __str__(self) -> str:
+        where = f"{self.file}:{self.line}" if self.line else self.file
+        return f"{where}: {self.severity}: {self.message}"
+
+
+def _banned_pattern(words: tuple[str, ...] | list[str]) -> re.Pattern[str] | None:
+    words = [w.strip() for w in words if w and w.strip()]
+    if not words:
+        return None
+    alts = [re.escape(w).replace(r"\ ", r"\s+") for w in words]
+    return re.compile(r"(?<![\w-])(" + "|".join(alts) + r")(?![\w-])", re.IGNORECASE)
+
+
+def lint_text(
+    text: str,
+    *,
+    filename: str = "<text>",
+    banned: tuple[str, ...] | list[str] = DEFAULT_BANNED_WORDS,
+) -> list[LintIssue]:
+    """Lint one file's text. Rules:
+
+    - the first non-empty line must be a markdown title (``# ...``)
+    - the file must not be empty
+    - no banned implementation words (whole-word, case-insensitive)
+    """
+    issues: list[LintIssue] = []
+    lines = text.splitlines()
+    first = next(((i, ln) for i, ln in enumerate(lines, start=1) if ln.strip()), None)
+    if first is None:
+        issues.append(LintIssue(filename, 0, "file is empty"))
+        return issues
+    line_no, line = first
+    if not re.match(r"^#\s+\S", line):
+        issues.append(
+            LintIssue(
+                filename,
+                line_no,
+                "first line must be a title (`# What this file is about`)",
+            )
+        )
+    pattern = _banned_pattern(banned)
+    if pattern is not None:
+        for i, ln in enumerate(lines, start=1):
+            for m in pattern.finditer(ln):
+                issues.append(
+                    LintIssue(
+                        filename,
+                        i,
+                        f"banned word {m.group(1)!r}: users don't say this; "
+                        "describe what they see instead",
+                    )
+                )
+    return issues
+
+
+def lint_corpus(
+    corpus_dir: str | Path,
+    *,
+    banned: tuple[str, ...] | list[str] = DEFAULT_BANNED_WORDS,
+    min_chars: int = RECOMMENDED_MIN_CHARS,
+) -> list[LintIssue]:
+    """Lint every file in a corpus directory. Errors mean the corpus should not ship.
+
+    Warnings (``severity == "warning"``): no files at all; total size below
+    ``min_chars`` (prompt caching probably will not engage).
+    """
+    files = corpus_files(corpus_dir)
+    issues: list[LintIssue] = []
+    if not files:
+        return [LintIssue(str(corpus_dir), 0, "no *.md files found", "warning")]
+    total = 0
+    for p in files:
+        text = p.read_text(encoding="utf-8")
+        total += len(text.strip())
+        issues.extend(lint_text(text, filename=p.name, banned=banned))
+    if total < min_chars:
+        issues.append(
+            LintIssue(
+                str(corpus_dir),
+                0,
+                f"corpus is {total} characters; aim above {min_chars} so prompt caching engages",
+                "warning",
+            )
+        )
+    return issues
+
+
+def has_errors(issues: list[LintIssue]) -> bool:
+    return any(i.severity == "error" for i in issues)
+
+
+def estimate_tokens(text: str) -> int:
+    """A rough token estimate (characters / 4). Good enough to see whether caching engages."""
+    return (len(text) + CHARS_PER_TOKEN - 1) // CHARS_PER_TOKEN
+
+
+@lru_cache(maxsize=64)
+def corpus_block_text(corpus_text: str, product_name: str) -> str:
+    """The text of the cached block: preamble + corpus + postamble."""
+    return (
+        prompts.CORPUS_PREAMBLE.format(product_name=product_name)
+        + corpus_text.strip()
+        + prompts.CORPUS_POSTAMBLE
+    )
+
+
+@lru_cache(maxsize=64)
+def _corpus_block(corpus_text: str, product_name: str) -> dict:
+    return {
+        "type": "text",
+        "text": corpus_block_text(corpus_text, product_name),
+        "cache_control": {"type": "ephemeral"},
+    }
+
+
+@lru_cache(maxsize=64)
+def _instructions_block(instructions: str) -> dict:
+    return {"type": "text", "text": instructions}
+
+
+def system_blocks(corpus_text: str, product_name: str, instructions: str) -> list[dict]:
+    """The system prompt as provider blocks.
+
+    Block 0 is the corpus with ``cache_control: ephemeral``; it depends only on the
+    corpus text and product name, so it is byte-identical across help, interview, and
+    summarize requests and across turns. Block 1 is the (uncached) mode instructions.
+    Results are memoised; callers get fresh list copies of the same dict objects and
+    must not mutate them.
+    """
+    return [_corpus_block(corpus_text, product_name), _instructions_block(instructions)]
+
+
+def assembled_prompt(blocks: list[dict]) -> str:
+    """Flatten system blocks to one string (for ``askpanel prompt`` and tests)."""
+    return "\n\n".join(b["text"] for b in blocks)
+
+
+__all__ = [
+    "CORPUS_SEPARATOR",
+    "DEFAULT_BANNED_WORDS",
+    "RECOMMENDED_MIN_CHARS",
+    "LintIssue",
+    "corpus_files",
+    "load_corpus",
+    "lint_text",
+    "lint_corpus",
+    "has_errors",
+    "estimate_tokens",
+    "corpus_block_text",
+    "system_blocks",
+    "assembled_prompt",
+]