convolvger 0.1.0__py3-none-any.whl

convolvger/cli/main.py

@@ -0,0 +1,223 @@
+"""Command line interface for Convolvger."""
+
+import re
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from convolvger.core.archive import ArchiveError, load_archive
+from convolvger.core.errors import ConvolvgerError
+from convolvger.core.findings import Finding, Level
+from convolvger.core.results import ParseError, ParseResult
+from convolvger.core.source import RawSource
+from convolvger.providers.default import build_registry
+from convolvger.renderers import render_json, render_markdown
+from convolvger.validation.report import Report
+
+EXIT_OK = 0
+EXIT_FAILED = 1
+EXIT_WARNINGS = 2
+
+FORMATS = ("md", "json")
+FORMAT_HELP = f"Output format ({', '.join(FORMATS)})."
+
+app = typer.Typer(
+    name="convolvger",
+    help="Archive public AI conversations into portable, provider-independent formats.",
+    no_args_is_help=True,
+)
+
+
+def _slug(title: str | None, fallback: str) -> str:
+    base = (title or fallback).lower()
+    base = re.sub(r"[^a-z0-9]+", "-", base).strip("-")
+    return base[:60] or fallback
+
+
+def _warn(message: str) -> None:
+    typer.echo(message, err=True)
+
+
+def _retrieve(source: str) -> tuple[RawSource, ParseResult]:
+    """Detect, fetch, and parse a conversation source."""
+    registry = build_registry()
+    provider = registry.detect(source)
+    raw = provider.fetch(source)
+    return raw, provider.parse(raw)
+
+
+def _report_findings(findings: list[Finding]) -> None:
+    """Report every finding, loudest first.
+
+    Notes are printed as well as warnings: a note does not change the
+    exit status, but it is still something the snapshot did not carry
+    and the operator should be able to see it.
+    """
+    if not findings:
+        return
+    warnings = [item for item in findings if item.level is Level.WARNING]
+    notes = [item for item in findings if item.level is Level.NOTE]
+    counts = [
+        f"{len(group)} {label}"
+        for group, label in ((warnings, "warning(s)"), (notes, "note(s)"))
+        if group
+    ]
+    _warn(f"\n{', '.join(counts)}:")
+    for item in warnings + notes:
+        where = f" ({item.message_id})" if item.message_id else ""
+        _warn(f"  - [{item.level.value}] {item.code}{where}: {item.message}")
+
+
+def _fail(error: Exception) -> None:
+    _warn(f"Error: {error}")
+    if isinstance(error, ParseError) and error.findings:
+        _report_findings(error.findings)
+    raise typer.Exit(EXIT_FAILED)
+
+
+@app.command()
+def providers() -> None:
+    """List supported conversation providers."""
+    for name in build_registry().names():
+        typer.echo(name)
+
+
+@app.command()
+def inspect(
+    source: Annotated[
+        str,
+        typer.Argument(help="Public conversation URL or local conversation source."),
+    ],
+) -> None:
+    """Inspect a conversation source without exporting it."""
+    try:
+        _, result = _retrieve(source)
+    except ConvolvgerError as error:
+        _fail(error)
+        return
+
+    conversation = result.conversation
+    typer.echo(f"Title:     {conversation.title or '(untitled)'}")
+    typer.echo(f"Provider:  {conversation.provider}")
+    typer.echo(f"Messages:  {len(conversation.messages)}")
+    typer.echo(f"Visible:   {sum(m.visible for m in conversation.messages)}")
+    typer.echo(f"Active:    {sum(m.active for m in conversation.messages)}")
+    typer.echo(f"Blocks:    {sum(len(m.content) for m in conversation.messages)}")
+
+    _report_findings(result.findings)
+    raise typer.Exit(EXIT_WARNINGS if result.warned else EXIT_OK)
+
+
+@app.command()
+def export(
+    source: Annotated[
+        str,
+        typer.Argument(help="Public conversation URL or local conversation source."),
+    ],
+    output: Annotated[
+        Path | None,
+        typer.Option("--output", "-o", help="Output path, or - for stdout."),
+    ] = None,
+    output_format: Annotated[
+        str,
+        typer.Option("--format", "-f", help=FORMAT_HELP),
+    ] = "md",
+    include_hidden: Annotated[
+        bool,
+        typer.Option("--include-hidden", help="Include provider-hidden messages."),
+    ] = False,
+    include_inactive: Annotated[
+        bool,
+        typer.Option("--include-inactive", help="Include deactivated branches."),
+    ] = False,
+) -> None:
+    """Export a conversation to a portable archive."""
+    if output_format not in FORMATS:
+        _warn(f"Error: unsupported format: {output_format}")
+        _warn(f"Supported formats: {', '.join(FORMATS)}")
+        raise typer.Exit(EXIT_FAILED)
+
+    try:
+        raw, result = _retrieve(source)
+    except ConvolvgerError as error:
+        _fail(error)
+        return
+
+    if output_format == "json":
+        if include_hidden or include_inactive:
+            _warn("Note: include flags are ignored; JSON keeps every message.")
+        rendered = render_json(
+            result.conversation,
+            findings=result.findings,
+            fetched_at=raw.fetched_at,
+        )
+    else:
+        rendered = render_markdown(
+            result.conversation,
+            include_hidden=include_hidden,
+            include_inactive=include_inactive,
+            findings=result.findings,
+            fetched_at=raw.fetched_at,
+        )
+
+    if output is not None and str(output) == "-":
+        sys.stdout.write(rendered)
+    else:
+        destination = output or Path(
+            f"{_slug(result.conversation.title, result.conversation.provider)}.{output_format}"
+        )
+        destination.write_text(rendered, encoding="utf-8")
+        _warn(f"Wrote {destination}")
+
+    _report_findings(result.findings)
+    raise typer.Exit(EXIT_WARNINGS if result.warned else EXIT_OK)
+
+
+def _yes_no(value: bool) -> str:
+    return "yes" if value else "no"
+
+
+@app.command()
+def verify(
+    archive: Annotated[
+        Path,
+        typer.Argument(help="Path to a JSON archive written by convolvger."),
+    ],
+) -> None:
+    """Report what a JSON archive says about its own integrity.
+
+    The verdict is derived from the findings the archive already
+    carries. Nothing is re-fetched and nothing is re-parsed: this reads
+    a file and reports what it records.
+    """
+    try:
+        envelope = load_archive(archive.read_text(encoding="utf-8"))
+    except (ArchiveError, OSError) as error:
+        _fail(error)
+        return
+
+    report = Report(findings=envelope.findings)
+    conversation = envelope.conversation
+
+    typer.echo(f"Archive:   {archive}")
+    typer.echo(f"Schema:    {envelope.schema_version}")
+    typer.echo(f"Tool:      {envelope.tool} {envelope.tool_version}")
+    if envelope.retrieved_at is not None:
+        typer.echo(f"Retrieved: {envelope.retrieved_at.isoformat()}")
+    typer.echo(f"Provider:  {conversation.provider}")
+    typer.echo(f"Messages:  {len(conversation.messages)}")
+    typer.echo(f"Complete:  {_yes_no(report.complete)}")
+    typer.echo(f"Faithful:  {_yes_no(report.faithful)}")
+    if report.unrecognised:
+        typer.echo(f"Unknown:   {len(report.unrecognised)} unclassifiable code(s)")
+
+    _report_findings(envelope.findings)
+    raise typer.Exit(
+        EXIT_OK if report.complete and report.faithful else EXIT_WARNINGS
+    )
+
+
+if __name__ == "__main__":
+    app()

convolvger/core/__init__.py

@@ -0,0 +1,33 @@
+from convolvger.core.archive import ArchiveEnvelope
+from convolvger.core.errors import ConvolvgerError, ProviderNotFoundError
+from convolvger.core.models import (
+    CodeBlock,
+    ContentBlock,
+    Conversation,
+    KnownBlock,
+    Message,
+    MessageRole,
+    ReasoningBlock,
+    TextBlock,
+    UnknownBlock,
+)
+from convolvger.core.results import ParseError, ParseResult
+from convolvger.core.source import RawSource
+
+__all__ = [
+    "ArchiveEnvelope",
+    "CodeBlock",
+    "ContentBlock",
+    "Conversation",
+    "ConvolvgerError",
+    "KnownBlock",
+    "Message",
+    "MessageRole",
+    "ParseError",
+    "ParseResult",
+    "ProviderNotFoundError",
+    "RawSource",
+    "ReasoningBlock",
+    "TextBlock",
+    "UnknownBlock",
+]

convolvger/core/archive.py

@@ -0,0 +1,106 @@
+"""The archival package produced by the JSON export.
+
+The Markdown renderer is a dissemination package and may omit content.
+This is the archival package: it omits nothing the canonical model holds.
+
+Extraction findings and the retrieval time describe the capture event
+rather than the conversation, so they sit beside the conversation here,
+matching ``ParseResult`` rather than contradicting it. ``conversation``
+alone round-trips back to an equal ``Conversation``.
+"""
+
+import json
+from datetime import datetime
+from importlib.metadata import PackageNotFoundError, version
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+from convolvger.core.errors import ConvolvgerError
+from convolvger.core.findings import Finding
+from convolvger.core.models import Conversation
+
+SCHEMA_VERSION = 2
+"""Bumped only when a change would stop an older reader loading a file.
+
+Version 2 replaced the ``warnings`` list of strings with ``findings``.
+Adding a field is safe for a reader that allows unknown ones; removing
+or renaming one is not.
+"""
+
+
+class ArchiveError(ConvolvgerError):
+    """Raised when a file cannot be read as an archive of this version.
+
+    Lives here rather than in ``errors`` for the same reason
+    ``ParseError`` lives beside the parser: it belongs to the format it
+    guards.
+    """
+
+
+def _tool_version() -> str:
+    try:
+        return version("convolvger")
+    except PackageNotFoundError:
+        return "unknown"
+
+
+class ArchiveEnvelope(BaseModel):
+    """A conversation together with the provenance of its capture.
+
+    ``extra="allow"``, unlike every other model here. An archive is a
+    permanent file that a later version of this tool must be able to
+    read: forbidding unknown fields would make every future addition a
+    breaking change, and ignoring them would drop them on
+    re-serialisation. Allowing them preserves a field this version does
+    not model. The canonical models keep ``forbid`` -- they guard an
+    internal invariant, not a file format.
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    schema_version: int = SCHEMA_VERSION
+    tool: str = "convolvger"
+    tool_version: str = Field(default_factory=_tool_version)
+    retrieved_at: datetime | None = None
+    findings: list[Finding] = Field(default_factory=list)
+    conversation: Conversation
+
+
+def load_archive(text: str) -> ArchiveEnvelope:
+    """Read an archive this version can vouch for, or refuse it.
+
+    The declared schema version is checked before anything else is
+    trusted, because the envelope alone will not refuse a file it cannot
+    truthfully represent. A version 1 archive validates quite happily:
+    its ``warnings`` list survives as an unknown field and ``findings``
+    defaults to empty, so a reader that skipped this check would
+    pronounce a file recording real damage entirely clean. Refusal is
+    the only honest answer for a format this version cannot read as its
+    own.
+
+    Nothing here touches the filesystem. The caller owns reading the
+    file, as it already owns writing one.
+    """
+    try:
+        payload = json.loads(text)
+    except json.JSONDecodeError as error:
+        raise ArchiveError(f"Not JSON: {error}") from error
+
+    if not isinstance(payload, dict):
+        raise ArchiveError(
+            f"Not an archive: expected an object, found {type(payload).__name__}"
+        )
+
+    declared = payload.get("schema_version")
+    if not isinstance(declared, int):
+        raise ArchiveError("Not an archive: no schema_version")
+    if declared != SCHEMA_VERSION:
+        raise ArchiveError(
+            f"Archive declares schema version {declared}; "
+            f"this version reads {SCHEMA_VERSION}"
+        )
+
+    try:
+        return ArchiveEnvelope.model_validate(payload)
+    except ValidationError as error:
+        raise ArchiveError(f"Archive is not a valid envelope: {error}") from error

convolvger/core/errors.py

@@ -0,0 +1,6 @@
+class ConvolvgerError(Exception):
+    """Base class for all Convolvger errors."""
+
+
+class ProviderNotFoundError(ConvolvgerError):
+    """Raised when no provider can handle the requested source."""

convolvger/core/findings.py

@@ -0,0 +1,83 @@
+"""Structured observations recorded during extraction.
+
+A finding is one thing this tool noticed, not a verdict. Each carries a
+stable ``code`` callers can key on without matching prose, and a
+``level`` that decides whether it raises the exit status.
+
+Level governs notification only. Every finding is recorded in the
+archive whatever its level: nothing is ever withheld from the record
+because it was judged unremarkable.
+
+Codes are append-only. Never rename a code and never change what it
+means -- an archive written a year ago keys on the same string, and a
+descriptive name tempts renaming when an interpretation shifts. If the
+meaning changes, add a new code and stop emitting the old one.
+"""
+
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict
+
+
+class Level(StrEnum):
+    """How loudly a finding is reported.
+
+    There is deliberately no ``error``: an unrecoverable problem raises
+    ``ParseError``, and there is then no archive for a finding to sit in.
+    """
+
+    NOTE = "note"
+    WARNING = "warning"
+
+
+LEVELS: dict[str, Level] = {
+    "deferred_slot_not_merged": Level.WARNING,
+    "deferred_value_unresolved": Level.WARNING,
+    "literal_object_key": Level.NOTE,
+    "message_content_withheld": Level.WARNING,
+    "message_has_no_content": Level.NOTE,
+    "message_weight_absent": Level.NOTE,
+    "non_standard_json_constant": Level.WARNING,
+    "unexpected_message_weight": Level.WARNING,
+    "unmodelled_content_type": Level.WARNING,
+    "unrecognised_role": Level.WARNING,
+    "unrecognised_stream_line": Level.WARNING,
+}
+"""The single place a code's severity is decided.
+
+``message_has_no_content`` is a note because a public share snapshot
+omits content by design: OpenAI states that custom instructions are not
+shared with share-link viewers, so empty system messages appear in every
+such conversation. ``message_content_withheld`` is a warning because it
+marks content the snapshot was expected to carry and did not.
+
+``message_weight_absent`` is a note because absence is not damage on
+its own: a snapshot that never carried the field says nothing about
+whether a branch was deactivated. It is recorded rather than assumed
+away so that a provider dropping a field it always sent is visible.
+"""
+
+
+class Finding(BaseModel):
+    """One recorded observation about an extraction."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    code: str
+    level: Level
+    message: str
+    message_id: str | None = None
+
+
+def finding(code: str, message: str, message_id: str | None = None) -> Finding:
+    """Build a finding, taking its level from ``LEVELS``.
+
+    The level is not a parameter: one code must never be emitted at two
+    different severities. It is still written into the output, so a
+    reader does not need this table to interpret an archive.
+    """
+    if code not in LEVELS:
+        raise KeyError(f"Unknown finding code: {code}")
+    return Finding(
+        code=code, level=LEVELS[code], message=message, message_id=message_id
+    )

convolvger/core/models.py

@@ -0,0 +1,107 @@
+from datetime import datetime
+from enum import StrEnum
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class MessageRole(StrEnum):
+    USER = "user"
+    ASSISTANT = "assistant"
+    SYSTEM = "system"
+    TOOL = "tool"
+    UNKNOWN = "unknown"
+
+
+class TextBlock(BaseModel):
+    """Plain prose or Markdown authored by a participant."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: Literal["text"] = "text"
+    text: str
+
+
+class CodeBlock(BaseModel):
+    """Source code, a command, or a tool invocation payload."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: Literal["code"] = "code"
+    text: str
+    language: str | None = None
+
+
+class ReasoningBlock(BaseModel):
+    """A reasoning summary exposed by the provider's public snapshot.
+
+    This is not hidden chain-of-thought. It holds only what the snapshot
+    itself discloses, kept separate from assistant output so renderers
+    never present the two as equivalent.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: Literal["reasoning"] = "reasoning"
+    text: str
+    label: str | None = None
+
+
+class UnknownBlock(BaseModel):
+    """A block whose type this version does not model.
+
+    Unrecognised content is preserved verbatim in ``raw`` rather than
+    dropped, so an archive never loses recoverable content to a provider
+    format that changed after this release.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: str
+    text: str | None = None
+    raw: dict[str, Any] = Field(default_factory=dict)
+
+
+KnownBlock = Annotated[
+    TextBlock | CodeBlock | ReasoningBlock,
+    Field(discriminator="type"),
+]
+
+ContentBlock = Annotated[
+    KnownBlock | UnknownBlock,
+    Field(union_mode="left_to_right"),
+]
+
+
+class Message(BaseModel):
+    """A single turn in a conversation.
+
+    ``provider_metadata`` holds source fields this version does not model
+    canonically, so nothing recoverable is lost. Renderers must not read
+    it; it exists for validation and lossless export only.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    id: str | None = None
+    role: MessageRole
+    author: str | None = None
+    timestamp: datetime | None = None
+    content: list[ContentBlock] = Field(default_factory=list)
+    visible: bool = True
+    active: bool = True
+    status: str | None = None
+    recipient: str | None = None
+    provider_metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class Conversation(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    id: str | None = None
+    provider: str
+    source_url: str
+    title: str | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+    messages: list[Message] = Field(default_factory=list)

convolvger/core/results.py

@@ -0,0 +1,39 @@
+"""Outcome types carrying non-fatal diagnostics alongside parsed data.
+
+Findings are extraction metadata, not conversation content, so they
+travel beside the canonical model rather than inside it. This keeps the
+same source snapshot producing the same ``Conversation`` even as finding
+text evolves between releases.
+"""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from convolvger.core.errors import ConvolvgerError
+from convolvger.core.findings import Finding, Level
+from convolvger.core.models import Conversation
+
+
+class ParseResult(BaseModel):
+    """A parsed conversation plus any non-fatal extraction findings."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    conversation: Conversation
+    findings: list[Finding] = Field(default_factory=list)
+
+    @property
+    def warned(self) -> bool:
+        """True when a finding is severe enough to change the exit status."""
+        return any(item.level is Level.WARNING for item in self.findings)
+
+
+class ParseError(ConvolvgerError):
+    """Raised when a source cannot be parsed into a conversation.
+
+    Carries any findings accumulated before the failure so a caller can
+    still report what was observed.
+    """
+
+    def __init__(self, message: str, findings: list[Finding] | None = None) -> None:
+        super().__init__(message)
+        self.findings = list(findings or [])

convolvger/core/source.py

@@ -0,0 +1,14 @@
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict
+
+
+class RawSource(BaseModel):
+    """Unparsed provider snapshot, before canonicalization."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    url: str
+    content: str
+    content_type: str | None = None
+    fetched_at: datetime | None = None

convolvger/providers/__init__.py

@@ -0,0 +1,7 @@
+from convolvger.providers.base import Provider
+from convolvger.providers.registry import ProviderRegistry
+
+__all__ = [
+    "Provider",
+    "ProviderRegistry",
+]

convolvger/providers/base.py

@@ -0,0 +1,26 @@
+from typing import Protocol
+
+from convolvger.core.results import ParseResult
+from convolvger.core.source import RawSource
+
+
+class Provider(Protocol):
+    """Adapter for one AI provider's public conversation format."""
+
+    name: str
+
+    def matches(self, url: str) -> bool:
+        """Return True if this provider handles the given URL."""
+        ...
+
+    def fetch(self, url: str) -> RawSource:
+        """Retrieve the raw public snapshot for the given URL."""
+        ...
+
+    def parse(self, source: RawSource) -> ParseResult:
+        """Convert a raw snapshot into a canonical conversation.
+
+        Returns the conversation with any non-fatal findings. Raises
+        ``ParseError`` when the source cannot be parsed at all.
+        """
+        ...

convolvger/providers/chatgpt/__init__.py

@@ -0,0 +1,3 @@
+from convolvger.providers.chatgpt.provider import ChatGPTProvider
+
+__all__ = ["ChatGPTProvider"]