postwriter 0.1.0__tar.gz

postwriter-0.1.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.3
+Name: postwriter
+Version: 0.1.0
+Summary: Orchestrated long-form fiction generation system
+Author: Avram Score
+Author-email: Avram Score <ascore@gmail.com>
+Requires-Dist: sqlalchemy[asyncio]>=2.0,<3.0
+Requires-Dist: asyncpg>=0.29,<1.0
+Requires-Dist: alembic>=1.13,<2.0
+Requires-Dist: redis>=5.0,<6.0
+Requires-Dist: anthropic>=0.40,<1.0
+Requires-Dist: pydantic>=2.0,<3.0
+Requires-Dist: pydantic-settings>=2.0,<3.0
+Requires-Dist: jinja2>=3.1,<4.0
+Requires-Dist: rich>=13.0,<14.0
+Requires-Dist: prompt-toolkit>=3.0,<4.0
+Requires-Dist: networkx>=3.0,<4.0
+Requires-Dist: click>=8.0,<9.0
+Requires-Dist: ebooklib>=0.20
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# Postwriter
+
+An orchestrated system for generating long-form fiction. Postwriter treats novel writing as a multi-pass engineering problem — planning at multiple narrative scales, drafting with stylistic variation, validating against explicit story state, and revising with manuscript-level awareness.
+
+The target is not one-shot draft generation. The target is sustained narrative control, stylistic freshness, and cumulative artistic pressure across an entire manuscript.
+
+## What it does
+
+Postwriter generates a complete novel (~80k words) through a pipeline of specialized AI agents:
+
+1. **Plan** — An architect agent designs the premise, structural spine, characters, style profile, chapters, and scenes. You approve the premise and act structure at human checkpoints.
+
+2. **Draft** — Each scene is drafted 3–5 times in parallel using distinct stylistic profiles (subtext-heavy, lyrical, compressed, etc.). Branches are not random paraphrases — they represent different rhetorical strategies.
+
+3. **Validate** — 5 hard validators (continuity, timeline, POV, knowledge state, banned patterns) gate acceptance. 10 soft critics score tension, emotion, prose vitality, voice consistency, dialogue, thematic integration, redundancy, transitions, scene purpose, and symbolic restraint.
+
+4. **Repair** — Failed drafts enter a targeted repair loop (up to 3 rounds). The repair planner prioritizes issues, and a local rewriter fixes specific problems while preserving what works.
+
+5. **Analyze** — Literary devices are detected across the manuscript (54 types, rule-based and model-based), tracked in temporal graphs, and evaluated for overuse, burstiness, imagery monoculture, and functional repetition.
+
+6. **Revise** — Manuscript-level audits check promises, character arcs, device ecology, rhythm, and thematic overstatement. A backward propagation engine modifies earlier scenes to strengthen later payoffs.
+
+7. **Export** — The final manuscript exports as markdown, with a full JSON canonical state dump and a generation report.
+
+## How it works
+
+The manuscript is maintained as four linked representations:
+
+- **Text layer** — the prose itself
+- **Story-state layer** — facts, causality, character states, timeline, unresolved obligations
+- **Stylistic layer** — voice targets, device preferences, imagery ecology, banned phrases
+- **Analytical layer** — validator outputs, scores, device distributions, revision lineage
+
+No important reasoning depends on prose alone when it can instead depend on structured state.
+
+## Quick start
+
+### Prerequisites
+
+- Python 3.12+
+- Docker (for PostgreSQL and Redis)
+- An Anthropic API key
+
+### Install
+
+```bash
+git clone https://github.com/avigold/postwriter.git
+cd postwriter
+uv sync
+```
+
+### Start infrastructure
+
+```bash
+docker compose up -d
+uv run alembic upgrade head
+```
+
+### Configure
+
+```bash
+echo "PW_LLM_ANTHROPIC_API_KEY=sk-ant-your-key-here" > .env
+```
+
+### Run
+
+```bash
+uv run postwriter new
+```
+
+This walks you through an interactive bootstrap, then runs the full pipeline: plan → draft → revise → export.
+
+### Options
+
+```bash
+# Use a generation profile
+uv run postwriter new --profile fast_draft      # Fewer branches, faster
+uv run postwriter new --profile high_quality    # More branches, more repair rounds
+uv run postwriter new --profile budget_conscious # Minimize API costs
+
+# Export a completed manuscript
+uv run postwriter export <manuscript-id> --format all
+
+# View manuscript dashboard
+uv run postwriter dashboard <manuscript-id>
+
+# List profiles
+uv run postwriter profiles
+```
+
+## Context files
+
+Drop markdown or image files into a `context/` directory to inform the writing. These are optional — if they're there, the system uses them; if not, it asks you everything interactively.
+
+```
+context/
+  style-guide.md      # Voice and prose preferences
+  characters.md       # Character sketches
+  plot-outline.md     # Story beats or synopsis
+  mood-board.png      # Visual references
+```
+
+Files can include YAML frontmatter to specify their type:
+
+```markdown
+---
+type: style
+---
+Write in short, declarative sentences. Avoid adverbs.
+```
+
+Supported types: `sample_writing`, `plot`, `guidelines`, `characters`, `world`, `style`, `reference`. Without frontmatter, the system infers type from the filename.
+
+Context files can be added at any time during generation. New files affect future scenes (forward-only — no retroactive re-evaluation).
+
+## Architecture
+
+```
+postwriter/
+  agents/          # 10 specialized agents (architect, planner, writer, critics, rewriter)
+  canon/           # Canonical data store, context slicing, event logging
+  cli/             # Interactive CLI with rich terminal dashboards
+  context/         # User-provided reference file loader
+  db/              # Async PostgreSQL via SQLAlchemy 2.0, Alembic migrations
+  devices/         # Literary device detection (54 types), imagery classification
+  export/          # Markdown, JSON, and report exporters
+  graphs/          # Temporal device graphs and ecology metrics
+  llm/             # Anthropic SDK wrapper with Opus/Sonnet/Haiku tiering
+  models/          # 21 database tables covering the full canonical data model
+  orchestrator/    # Scene loop, branch management, global revision, checkpointing
+  prompts/         # Jinja2 prompt templates for all agent roles
+  repair/          # Repair planner and action specifications
+  revision/        # 5 manuscript-level audit passes + backward propagation
+  scoring/         # 11-dimension score vectors, Pareto comparison, device balance
+  validation/      # 5 hard validators + 10 soft critics
+```
+
+### Model tiering
+
+| Tier | Role | Used for |
+|------|------|----------|
+| Opus | Creative judgment | Premise design, act structure, pivotal scene branches |
+| Sonnet | Workhorse | Scene drafting, soft critics, repair, chapter/scene planning |
+| Haiku | Mechanical checks | Hard validators, device detection, state extraction |
+
+### Key design principles
+
+- Structured state outside prose — the database is the source of truth, not the text
+- Narrow agents — each agent does one thing well
+- Hard legality vs soft quality — separate concerns, separate priorities
+- Repair locally before rewriting globally
+- Branches represent rhetorical strategies, not random variation
+- Graphs are advisory but consequential
+- Human review at genuinely aesthetic decision points
+- Plain prose is sometimes superior to ornamental variation
+
+## Tests
+
+```bash
+uv run pytest tests/ -v
+```
+
+165 tests covering models, canon store, all validators and critics, device detection, graph metrics, scoring, repair planning, revision audits, export, and configuration profiles. Tests use a real PostgreSQL instance (Docker) for database tests and mock LLM responses for agent tests.
+
+## License
+
+TBD

postwriter-0.1.0/README.md

@@ -0,0 +1,167 @@
+# Postwriter
+
+An orchestrated system for generating long-form fiction. Postwriter treats novel writing as a multi-pass engineering problem — planning at multiple narrative scales, drafting with stylistic variation, validating against explicit story state, and revising with manuscript-level awareness.
+
+The target is not one-shot draft generation. The target is sustained narrative control, stylistic freshness, and cumulative artistic pressure across an entire manuscript.
+
+## What it does
+
+Postwriter generates a complete novel (~80k words) through a pipeline of specialized AI agents:
+
+1. **Plan** — An architect agent designs the premise, structural spine, characters, style profile, chapters, and scenes. You approve the premise and act structure at human checkpoints.
+
+2. **Draft** — Each scene is drafted 3–5 times in parallel using distinct stylistic profiles (subtext-heavy, lyrical, compressed, etc.). Branches are not random paraphrases — they represent different rhetorical strategies.
+
+3. **Validate** — 5 hard validators (continuity, timeline, POV, knowledge state, banned patterns) gate acceptance. 10 soft critics score tension, emotion, prose vitality, voice consistency, dialogue, thematic integration, redundancy, transitions, scene purpose, and symbolic restraint.
+
+4. **Repair** — Failed drafts enter a targeted repair loop (up to 3 rounds). The repair planner prioritizes issues, and a local rewriter fixes specific problems while preserving what works.
+
+5. **Analyze** — Literary devices are detected across the manuscript (54 types, rule-based and model-based), tracked in temporal graphs, and evaluated for overuse, burstiness, imagery monoculture, and functional repetition.
+
+6. **Revise** — Manuscript-level audits check promises, character arcs, device ecology, rhythm, and thematic overstatement. A backward propagation engine modifies earlier scenes to strengthen later payoffs.
+
+7. **Export** — The final manuscript exports as markdown, with a full JSON canonical state dump and a generation report.
+
+## How it works
+
+The manuscript is maintained as four linked representations:
+
+- **Text layer** — the prose itself
+- **Story-state layer** — facts, causality, character states, timeline, unresolved obligations
+- **Stylistic layer** — voice targets, device preferences, imagery ecology, banned phrases
+- **Analytical layer** — validator outputs, scores, device distributions, revision lineage
+
+No important reasoning depends on prose alone when it can instead depend on structured state.
+
+## Quick start
+
+### Prerequisites
+
+- Python 3.12+
+- Docker (for PostgreSQL and Redis)
+- An Anthropic API key
+
+### Install
+
+```bash
+git clone https://github.com/avigold/postwriter.git
+cd postwriter
+uv sync
+```
+
+### Start infrastructure
+
+```bash
+docker compose up -d
+uv run alembic upgrade head
+```
+
+### Configure
+
+```bash
+echo "PW_LLM_ANTHROPIC_API_KEY=sk-ant-your-key-here" > .env
+```
+
+### Run
+
+```bash
+uv run postwriter new
+```
+
+This walks you through an interactive bootstrap, then runs the full pipeline: plan → draft → revise → export.
+
+### Options
+
+```bash
+# Use a generation profile
+uv run postwriter new --profile fast_draft      # Fewer branches, faster
+uv run postwriter new --profile high_quality    # More branches, more repair rounds
+uv run postwriter new --profile budget_conscious # Minimize API costs
+
+# Export a completed manuscript
+uv run postwriter export <manuscript-id> --format all
+
+# View manuscript dashboard
+uv run postwriter dashboard <manuscript-id>
+
+# List profiles
+uv run postwriter profiles
+```
+
+## Context files
+
+Drop markdown or image files into a `context/` directory to inform the writing. These are optional — if they're there, the system uses them; if not, it asks you everything interactively.
+
+```
+context/
+  style-guide.md      # Voice and prose preferences
+  characters.md       # Character sketches
+  plot-outline.md     # Story beats or synopsis
+  mood-board.png      # Visual references
+```
+
+Files can include YAML frontmatter to specify their type:
+
+```markdown
+---
+type: style
+---
+Write in short, declarative sentences. Avoid adverbs.
+```
+
+Supported types: `sample_writing`, `plot`, `guidelines`, `characters`, `world`, `style`, `reference`. Without frontmatter, the system infers type from the filename.
+
+Context files can be added at any time during generation. New files affect future scenes (forward-only — no retroactive re-evaluation).
+
+## Architecture
+
+```
+postwriter/
+  agents/          # 10 specialized agents (architect, planner, writer, critics, rewriter)
+  canon/           # Canonical data store, context slicing, event logging
+  cli/             # Interactive CLI with rich terminal dashboards
+  context/         # User-provided reference file loader
+  db/              # Async PostgreSQL via SQLAlchemy 2.0, Alembic migrations
+  devices/         # Literary device detection (54 types), imagery classification
+  export/          # Markdown, JSON, and report exporters
+  graphs/          # Temporal device graphs and ecology metrics
+  llm/             # Anthropic SDK wrapper with Opus/Sonnet/Haiku tiering
+  models/          # 21 database tables covering the full canonical data model
+  orchestrator/    # Scene loop, branch management, global revision, checkpointing
+  prompts/         # Jinja2 prompt templates for all agent roles
+  repair/          # Repair planner and action specifications
+  revision/        # 5 manuscript-level audit passes + backward propagation
+  scoring/         # 11-dimension score vectors, Pareto comparison, device balance
+  validation/      # 5 hard validators + 10 soft critics
+```
+
+### Model tiering
+
+| Tier | Role | Used for |
+|------|------|----------|
+| Opus | Creative judgment | Premise design, act structure, pivotal scene branches |
+| Sonnet | Workhorse | Scene drafting, soft critics, repair, chapter/scene planning |
+| Haiku | Mechanical checks | Hard validators, device detection, state extraction |
+
+### Key design principles
+
+- Structured state outside prose — the database is the source of truth, not the text
+- Narrow agents — each agent does one thing well
+- Hard legality vs soft quality — separate concerns, separate priorities
+- Repair locally before rewriting globally
+- Branches represent rhetorical strategies, not random variation
+- Graphs are advisory but consequential
+- Human review at genuinely aesthetic decision points
+- Plain prose is sometimes superior to ornamental variation
+
+## Tests
+
+```bash
+uv run pytest tests/ -v
+```
+
+165 tests covering models, canon store, all validators and critics, device detection, graph metrics, scoring, repair planning, revision audits, export, and configuration profiles. Tests use a real PostgreSQL instance (Docker) for database tests and mock LLM responses for agent tests.
+
+## License
+
+TBD

postwriter-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+name = "postwriter"
+version = "0.1.0"
+description = "Orchestrated long-form fiction generation system"
+readme = "README.md"
+authors = [
+    { name = "Avram Score", email = "ascore@gmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "sqlalchemy[asyncio]>=2.0,<3.0",
+    "asyncpg>=0.29,<1.0",
+    "alembic>=1.13,<2.0",
+    "redis>=5.0,<6.0",
+    "anthropic>=0.40,<1.0",
+    "pydantic>=2.0,<3.0",
+    "pydantic-settings>=2.0,<3.0",
+    "jinja2>=3.1,<4.0",
+    "rich>=13.0,<14.0",
+    "prompt-toolkit>=3.0,<4.0",
+    "networkx>=3.0,<4.0",
+    "click>=8.0,<9.0",
+    "ebooklib>=0.20",
+]
+
+[project.scripts]
+postwriter = "postwriter.cli.app:main"
+
+[build-system]
+requires = ["uv_build>=0.10.7,<0.11.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0,<9.0",
+    "pytest-asyncio>=0.24,<1.0",
+    "pytest-cov>=5.0,<6.0",
+    "factory-boy>=3.3,<4.0",
+    "mypy>=1.10,<2.0",
+    "ruff>=0.6,<1.0",
+]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "B", "SIM", "TCH"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+plugins = ["pydantic.mypy"]

postwriter-0.1.0/src/postwriter/__init__.py

@@ -0,0 +1,2 @@
+def hello() -> str:
+    return "Hello from postwriter!"

postwriter-0.1.0/src/postwriter/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for `python -m postwriter`."""
+
+from postwriter.cli.app import main
+
+if __name__ == "__main__":
+    main()

postwriter-0.1.0/src/postwriter/agents/__init__.py

@@ -0,0 +1,6 @@
+"""Agent implementations for the fiction orchestration system."""
+
+from postwriter.agents.base import BaseAgent
+from postwriter.agents.context import AgentContext, AgentResult
+
+__all__ = ["BaseAgent", "AgentContext", "AgentResult"]

postwriter-0.1.0/src/postwriter/agents/architect.py

@@ -0,0 +1,118 @@
+"""Architect agents: premise design and structural spine."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from postwriter.agents.base import BaseAgent
+from postwriter.types import AgentContext, ModelTier
+
+
+# ---------------------------------------------------------------------------
+# Response models
+# ---------------------------------------------------------------------------
+
+
+class PremiseResponse(BaseModel):
+    premise: str = Field(description="2-3 paragraph summary of the novel's core situation and trajectory")
+    controlling_design: dict[str, Any] = Field(
+        description="Architectural spine: central_question, arc_shape, turning_points, emotional_trajectory, plot_internal_relationship, tonal_range"
+    )
+    thematic_architecture: dict[str, Any] = Field(
+        description="How themes are embodied: character_tensions, symbolic_patterns, structural_embodiments"
+    )
+
+
+class SpineResponse(BaseModel):
+    acts: list[dict[str, Any]] = Field(
+        description="List of acts, each with: name, ordinal, purpose, emotional_arc, chapter_count"
+    )
+    major_turning_points: list[dict[str, Any]] = Field(
+        description="Key structural turning points with: description, approximate_position, function"
+    )
+    arc_summary: str = Field(description="One-paragraph summary of the full arc shape")
+
+
+# ---------------------------------------------------------------------------
+# Agents
+# ---------------------------------------------------------------------------
+
+
+class PremiseArchitect(BaseAgent):
+    """Generates a novel premise and controlling design from a creative brief."""
+
+    role = "premise_architect"
+    model_tier = ModelTier.OPUS
+    template_name = "architect_premise.j2"
+    response_model = PremiseResponse
+
+    def build_template_context(self, context: AgentContext) -> dict[str, Any]:
+        brief = context.extra.get("creative_brief", {})
+        return {
+            "genre": brief.get("genre", ""),
+            "setting": brief.get("setting", ""),
+            "time_period": brief.get("time_period", ""),
+            "tone": brief.get("tone", ""),
+            "protagonist": brief.get("protagonist", ""),
+            "central_conflict": brief.get("central_conflict", ""),
+            "ending_direction": brief.get("ending_direction", ""),
+            "themes": brief.get("themes", []),
+            "constraints": brief.get("constraints", []),
+            "user_context": context.user_context,
+        }
+
+    def build_system_prompt(self, context: AgentContext) -> str:
+        base = (
+            "You are a master fiction architect with deep knowledge of narrative structure, "
+            "literary tradition, and genre conventions. Your task is to design a novel premise "
+            "and controlling design that will sustain a full-length manuscript.\n\n"
+            "Design for emotional credibility, thematic depth, and structural integrity. "
+            "Themes should be embodied through character and situation, never stated directly."
+        )
+        # Append user context if available
+        if context.user_context:
+            base += "\n\n## User-Provided Reference Materials\n\n"
+            for ctx in context.user_context:
+                base += f"### {ctx.get('name', 'Reference')} ({ctx.get('type', 'unknown')})\n"
+                base += ctx.get("content", "") + "\n\n"
+        return base
+
+    def _max_tokens(self) -> int:
+        return 8192
+
+    def _temperature(self) -> float:
+        return 1.0
+
+
+class SpineArchitect(BaseAgent):
+    """Designs the structural spine (acts and major movements) from a premise."""
+
+    role = "spine_architect"
+    model_tier = ModelTier.OPUS
+    template_name = "architect_spine.j2"
+    response_model = SpineResponse
+
+    def build_template_context(self, context: AgentContext) -> dict[str, Any]:
+        return {
+            "premise": context.premise,
+            "controlling_design": context.controlling_design,
+            "target_word_count": context.extra.get("target_word_count", 80000),
+            "target_chapters": context.extra.get("target_chapters", "30-40"),
+            "user_context": context.user_context,
+        }
+
+    def build_system_prompt(self, context: AgentContext) -> str:
+        return (
+            "You are a master fiction architect. Given a premise and controlling design, "
+            "design the structural spine of the novel: its acts, major movements, and "
+            "turning points.\n\n"
+            "Each act should have a clear purpose and emotional trajectory. "
+            "Distribute tension, revelation, and release across the full arc. "
+            "The spine should support the controlling design without over-determining "
+            "individual scenes."
+        )
+
+    def _max_tokens(self) -> int:
+        return 8192