conversation-analyser 0.1.0__tar.gz

conversation_analyser-0.1.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: conversation-analyser
+Version: 0.1.0
+Summary: Critical-thinking and analytics for human-AI conversations — a member of the lens analyser family.
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.109.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyspellchecker>=0.8
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: rich>=13.7.0
+Requires-Dist: textstat>=0.7
+Requires-Dist: uvicorn[standard]>=0.27.0
+Requires-Dist: vadersentiment>=3.3
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: embeddings
+Requires-Dist: numpy>=1.24; extra == 'embeddings'
+Requires-Dist: sentence-transformers>=2.2; extra == 'embeddings'
+Provides-Extra: llm
+Requires-Dist: anthropic>=0.39; extra == 'llm'
+Description-Content-Type: text/markdown
+
+# conversation-analyser
+
+Critical-thinking and analytics for human–AI conversations — a member of the
+[`lens`](../) analyser family.
+
+It scores a single conversation on two tiers:
+
+1. **Analytics** (always on, offline): turn/word counts, prompt/response lengths,
+   question ratio, pushback hits, readability, sentiment trajectory, prompt
+   self-similarity, and temporal metrics when timestamps are present.
+2. **Critical thinking** (opt-in, needs an LLM): classifies every human turn under
+   a 7-label prompt taxonomy, derives engagement ratios, an engagement **band**,
+   and a composite **0–100 critical-thinking score** with a component breakdown.
+
+The taxonomy reuses the validated `NQ/FU/CH/EX/DG/AC/MT` scheme from the ISYS6020
+marking pipeline (copied and forked). Design: `docs/superpowers/specs/2026-05-23-conversation-analyser-design.md`.
+
+## Install
+
+```bash
+pip install -e .                       # core: analytics + CLI + HTTP API
+pip install -e '.[embeddings]'         # + prompt self-similarity (sentence-transformers)
+pip install -e '.[llm]'                # + taxonomy/CT tier (anthropic)
+pip install -e '.[embeddings,llm,dev]' # everything
+export ANTHROPIC_API_KEY=...           # required for the critical-thinking tier
+```
+
+## CLI
+
+Bare positional path to analyse (human summary by default, `--json` for machines);
+`serve` subcommand for the HTTP API — same grammar as the rest of the family.
+
+```bash
+conversation-analyser transcript.txt              # human summary, analytics only
+conversation-analyser chat.json --json            # full JSON to stdout
+conversation-analyser chat.json --llm             # add the critical-thinking tier
+conversation-analyser log.json --idle-gap 45      # split sub-sessions on 45-min gaps
+conversation-analyser raw.txt --parse-mode llm-segment --llm
+conversation-analyser serve --port 8009           # run the HTTP API
+```
+
+The critical-thinking tier is **opt-in** (`--llm`) to avoid surprise API costs;
+without it you get the analytics tier only.
+
+## HTTP API
+
+```bash
+conversation-analyser serve --port 8009
+curl -F file=@chat.json 'http://127.0.0.1:8009/analyse'        # analytics only
+curl -F file=@chat.json -F llm=true 'http://127.0.0.1:8009/analyse'
+curl http://127.0.0.1:8009/health
+```
+
+`GET /health` and `POST /analyse` (multipart file upload, optional `llm` form
+field) — the same `/analyse` contract auto-analyser routes to.
+
+## Python API
+
+```python
+from conversation_analyser import ConversationAnalyser
+
+result = ConversationAnalyser().analyse("transcript.txt", llm=True)
+print(result.model_dump_json(indent=2))
+```
+
+## Input formats
+
+A pluggable adapter registry tries, in order: structured adapters → heuristic
+speaker markers → optional LLM segmentation → unsegmented fallback.
+
+- **role/content** message list (OpenAI/Anthropic): `[{"role": "user", "content": "..."}, ...]`
+- **AnythingLLM** rows: `[{"prompt": "...", "response": "...", "createdAt": ...}, ...]`
+- **flat text** with speaker markers: `User:` / `Assistant:` / `Me:` / `ChatGPT:` /
+  `You said:` / `ChatGPT said:` / `Prompt:` / `Response:`
+- anything else → LLM-segment (needs `[llm]`), else a single-blob fallback
+
+`.pdf`/`.docx` inputs are text-extracted first (needs `pdfplumber`/`markitdown`,
+or pre-extract with `document-analyser`).
+
+## The taxonomy
+
+| Code | Meaning |
+|---|---|
+| `NQ` | New Query — opens a new topic |
+| `FU` | Follow-up — clarification/elaboration |
+| `CH` | Challenge — pushes back, tests, asks why |
+| `EX` | Extension — applies/compares/synthesises in a new direction |
+| `DG` | Delegation — task hand-off, no engagement |
+| `AC` | Acknowledgement — thanks/confirmation |
+| `MT` | Meta — about the conversation itself |
+
+`critical_thinking = (CH+EX)/turns`, `delegation = DG/turns`, `filler = (AC+MT)/turns`.
+Bands: One-Shot · Delegator · Directed · Iterative · Critical.
+
+## Graceful degradation
+
+| Missing | Effect |
+|---|---|
+| `ANTHROPIC_API_KEY` / `[llm]` | `taxonomy`/`critical_thinking` null; analytics still produced; note `llm_unavailable` |
+| `[embeddings]` | `prompt_self_similarity` null; note `embeddings_unavailable` |
+| timestamps | temporal metrics omitted; no sub-session split; note `no timestamps` |
+
+## Output
+
+`ConversationAnalysis` → an `aggregate` (rolled up over all human turns, the
+headline) plus one `SessionAnalysis` per idle-gap sub-session, each with
+`analytics`, `taxonomy`, `critical_thinking`, and per-turn `turns` (label +
+rationale + preview). See the design spec §8 for the full schema.
+
+## Testing
+
+```bash
+pytest                    # fast, deterministic (LLM mocked, no network)
+pytest -m slow            # includes sentence-transformers model download
+pytest -m integration     # includes live LLM calls
+```

conversation_analyser-0.1.0/README.md

@@ -0,0 +1,116 @@
+# conversation-analyser
+
+Critical-thinking and analytics for human–AI conversations — a member of the
+[`lens`](../) analyser family.
+
+It scores a single conversation on two tiers:
+
+1. **Analytics** (always on, offline): turn/word counts, prompt/response lengths,
+   question ratio, pushback hits, readability, sentiment trajectory, prompt
+   self-similarity, and temporal metrics when timestamps are present.
+2. **Critical thinking** (opt-in, needs an LLM): classifies every human turn under
+   a 7-label prompt taxonomy, derives engagement ratios, an engagement **band**,
+   and a composite **0–100 critical-thinking score** with a component breakdown.
+
+The taxonomy reuses the validated `NQ/FU/CH/EX/DG/AC/MT` scheme from the ISYS6020
+marking pipeline (copied and forked). Design: `docs/superpowers/specs/2026-05-23-conversation-analyser-design.md`.
+
+## Install
+
+```bash
+pip install -e .                       # core: analytics + CLI + HTTP API
+pip install -e '.[embeddings]'         # + prompt self-similarity (sentence-transformers)
+pip install -e '.[llm]'                # + taxonomy/CT tier (anthropic)
+pip install -e '.[embeddings,llm,dev]' # everything
+export ANTHROPIC_API_KEY=...           # required for the critical-thinking tier
+```
+
+## CLI
+
+Bare positional path to analyse (human summary by default, `--json` for machines);
+`serve` subcommand for the HTTP API — same grammar as the rest of the family.
+
+```bash
+conversation-analyser transcript.txt              # human summary, analytics only
+conversation-analyser chat.json --json            # full JSON to stdout
+conversation-analyser chat.json --llm             # add the critical-thinking tier
+conversation-analyser log.json --idle-gap 45      # split sub-sessions on 45-min gaps
+conversation-analyser raw.txt --parse-mode llm-segment --llm
+conversation-analyser serve --port 8009           # run the HTTP API
+```
+
+The critical-thinking tier is **opt-in** (`--llm`) to avoid surprise API costs;
+without it you get the analytics tier only.
+
+## HTTP API
+
+```bash
+conversation-analyser serve --port 8009
+curl -F file=@chat.json 'http://127.0.0.1:8009/analyse'        # analytics only
+curl -F file=@chat.json -F llm=true 'http://127.0.0.1:8009/analyse'
+curl http://127.0.0.1:8009/health
+```
+
+`GET /health` and `POST /analyse` (multipart file upload, optional `llm` form
+field) — the same `/analyse` contract auto-analyser routes to.
+
+## Python API
+
+```python
+from conversation_analyser import ConversationAnalyser
+
+result = ConversationAnalyser().analyse("transcript.txt", llm=True)
+print(result.model_dump_json(indent=2))
+```
+
+## Input formats
+
+A pluggable adapter registry tries, in order: structured adapters → heuristic
+speaker markers → optional LLM segmentation → unsegmented fallback.
+
+- **role/content** message list (OpenAI/Anthropic): `[{"role": "user", "content": "..."}, ...]`
+- **AnythingLLM** rows: `[{"prompt": "...", "response": "...", "createdAt": ...}, ...]`
+- **flat text** with speaker markers: `User:` / `Assistant:` / `Me:` / `ChatGPT:` /
+  `You said:` / `ChatGPT said:` / `Prompt:` / `Response:`
+- anything else → LLM-segment (needs `[llm]`), else a single-blob fallback
+
+`.pdf`/`.docx` inputs are text-extracted first (needs `pdfplumber`/`markitdown`,
+or pre-extract with `document-analyser`).
+
+## The taxonomy
+
+| Code | Meaning |
+|---|---|
+| `NQ` | New Query — opens a new topic |
+| `FU` | Follow-up — clarification/elaboration |
+| `CH` | Challenge — pushes back, tests, asks why |
+| `EX` | Extension — applies/compares/synthesises in a new direction |
+| `DG` | Delegation — task hand-off, no engagement |
+| `AC` | Acknowledgement — thanks/confirmation |
+| `MT` | Meta — about the conversation itself |
+
+`critical_thinking = (CH+EX)/turns`, `delegation = DG/turns`, `filler = (AC+MT)/turns`.
+Bands: One-Shot · Delegator · Directed · Iterative · Critical.
+
+## Graceful degradation
+
+| Missing | Effect |
+|---|---|
+| `ANTHROPIC_API_KEY` / `[llm]` | `taxonomy`/`critical_thinking` null; analytics still produced; note `llm_unavailable` |
+| `[embeddings]` | `prompt_self_similarity` null; note `embeddings_unavailable` |
+| timestamps | temporal metrics omitted; no sub-session split; note `no timestamps` |
+
+## Output
+
+`ConversationAnalysis` → an `aggregate` (rolled up over all human turns, the
+headline) plus one `SessionAnalysis` per idle-gap sub-session, each with
+`analytics`, `taxonomy`, `critical_thinking`, and per-turn `turns` (label +
+rationale + preview). See the design spec §8 for the full schema.
+
+## Testing
+
+```bash
+pytest                    # fast, deterministic (LLM mocked, no network)
+pytest -m slow            # includes sentence-transformers model download
+pytest -m integration     # includes live LLM calls
+```

conversation_analyser-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "conversation-analyser"
+version = "0.1.0"
+description = "Critical-thinking and analytics for human-AI conversations — a member of the lens analyser family."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "pydantic>=2.0",
+    "textstat>=0.7",
+    "vaderSentiment>=3.3",
+    "pyspellchecker>=0.8",
+    "fastapi>=0.109.0",
+    "uvicorn[standard]>=0.27.0",
+    "python-multipart>=0.0.9",
+    "rich>=13.7.0",
+]
+
+[project.optional-dependencies]
+embeddings = ["sentence-transformers>=2.2", "numpy>=1.24"]
+llm = ["anthropic>=0.39"]
+dev = ["pytest>=8.0", "httpx>=0.27.0"]
+
+[project.scripts]
+conversation-analyser = "conversation_analyser.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/conversation_analyser"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "-m 'not slow and not integration'"
+markers = [
+    "slow: loads real models (sentence-transformers) or downloads weights — opt-in with -m slow",
+    "integration: makes live LLM calls — opt-in with -m integration",
+]

conversation_analyser-0.1.0/src/conversation_analyser/__init__.py

@@ -0,0 +1,16 @@
+"""conversation-analyser: critical-thinking + analytics for human-AI conversations.
+
+Public API:
+
+    from conversation_analyser import ConversationAnalyser, ConversationAnalysis
+
+    result = ConversationAnalyser().analyse("transcript.txt")
+    print(result.model_dump_json(indent=2))
+"""
+from __future__ import annotations
+
+from .manifest import MANIFEST
+from .models import ConversationAnalysis
+from .pipeline import ConversationAnalyser
+
+__all__ = ["ConversationAnalyser", "ConversationAnalysis", "MANIFEST"]

conversation_analyser-0.1.0/src/conversation_analyser/analytics.py

@@ -0,0 +1,127 @@
+"""Domain-neutral analytics tier (design spec §7).
+
+All metrics derive deterministically from a session's turns. Optional/heavy
+metrics (self-similarity) degrade to None when their dependency is absent; the
+pipeline records a single note. Sentiment/readability/typo use the light core
+deps and are wrapped defensively.
+"""
+from __future__ import annotations
+
+import re
+from collections import Counter
+from statistics import fmean
+
+from . import embeddings
+from .models import AnalyticsMetrics
+from .parsers.base import ParsedTurn
+
+# Pushback cue regex, ported verbatim from marking_pipeline/transcript.py.
+_PUSHBACK_RE = re.compile(
+    r"\b(no,|actually|but\b|wait\b|are you sure|that's wrong|incorrect|"
+    r"i disagree|not right|you're wrong|why\b|why is|why does)\b",
+    re.IGNORECASE,
+)
+_WORD_RE = re.compile(r"\w+")
+
+
+def _words(text: str) -> int:
+    return len(_WORD_RE.findall(text or ""))
+
+
+def pushback_count(human_turns: list[ParsedTurn]) -> int:
+    return sum(len(_PUSHBACK_RE.findall(t.content)) for t in human_turns)
+
+
+def _question_ratio(prompts: list[str]) -> float:
+    if not prompts:
+        return 0.0
+    asked = sum(1 for p in prompts if "?" in p)
+    return round(asked / len(prompts), 2)
+
+
+def _flesch(text: str) -> float | None:
+    if not text.strip():
+        return None
+    try:
+        import textstat
+
+        return round(float(textstat.flesch_reading_ease(text)), 1)
+    except Exception:
+        return None
+
+
+def _typo_rate(prompts: list[str]) -> float | None:
+    try:
+        from spellchecker import SpellChecker
+    except Exception:
+        return None
+    checker = SpellChecker()
+    rates: list[float] = []
+    for p in prompts:
+        words = [w.lower() for w in _WORD_RE.findall(p) if w.isalpha()]
+        if not words:
+            continue
+        unknown = checker.unknown(words)
+        rates.append(len(unknown) / len(words))
+    return round(fmean(rates), 3) if rates else None
+
+
+def _sentiment(prompts: list[str]) -> tuple[float | None, float | None, float | None]:
+    if not prompts:
+        return None, None, None
+    try:
+        from vaderSentiment.vaderSentiment import SentimentIntensityAnalyzer
+    except Exception:
+        return None, None, None
+    analyzer = SentimentIntensityAnalyzer()
+    start = round(analyzer.polarity_scores(prompts[0])["compound"], 3)
+    end = round(analyzer.polarity_scores(prompts[-1])["compound"], 3)
+    return start, end, round(end - start, 3)
+
+
+def _temporal(turns: list[ParsedTurn]) -> tuple[float | None, int | None, int | None]:
+    stamps = [t.timestamp for t in turns if t.timestamp is not None]
+    if len(stamps) < 2:
+        return None, None, None
+    duration = (max(stamps) - min(stamps)).total_seconds() / 60.0
+    hour_mode = Counter(s.hour for s in stamps).most_common(1)[0][0]
+    weekday_mode = Counter(s.weekday() for s in stamps).most_common(1)[0][0]
+    return round(duration, 1), hour_mode, weekday_mode
+
+
+def compute_analytics(turns: list[ParsedTurn], *, with_embeddings: bool = True) -> AnalyticsMetrics:
+    human = [t for t in turns if t.role == "human"]
+    assistant = [t for t in turns if t.role == "assistant"]
+    prompts = [t.content for t in human]
+    responses = [t.content for t in assistant]
+
+    prompt_words = [_words(p) for p in prompts]
+    response_words = [_words(r) for r in responses]
+
+    similarity = None
+    if with_embeddings and embeddings.available():
+        similarity = embeddings.mean_self_similarity(prompts)
+
+    sent_start, sent_end, sent_delta = _sentiment(prompts)
+    duration_min, hour_mode, weekday_mode = _temporal(turns)
+
+    return AnalyticsMetrics(
+        turn_count=len(turns),
+        human_turn_count=len(human),
+        assistant_turn_count=len(assistant),
+        total_words=sum(prompt_words) + sum(response_words),
+        mean_prompt_len=round(fmean(prompt_words), 2) if prompt_words else 0.0,
+        max_prompt_len=max(prompt_words) if prompt_words else 0,
+        mean_response_len=round(fmean(response_words), 2) if response_words else 0.0,
+        question_ratio=_question_ratio(prompts),
+        pushback_count=pushback_count(human),
+        prompt_self_similarity=similarity,
+        flesch_reading_ease=_flesch("\n\n".join(prompts)),
+        mean_typo_rate=_typo_rate(prompts),
+        sentiment_start=sent_start,
+        sentiment_end=sent_end,
+        sentiment_delta=sent_delta,
+        duration_min=duration_min,
+        hour_of_day_mode=hour_mode,
+        weekday_mode=weekday_mode,
+    )

conversation_analyser-0.1.0/src/conversation_analyser/api.py

@@ -0,0 +1,62 @@
+"""FastAPI app for conversation-analyser, mirroring the lens family contract.
+
+Module-level `app` so the CLI can launch it with
+`uvicorn.run("conversation_analyser.api:app", ...)` and tests can drive it with
+fastapi.testclient.TestClient. Endpoints: GET /health, POST /analyse (file upload).
+"""
+from __future__ import annotations
+
+import tempfile
+import time
+from importlib.metadata import version
+from pathlib import Path
+
+from fastapi import FastAPI, File, Form, HTTPException, UploadFile
+
+from .manifest import MANIFEST
+from .models import ConversationAnalysis
+from .pipeline import ConversationAnalyser
+
+_start_time = time.time()
+
+app = FastAPI(title="conversation-analyser", version=version("conversation-analyser"))
+
+_analyser = ConversationAnalyser()
+
+
+@app.get("/health")
+def health() -> dict:
+    return {
+        "status": "ok",
+        "uptime": round(time.time() - _start_time, 1),
+        "version": version("conversation-analyser"),
+    }
+
+
+@app.get("/manifest")
+def manifest() -> dict:
+    return MANIFEST
+
+
+@app.post("/analyse", response_model=ConversationAnalysis)
+async def analyse(
+    file: UploadFile = File(...),
+    llm: bool = Form(False),
+) -> ConversationAnalysis:
+    content = await file.read()
+    if not content:
+        raise HTTPException(status_code=422, detail="Empty file")
+
+    suffix = Path(file.filename or "upload.txt").suffix or ".txt"
+    with tempfile.NamedTemporaryFile(suffix=suffix, delete=False) as tmp:
+        tmp_path = Path(tmp.name)
+        tmp.write(content)
+
+    try:
+        return _analyser.analyse(tmp_path, llm=llm, input_label=file.filename or "<upload>")
+    except ValueError as e:
+        raise HTTPException(status_code=422, detail=str(e)) from e
+    except Exception as e:  # noqa: BLE001
+        raise HTTPException(status_code=500, detail=str(e)) from e
+    finally:
+        tmp_path.unlink(missing_ok=True)

conversation_analyser-0.1.0/src/conversation_analyser/cli.py

@@ -0,0 +1,129 @@
+"""CLI entry point following the lens family pattern.
+
+    conversation-analyser <path> [--json] [--llm] [...]   # analyse (default)
+    conversation-analyser serve [--host H] [--port P]      # run the HTTP API
+
+Human-readable summary by default; `--json` emits the full ConversationAnalysis
+to stdout (this is what auto-analyser consumes). Diagnostics go to stderr.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from .config import DEFAULT_PORT, IDLE_GAP_MIN
+from .manifest import MANIFEST
+from .models import ConversationAnalysis
+from .pipeline import ConversationAnalyser
+
+
+def main() -> None:
+    if len(sys.argv) > 1 and sys.argv[1] == "serve":
+        _serve(sys.argv[2:])
+        return
+
+    if len(sys.argv) > 1 and sys.argv[1] == "manifest":
+        print(json.dumps(MANIFEST, indent=2))
+        return
+
+    parser = argparse.ArgumentParser(
+        prog="conversation-analyser",
+        description="Analyse a human-AI conversation: analytics + critical-thinking taxonomy.",
+    )
+    parser.add_argument("file", type=Path, help="conversation file (.json/.txt/.md/.pdf)")
+    parser.add_argument("--json", action="store_true", dest="as_json", help="JSON output")
+    parser.add_argument("--llm", action="store_true", help="add the taxonomy/critical-thinking tier (needs [llm] + ANTHROPIC_API_KEY)")
+    parser.add_argument("--no-embeddings", action="store_true", help="skip prompt self-similarity")
+    parser.add_argument(
+        "--parse-mode",
+        choices=("auto", "structured", "heuristic", "llm-segment"),
+        default="auto",
+    )
+    parser.add_argument("--idle-gap", type=float, default=IDLE_GAP_MIN, help="sub-session split (minutes)")
+    args = parser.parse_args()
+
+    if not args.file.exists():
+        print(f"Error: file not found: {args.file}", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        result = ConversationAnalyser(idle_gap_min=args.idle_gap).analyse(
+            args.file,
+            llm=args.llm,
+            with_embeddings=not args.no_embeddings,
+            parse_mode=args.parse_mode,
+        )
+    except ValueError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:  # noqa: BLE001
+        print(f"Analysis failed: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    if args.as_json:
+        print(result.model_dump_json(indent=2))
+        return
+
+    _print_human(result)
+
+
+def _print_human(result: ConversationAnalysis) -> None:
+    from rich.console import Console
+    from rich.table import Table
+
+    console = Console(file=sys.stdout)
+    agg = result.aggregate
+    a = agg.analytics
+
+    console.print(
+        f"[bold]Input:[/bold] {result.input}  "
+        f"[bold]Format:[/bold] {result.format_detected} ({result.parse_mode})  "
+        f"[bold]Sessions:[/bold] {result.session_count}  "
+        f"[bold]LLM:[/bold] {'yes' if result.llm_used else 'no'}"
+    )
+    console.print(
+        f"[bold]Turns:[/bold] {a.turn_count} "
+        f"(human {a.human_turn_count}, ai {a.assistant_turn_count})  "
+        f"[bold]Words:[/bold] {a.total_words}  "
+        f"[bold]Questions:[/bold] {a.question_ratio:.0%}  "
+        f"[bold]Pushback:[/bold] {a.pushback_count}"
+    )
+
+    if agg.critical_thinking is not None and agg.taxonomy is not None:
+        ct = agg.critical_thinking
+        console.print(
+            f"[bold]Critical-thinking score:[/bold] {ct.score:.0f}/100  "
+            f"[bold]Band:[/bold] {ct.band}  "
+            f"[bold]Longest engaged chain:[/bold] {agg.taxonomy.longest_engaged_chain}"
+        )
+        table = Table(show_header=True, header_style="bold")
+        for code in agg.taxonomy.label_counts:
+            table.add_column(code, justify="right")
+        table.add_row(*[str(v) for v in agg.taxonomy.label_counts.values()])
+        console.print(table)
+    else:
+        console.print("[dim]Critical-thinking tier skipped (run with --llm).[/dim]")
+
+    if result.notes:
+        console.print(f"[dim]Notes: {', '.join(result.notes)}[/dim]")
+
+
+def _serve(argv: list[str]) -> None:
+    import uvicorn
+
+    parser = argparse.ArgumentParser(prog="conversation-analyser serve")
+    parser.add_argument(
+        "--port", type=int, default=int(os.getenv("CONVERSATION_ANALYSER_PORT", str(DEFAULT_PORT)))
+    )
+    parser.add_argument(
+        "--host", default=os.getenv("CONVERSATION_ANALYSER_HOST", "127.0.0.1")
+    )
+    args = parser.parse_args(argv)
+    uvicorn.run("conversation_analyser.api:app", host=args.host, port=args.port)
+
+
+if __name__ == "__main__":
+    main()