askpanel 0.1.6__tar.gz

askpanel-0.1.6/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/
+node_modules/
+.env
+.DS_Store
+coverage/
+.pytest_cache/
+.ruff_cache/
+examples/demo/web/dist/

askpanel-0.1.6/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Paul Gustafson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
+OR OTHER DEALINGS IN THE SOFTWARE.

askpanel-0.1.6/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.5
+Name: askpanel
+Version: 0.1.6
+Summary: In-app help chat and guided feature requests, grounded only in a markdown corpus you write.
+Author: Paul Gustafson
+License: MIT
+License-File: LICENSE
+Keywords: anthropic,chat,fastapi,feedback,help
+Classifier: Framework :: FastAPI
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.11
+Requires-Dist: anthropic>=0.40
+Requires-Dist: fastapi>=0.110
+Requires-Dist: pydantic>=2
+Provides-Extra: demo
+Requires-Dist: uvicorn>=0.23; extra == 'demo'
+Description-Content-Type: text/markdown
+
+# askpanel (Python)
+
+Server half of [AskPanel](https://github.com/pwgustafson/askpanel): a FastAPI router that
+serves in-app help chat and guided feature requests grounded only in a markdown corpus
+you write. See the repository README for the quickstart and `docs/` for configuration,
+the corpus guide, and the wire protocol.
+
+```bash
+pip install askpanel        # or: uv add askpanel
+```
+
+**Why:** as more of a product is built by AI agents, the humans on the team stop being
+able to answer "how does this work" and "what would it take to add that" from memory.
+AskPanel lets the same approach explain the product: an assistant that answers only from
+a short corpus written in your users' words, and turns "it doesn't do that" into a
+structured feature request with the whole conversation attached.

askpanel-0.1.6/README.md

@@ -0,0 +1,16 @@
+# askpanel (Python)
+
+Server half of [AskPanel](https://github.com/pwgustafson/askpanel): a FastAPI router that
+serves in-app help chat and guided feature requests grounded only in a markdown corpus
+you write. See the repository README for the quickstart and `docs/` for configuration,
+the corpus guide, and the wire protocol.
+
+```bash
+pip install askpanel        # or: uv add askpanel
+```
+
+**Why:** as more of a product is built by AI agents, the humans on the team stop being
+able to answer "how does this work" and "what would it take to add that" from memory.
+AskPanel lets the same approach explain the product: an assistant that answers only from
+a short corpus written in your users' words, and turns "it doesn't do that" into a
+structured feature request with the whole conversation attached.

askpanel-0.1.6/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "askpanel"
+version = "0.1.6"
+description = "In-app help chat and guided feature requests, grounded only in a markdown corpus you write."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+authors = [{ name = "Paul Gustafson" }]
+dependencies = [
+  "fastapi>=0.110",
+  "pydantic>=2",
+  "anthropic>=0.40",
+]
+keywords = ["help", "chat", "fastapi", "anthropic", "feedback"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Framework :: FastAPI",
+  "License :: OSI Approved :: MIT License",
+]
+
+[project.optional-dependencies]
+# `askpanel serve-demo` needs an ASGI server.
+demo = ["uvicorn>=0.23"]
+
+[project.scripts]
+askpanel = "askpanel.cli:main"
+
+[dependency-groups]
+dev = [
+  "pytest>=8",
+  "pytest-asyncio>=0.23",
+  "httpx>=0.27",   # Starlette's TestClient transport
+  "ruff>=0.5",
+  "uvicorn>=0.23",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/askpanel"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+asyncio_mode = "strict"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "UP", "B"]

askpanel-0.1.6/src/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-0.1.6/src/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-0.1.6/src/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"]