ghost-reader 0.1.0__py3-none-any.whl

ghost_reader/dialogue.py

@@ -0,0 +1,283 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+from ghost_reader.io import load_yaml_file, write_yaml
+from ghost_reader.paths import artifact_paths, session_dir
+from ghost_reader.project import load_manifest, read_persona
+from ghost_reader.reviews import feedback_summary, find_review_item, load_reviews
+from ghost_reader.telemetry import append_event
+from ghost_reader.time import now_iso
+
+_TURN_HEADER = re.compile(r"^## Turn (\d+) — (.+)$")
+
+_INDEX_SCHEMA_VERSION = 1
+
+
+def _dialogue_dir(project_root: Path, session_id: str) -> Path:
+    return artifact_paths(project_root, session_id)["dialogue"]
+
+
+def _index_path(project_root: Path, session_id: str) -> Path:
+    return _dialogue_dir(project_root, session_id) / "index.yaml"
+
+
+def _load_index(project_root: Path, session_id: str) -> dict[str, Any]:
+    path = _index_path(project_root, session_id)
+    if not path.exists():
+        return {"schema_version": _INDEX_SCHEMA_VERSION, "threads": {}}
+    return load_yaml_file(path)
+
+
+def _save_index(project_root: Path, session_id: str, index: dict[str, Any]) -> None:
+    write_yaml(_index_path(project_root, session_id), index)
+
+
+def load_dialogue(
+    project_root: Path, session_id: str, persona_id: str
+) -> list[dict[str, Any]]:
+    path = _dialogue_dir(project_root, session_id) / f"{persona_id}.md"
+    if not path.exists():
+        return []
+    turns: list[dict[str, Any]] = []
+    current_turn: dict[str, Any] | None = None
+    current_role: str | None = None
+    current_lines: list[str] = []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        header_match = _TURN_HEADER.match(line)
+        if header_match:
+            if current_turn is not None:
+                _flush_turn_block(current_turn, current_role, current_lines)
+                turns.append(current_turn)
+            current_turn = {
+                "turn_index": int(header_match.group(1)),
+                "timestamp": header_match.group(2),
+            }
+            current_role = None
+            current_lines = []
+            continue
+        if line.startswith("**User:**") or line.startswith("**Persona:**"):
+            if current_role is not None and current_lines:
+                _flush_turn_block(current_turn, current_role, current_lines)
+            current_role = "user" if line.startswith("**User:**") else "persona"
+            current_lines = [line.split(":**", 1)[1].strip() if ":**" in line else ""]
+            continue
+        if current_turn is not None and current_role is not None:
+            current_lines.append(line)
+    if current_turn is not None:
+        _flush_turn_block(current_turn, current_role, current_lines)
+        turns.append(current_turn)
+    return turns
+
+
+def _flush_turn_block(
+    turn: dict[str, Any], role: str | None, lines: list[str]
+) -> None:
+    if role and lines:
+        turn[role] = "\n".join(lines).strip()
+
+
+def dialogue_thread_context(
+    project_root: Path,
+    session_id: str,
+    thread_id: str,
+) -> dict[str, Any]:
+    index = _load_index(project_root, session_id)
+    threads = index.get("threads", {})
+    if thread_id not in threads:
+        raise FileNotFoundError(
+            f"Thread `{thread_id}` not found in dialogue index for session `{session_id}`."
+        )
+    return threads[thread_id]
+
+
+def dialogue_context(
+    project_root: Path,
+    home: Path,
+    session_id: str,
+    persona_id: str,
+    item_id: str,
+) -> dict[str, Any]:
+    load_manifest(project_root, session_id)
+    persona = read_persona(home, persona_id)
+    reviews = {
+        review["persona_id"]: review
+        for review in load_reviews(project_root, home, session_id)
+    }
+    review = reviews.get(persona_id)
+    if not review:
+        raise FileNotFoundError(
+            f"No review artifact found for persona `{persona_id}` in session `{session_id}`."
+        )
+    found = find_review_item(review, item_id)
+    if not found:
+        raise FileNotFoundError(
+            f"Review item `{item_id}` not found in {persona_id}'s review."
+        )
+    kind, item = found
+    feedback = feedback_summary(project_root, session_id)
+    target_id = f"{persona_id}:{item_id}"
+    user_note = feedback["user_notes"].get(target_id, "")
+    prior = load_dialogue(project_root, session_id, persona_id)
+    locators = [
+        evidence.get("locator")
+        for evidence in item.get("evidence", [])
+        if evidence.get("locator")
+    ]
+    context_dir = session_dir(project_root, session_id) / "context"
+    source_map_path = context_dir / "source-map.yaml"
+    relevant_context: list[dict[str, str]] = []
+    if source_map_path.exists():
+        source_map = load_yaml_file(source_map_path)
+        for entry in source_map.get("source_ranges", []):
+            if entry.get("locator") in locators:
+                relevant_context.append(
+                    {
+                        "source_id": entry.get("source_id", ""),
+                        "locator": entry.get("locator", ""),
+                    }
+                )
+    return {
+        "session_id": session_id,
+        "persona": {
+            "id": persona["id"],
+            "reader_type": persona["reader_type"],
+            "review_focus": persona["review_focus"],
+        },
+        "review_item": {
+            "id": item_id,
+            "kind": "strength" if kind == "strengths" else "concern",
+            "reason": item.get("reason"),
+            "locator": locators[0] if locators else None,
+            "revision_hint": item.get("revision_hint"),
+            "reader_effect": item.get("reader_effect"),
+        },
+        "user_note": user_note,
+        "prior_dialogue_summary": (
+            f"{len(prior)} previous turn(s)."
+            if prior
+            else "No previous dialogue."
+        ),
+        "relevant_context": relevant_context,
+    }
+
+
+def dialogue_append(
+    project_root: Path,
+    home: Path,
+    session_id: str,
+    persona_id: str,
+    item_id: str,
+    turn_text: str,
+    thread_id: str | None = None,
+    round_id: int | None = None,
+    item_uid: str | None = None,
+) -> dict[str, Any]:
+    load_manifest(project_root, session_id)
+    dialogue_dir = _dialogue_dir(project_root, session_id)
+    dialogue_dir.mkdir(parents=True, exist_ok=True)
+    existing = load_dialogue(project_root, session_id, persona_id)
+    turn_index = len(existing) + 1
+    timestamp = now_iso()
+    path = dialogue_dir / f"{persona_id}.md"
+    block = f"## Turn {turn_index} — {timestamp}\n\n{turn_text.strip()}\n"
+    with path.open("a", encoding="utf-8") as handle:
+        handle.write("\n" + block if existing else block)
+    append_event(
+        home,
+        project_root,
+        "dialogue_turn_created",
+        session_id,
+        meta={
+            "persona_id": persona_id,
+            "review_item_id": item_id,
+            "turn_index": turn_index,
+        },
+    )
+    index = _load_index(project_root, session_id)
+    tid = thread_id or f"th-{persona_id}-{item_id}"
+    if tid not in index.setdefault("threads", {}):
+        index["threads"][tid] = {
+            "persona_id": persona_id,
+            "round_id": round_id or 1,
+            "item_uid": item_uid or "",
+            "created_at": timestamp,
+            "turns": [],
+        }
+    user_text, persona_text = _split_turn_text(turn_text)
+    index["threads"][tid]["turns"].append(
+        {
+            "turn_index": turn_index,
+            "timestamp": timestamp,
+            "user": user_text,
+            "persona": persona_text,
+        }
+    )
+    _save_index(project_root, session_id, index)
+    return {
+        "written": True,
+        "path": str(path),
+        "turn_index": turn_index,
+        "persona_id": persona_id,
+        "review_item_id": item_id,
+        "thread_id": tid,
+    }
+
+
+def _split_turn_text(turn_text: str) -> tuple[str, str]:
+    user_text = ""
+    persona_text = ""
+    lines = turn_text.strip().splitlines()
+    current_role: str | None = None
+    current_lines: list[str] = []
+    for line in lines:
+        if line.startswith("**User:**"):
+            if current_role == "persona" and current_lines:
+                persona_text = "\n".join(current_lines).strip()
+            current_role = "user"
+            current_lines = [line.split(":**", 1)[1].strip() if ":**" in line else ""]
+        elif line.startswith("**Persona:**"):
+            if current_role == "user" and current_lines:
+                user_text = "\n".join(current_lines).strip()
+            current_role = "persona"
+            current_lines = [line.split(":**", 1)[1].strip() if ":**" in line else ""]
+        elif current_role is not None:
+            current_lines.append(line)
+    if current_role == "user" and current_lines:
+        user_text = "\n".join(current_lines).strip()
+    elif current_role == "persona" and current_lines:
+        persona_text = "\n".join(current_lines).strip()
+    return user_text, persona_text
+
+
+def load_all_dialogue(
+    project_root: Path, session_id: str, personas: list[str]
+) -> dict[str, list[dict[str, Any]]]:
+    index = _load_index(project_root, session_id)
+    if index.get("threads"):
+        result: dict[str, list[dict[str, Any]]] = {}
+        for thread_id, thread in index["threads"].items():
+            persona_id = thread.get("persona_id", "")
+            if persona_id not in personas:
+                continue
+            if persona_id not in result:
+                result[persona_id] = []
+            for turn in thread.get("turns", []):
+                result[persona_id].append(
+                    {
+                        "thread_id": thread_id,
+                        "turn_index": turn.get("turn_index"),
+                        "timestamp": turn.get("timestamp"),
+                        "user": turn.get("user", ""),
+                        "persona": turn.get("persona", ""),
+                    }
+                )
+        return result
+    result: dict[str, list[dict[str, Any]]] = {}
+    for persona_id in personas:
+        turns = load_dialogue(project_root, session_id, persona_id)
+        if turns:
+            result[persona_id] = turns
+    return result

ghost_reader/errors.py

@@ -0,0 +1,2 @@
+class GhostReaderError(Exception):
+    """Expected CLI error shown without a traceback."""

ghost_reader/feedback_store.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from ghost_reader.constants import SCHEMA_VERSIONS
+from ghost_reader.io import write_yaml
+from ghost_reader.paths import artifact_paths
+from ghost_reader.project import load_manifest
+from ghost_reader.telemetry import append_event
+from ghost_reader.validators import validate_feedback
+
+
+def normalize_feedback(
+    feedback: dict[str, Any],
+    session_id: str,
+    project_root: Path,
+) -> dict[str, Any]:
+    manifest = load_manifest(project_root, session_id)
+    normalized = dict(feedback)
+    normalized["schema_version"] = SCHEMA_VERSIONS["feedback"]
+    normalized["session_id"] = session_id
+    normalized.setdefault("round_id", manifest.get("current_round", 1))
+    if "mode" not in feedback:
+        normalized["mode"] = "revise"
+    normalized.setdefault("refinement_pass", 0)
+    return normalized
+
+
+def record_feedback(
+    project_root: Path,
+    home: Path,
+    session_id: str,
+    feedback: dict[str, Any],
+    *,
+    surface: str = "cli",
+) -> Path:
+    """Validate, persist feedback.yaml, and append content-safe telemetry."""
+    load_manifest(project_root, session_id)
+    feedback = normalize_feedback(feedback, session_id, project_root)
+    validate_feedback(feedback, session_id)
+    target = artifact_paths(project_root, session_id)["feedback"] / "feedback.yaml"
+    write_yaml(target, feedback)
+    append_event(
+        home,
+        project_root,
+        "feedback_recorded",
+        session_id,
+        surface=surface,
+        meta={
+            "selected_review_item_ids": [
+                item["target_id"] for item in feedback.get("selected_items", [])
+            ]
+        },
+    )
+    return target

ghost_reader/io.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from ghost_reader.errors import GhostReaderError
+
+
+def load_yaml_file(path: Path) -> Any:
+    try:
+        with path.open("r", encoding="utf-8") as handle:
+            return yaml.safe_load(handle) or {}
+    except yaml.YAMLError as exc:
+        raise GhostReaderError(_yaml_error_message(str(path), exc)) from exc
+
+
+def load_yaml_text(text: str, source: str = "provided YAML text") -> Any:
+    try:
+        return yaml.safe_load(text) or {}
+    except yaml.YAMLError as exc:
+        raise GhostReaderError(_yaml_error_message(source, exc)) from exc
+
+
+def _yaml_error_message(source: str, exc: yaml.YAMLError) -> str:
+    return (
+        f"Invalid YAML in {source}. Common causes are unquoted special characters "
+        f"(:, #, {{, }}, [, ]) or inconsistent indentation. Original parser message: {exc}"
+    )
+
+
+def dump_yaml(data: Any) -> str:
+    return yaml.safe_dump(data, sort_keys=False, allow_unicode=True)
+
+
+def write_yaml(path: Path, data: Any) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(dump_yaml(data), encoding="utf-8")
+
+
+def emit_yaml(data: Any) -> None:
+    sys.stdout.write(dump_yaml(data))
+
+
+def read_input(args: argparse.Namespace) -> str:
+    if getattr(args, "from_file", None):
+        if args.from_file == "-":
+            return sys.stdin.read()
+        return Path(args.from_file).read_text(encoding="utf-8")
+    if getattr(args, "content", None) is not None:
+        return args.content
+    if sys.stdin.isatty():
+        raise GhostReaderError(
+            "No input provided. Use --from, --content, or pipe content on stdin."
+        )
+    return sys.stdin.read()

ghost_reader/models.py

@@ -0,0 +1,227 @@
+"""Pydantic models for ghost-reader data schemas.
+
+Provides parse-once validation for persona, review, and feedback data.
+All models preserve schema_version for backward compatibility with on-disk files.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field, model_validator
+from pydantic.config import ConfigDict
+
+
+class GhostReaderBase(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+
+class PersonaProfile(GhostReaderBase):
+    summary: str | None = None
+    favorite_genres: list[str] = Field(default_factory=list)
+
+
+class PersonaPreferences(GhostReaderBase):
+    seeks: list[str] = Field(default_factory=list)
+    dislikes: list[str] = Field(default_factory=list)
+
+
+class ReviewFocus(GhostReaderBase):
+    primary: list[str] = Field(default_factory=list)
+    secondary: list[str] = Field(default_factory=list)
+
+
+class FeedbackVoice(GhostReaderBase):
+    voice: str | None = None
+    default_question: str | None = None
+
+
+class Persona(GhostReaderBase):
+    """Persona schema v1 — loaded from YAML files in defaults/personas/."""
+
+    schema_version: int = 1
+    id: str
+    name: str
+    reader_type: str
+    profile: PersonaProfile = PersonaProfile()
+    preferences: PersonaPreferences = PersonaPreferences()
+    review_focus: ReviewFocus = ReviewFocus()
+    feedback_style: FeedbackVoice = FeedbackVoice()
+
+    @model_validator(mode="after")
+    def check_schema_version(self) -> Persona:
+        from ghost_reader.constants import SCHEMA_VERSIONS
+
+        expected = SCHEMA_VERSIONS["persona"]
+        if self.schema_version != expected:
+            raise ValueError(f"Persona schema_version must be {expected}.")
+        return self
+
+    @model_validator(mode="after")
+    def check_forbidden_fields(self) -> Persona:
+        forbidden = {
+            "posture",
+            "tolerance",
+            "telemetry",
+            "matching",
+            "analytics",
+            "weights",
+        }
+        # Check both defined fields and extra fields (extra="allow" stores unknown keys)
+        defined = set(type(self).model_fields.keys())
+        extra = getattr(self, "model_extra", {}) or {}
+        present = sorted(forbidden.intersection(defined | set(extra.keys())))
+        if present:
+            raise ValueError(
+                f"Persona includes forbidden Phase 1 fields: {', '.join(present)}"
+            )
+        return self
+
+
+class Evidence(GhostReaderBase):
+    source_id: str
+    locator: str
+
+
+class ReviewItem(GhostReaderBase):
+    id: str = Field(..., pattern=r"^[sc][1-9][0-9]*$")
+    reason: str
+    item_uid: str = Field(
+        ...,
+        pattern=r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
+    )
+    refinement_pass: bool
+    evidence: list[Evidence] = Field(..., min_length=1)
+
+    # concern-specific (optional for strengths)
+    reader_effect: str | None = None
+    revision_hint: str | None = None
+
+
+class OverallScore(GhostReaderBase):
+    summary: str
+    would_continue: bool
+
+
+class ReviewScores(GhostReaderBase):
+    engagement: int = Field(..., ge=1, le=10)
+    character: int = Field(..., ge=1, le=10)
+    pacing: int = Field(..., ge=1, le=10)
+    genre_fit: int = Field(..., ge=1, le=10)
+
+
+class Review(GhostReaderBase):
+    """Review schema v2 — loaded from .review.yaml artifact files."""
+
+    schema_version: int = 2
+    session_id: str
+    persona_id: str
+    round_id: int | str
+    overall: OverallScore
+    scores: ReviewScores
+    strengths: list[ReviewItem]
+    concerns: list[ReviewItem]
+
+    @model_validator(mode="after")
+    def check_schema_version(self) -> Review:
+        from ghost_reader.constants import SCHEMA_VERSIONS
+
+        expected = SCHEMA_VERSIONS["review"]
+        if self.schema_version != expected:
+            raise ValueError(f"Review schema_version must be {expected}.")
+        return self
+
+    @model_validator(mode="after")
+    def check_strength_ids(self) -> Review:
+        for item in self.strengths:
+            if not item.id.startswith("s"):
+                raise ValueError(f"Strength id `{item.id}` must start with s.")
+        return self
+
+    @model_validator(mode="after")
+    def check_concern_ids(self) -> Review:
+        for item in self.concerns:
+            if not item.id.startswith("c"):
+                raise ValueError(f"Concern id `{item.id}` must start with c.")
+            if not item.reader_effect:
+                raise ValueError(f"Concern {item.id} must include reader_effect.")
+            if not item.revision_hint:
+                raise ValueError(f"Concern {item.id} must include revision_hint.")
+        return self
+
+
+class SelectedItem(GhostReaderBase):
+    target_id: str
+    item_uid: str
+    thread_id: str
+    note: str | None = None
+
+    @model_validator(mode="after")
+    def check_forbidden_fields(self) -> SelectedItem:
+        forbidden = {
+            "supportive_items",
+            "rejective_items",
+            "accepted_items",
+            "rejected_items",
+            "stance",
+            "classification",
+        }
+        defined = set(type(self).model_fields.keys())
+        extra = getattr(self, "model_extra", {}) or {}
+        present = sorted(forbidden.intersection(defined | set(extra.keys())))
+        if present:
+            raise ValueError(
+                f"SelectedItem includes forbidden fields: {', '.join(present)}"
+            )
+        return self
+
+
+class Feedback(GhostReaderBase):
+    """Feedback schema v2 — loaded from feedback.yaml artifact files."""
+
+    schema_version: int = 2
+    session_id: str
+    round_id: int | str | None = None
+    mode: str
+    selected_items: list[SelectedItem] = Field(..., min_length=1)
+
+    @model_validator(mode="after")
+    def check_schema_version(self) -> Feedback:
+        from ghost_reader.constants import SCHEMA_VERSIONS
+
+        expected = SCHEMA_VERSIONS["feedback"]
+        if self.schema_version != expected:
+            raise ValueError(f"Feedback schema_version must be {expected}.")
+        return self
+
+    @model_validator(mode="after")
+    def check_mode(self) -> Feedback:
+        if self.mode not in ("refine", "revise"):
+            raise ValueError("Feedback mode must be 'refine' or 'revise'.")
+        return self
+
+    @model_validator(mode="after")
+    def check_target_id_format(self) -> Feedback:
+        for item in self.selected_items:
+            if ":" not in item.target_id:
+                raise ValueError(
+                    f"Feedback target_id `{item.target_id}` must use persona:item format."
+                )
+        return self
+
+    @model_validator(mode="after")
+    def check_forbidden_fields(self) -> Feedback:
+        forbidden = {
+            "supportive_items",
+            "rejective_items",
+            "accepted_items",
+            "rejected_items",
+            "stance",
+            "classification",
+        }
+        defined = set(type(self).model_fields.keys())
+        extra = getattr(self, "model_extra", {}) or {}
+        present = sorted(forbidden.intersection(defined | set(extra.keys())))
+        if present:
+            raise ValueError(
+                f"Feedback includes forbidden stance-classification fields: {', '.join(present)}"
+            )
+        return self

ghost_reader/paths.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from ghost_reader.errors import GhostReaderError
+
+
+def ghost_reader_home() -> Path:
+    return Path(
+        os.environ.get("GHOST_READER_HOME", Path.home() / ".ghostreader")
+    ).expanduser()
+
+
+def project_dir(project_root: Path) -> Path:
+    return project_root / ".ghostreader"
+
+
+def session_dir(project_root: Path, session_id: str) -> Path:
+    return project_dir(project_root) / "sessions" / session_id
+
+
+def round_dir(project_root: Path, session_id: str, round_id: int) -> Path:
+    return session_dir(project_root, session_id) / f"round-{round_id}"
+
+
+def active_round_dir(project_root: Path, session_id: str) -> Path:
+    from ghost_reader.project import load_manifest
+
+    manifest = load_manifest(project_root, session_id)
+    current = manifest.get("current_round", 1)
+    return round_dir(project_root, session_id, current)
+
+
+def artifact_paths(project_root: Path, session_id: str) -> dict[str, Path]:
+    active = active_round_dir(project_root, session_id)
+    session = session_dir(project_root, session_id)
+    return {
+        "context": active / "context",
+        "reviews": active / "reviews",
+        "feedback": active / "feedback",
+        "prompts": active / "prompts",
+        "report": active / "report",
+        "refinements": active / "refinements",
+        "dialogue": session / "dialogue",
+        "manifest": session / "manifest.yaml",
+        "telemetry": session / "telemetry",
+        "session": session,
+        "active_round": active,
+    }
+
+
+def find_project_root(start: Path | None = None) -> Path:
+    current = (start or Path.cwd()).resolve()
+    for candidate in [current, *current.parents]:
+        if (candidate / ".ghostreader" / "project.yaml").exists():
+            return candidate
+    raise GhostReaderError(
+        "Ghost Reader project not initialized. Run `ghost-reader init` first."
+    )
+
+
+def outbox_path(home: Path) -> Path:
+    return home / "telemetry" / "outbox" / "events.ndjson"
+
+
+def sync_state_path(home: Path) -> Path:
+    return home / "telemetry" / "sync-state.yaml"