authoringfw 0.1.0__tar.gz

authoringfw-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,38 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install and test
+        run: |
+          pip install -e ".[dev]"
+          pytest tests/ -v
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Build
+        run: |
+          pip install hatch
+          hatch build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

authoringfw-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+*.log

authoringfw-0.1.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog — authoringfw
+
+## [Unreleased]
+
+## [0.1.0] — 2026-02-28
+
+### Added
+- Initial release
+- `StyleProfile` — tone, POV, tense, vocabulary, sentence rhythm + `to_constraints()`
+- `CharacterProfile` — name, role, traits, backstory, arc, relationships + `to_context_string()`
+- `WorldContext` + `Location` — world rules, locations, lore + `to_context_string()`
+- `VersionMetadata` — immutable content snapshot with SHA-256 hash, semver, LLM metadata
+- `PhaseSnapshot` — project state at workflow phase boundary
+- `ChangeType` enum (AI_GENERATED, HUMAN_EDITED, MERGED, REVERTED)
+- `FormatProfile` — novel, essay, series, scientific with workflow phases and style constraints
+- `WorkflowPhase` enum (IDEATION → PRODUCTION)
+- `StepConfig` — per-step template and parameter config
+- `get_format()` — lookup built-in format profiles
+- `IStyleAdapter`, `ICharacterAdapter`, `IWorldAdapter` Protocol interfaces (`@runtime_checkable`)

authoringfw-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: authoringfw
+Version: 0.1.0
+Summary: Authoring Framework — domain schemas for AI-assisted creative writing applications
+Project-URL: Homepage, https://github.com/achimdehnert/platform
+Project-URL: Repository, https://github.com/achimdehnert/platform/tree/main/packages/authoringfw
+Author-email: Achim Dehnert <achim@dehnert.com>
+License: MIT
+Keywords: ai,authoring,creative-writing,llm,pydantic,schema,story
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.6
+Provides-Extra: dev
+Requires-Dist: pytest-mock>=3.12; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: testing
+Requires-Dist: pytest-mock>=3.12; extra == 'testing'
+Requires-Dist: pytest>=8.0; extra == 'testing'
+Description-Content-Type: text/markdown
+
+# authoringfw — Authoring Framework
+
+Domain schemas for AI-assisted creative writing applications.
+
+## Installation
+
+```bash
+pip install authoringfw
+```
+
+## Quick Start
+
+```python
+from authoringfw import StyleProfile, CharacterProfile, WorldContext, get_format
+
+# Style constraints for prompt injection
+style = StyleProfile(tone="melancholic", pov="third_limited", tense="past")
+constraints = style.to_constraints()
+
+# Character context
+alice = CharacterProfile(
+    name="Alice",
+    role="protagonist",
+    personality_traits=["brave", "curious"],
+    arc="From fear to courage",
+)
+print(alice.to_context_string())
+
+# World context
+world = WorldContext(
+    title="The Shattered Realms",
+    genre="fantasy",
+    world_rules=["Magic costs life force", "Dragons are extinct"],
+)
+print(world.to_context_string())
+
+# Format profiles (novel, essay, series, scientific)
+roman = get_format("roman")
+print(roman.style_constraints)
+```
+
+## Schemas
+
+- **`StyleProfile`** — tone, POV, tense, vocabulary, sentence rhythm
+- **`CharacterProfile`** — name, role, traits, backstory, arc, relationships
+- **`WorldContext`** — title, genre, setting, world rules, locations, lore
+- **`VersionMetadata`** — immutable content snapshot with hash, semver, LLM metadata
+- **`PhaseSnapshot`** — project state at a workflow phase boundary
+
+## Format Profiles
+
+Built-in formats: `roman`, `essay`, `serie`, `scientific`
+
+```python
+from authoringfw.formats.base import get_format, WorkflowPhase
+
+novel = get_format("roman")
+outline_steps = novel.steps_for_phase(WorkflowPhase.OUTLINE)
+```
+
+## Adapter Interfaces
+
+Protocol-based adapters — no inheritance required:
+
+```python
+from authoringfw.adapters.interfaces import IStyleAdapter
+
+class MyStyleAdapter:
+    async def get_profile(self, style_id): ...
+    async def analyze_text(self, text): ...
+    def generate_style_constraints(self, profile): ...
+    async def score_conformity(self, text, profile): ...
+
+adapter = MyStyleAdapter()
+assert isinstance(adapter, IStyleAdapter)  # True via @runtime_checkable
+```

authoringfw-0.1.0/README.md

@@ -0,0 +1,76 @@
+# authoringfw — Authoring Framework
+
+Domain schemas for AI-assisted creative writing applications.
+
+## Installation
+
+```bash
+pip install authoringfw
+```
+
+## Quick Start
+
+```python
+from authoringfw import StyleProfile, CharacterProfile, WorldContext, get_format
+
+# Style constraints for prompt injection
+style = StyleProfile(tone="melancholic", pov="third_limited", tense="past")
+constraints = style.to_constraints()
+
+# Character context
+alice = CharacterProfile(
+    name="Alice",
+    role="protagonist",
+    personality_traits=["brave", "curious"],
+    arc="From fear to courage",
+)
+print(alice.to_context_string())
+
+# World context
+world = WorldContext(
+    title="The Shattered Realms",
+    genre="fantasy",
+    world_rules=["Magic costs life force", "Dragons are extinct"],
+)
+print(world.to_context_string())
+
+# Format profiles (novel, essay, series, scientific)
+roman = get_format("roman")
+print(roman.style_constraints)
+```
+
+## Schemas
+
+- **`StyleProfile`** — tone, POV, tense, vocabulary, sentence rhythm
+- **`CharacterProfile`** — name, role, traits, backstory, arc, relationships
+- **`WorldContext`** — title, genre, setting, world rules, locations, lore
+- **`VersionMetadata`** — immutable content snapshot with hash, semver, LLM metadata
+- **`PhaseSnapshot`** — project state at a workflow phase boundary
+
+## Format Profiles
+
+Built-in formats: `roman`, `essay`, `serie`, `scientific`
+
+```python
+from authoringfw.formats.base import get_format, WorkflowPhase
+
+novel = get_format("roman")
+outline_steps = novel.steps_for_phase(WorkflowPhase.OUTLINE)
+```
+
+## Adapter Interfaces
+
+Protocol-based adapters — no inheritance required:
+
+```python
+from authoringfw.adapters.interfaces import IStyleAdapter
+
+class MyStyleAdapter:
+    async def get_profile(self, style_id): ...
+    async def analyze_text(self, text): ...
+    def generate_style_constraints(self, profile): ...
+    async def score_conformity(self, text, profile): ...
+
+adapter = MyStyleAdapter()
+assert isinstance(adapter, IStyleAdapter)  # True via @runtime_checkable
+```

authoringfw-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+name = "authoringfw"
+version = "0.1.0"
+description = "Authoring Framework — domain schemas for AI-assisted creative writing applications"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+authors = [
+    {name = "Achim Dehnert", email = "achim@dehnert.com"}
+]
+keywords = ["llm", "authoring", "creative-writing", "ai", "story", "schema", "pydantic"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Text Processing :: Linguistic",
+]
+
+dependencies = [
+    "pydantic>=2.6",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-mock>=3.12",
+]
+testing = [
+    "pytest>=8.0",
+    "pytest-mock>=3.12",
+]
+
+[project.urls]
+Homepage = "https://github.com/achimdehnert/platform"
+Repository = "https://github.com/achimdehnert/platform/tree/main/packages/authoringfw"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/authoringfw"]
+
+[tool.pytest.ini_options]
+python_files = ["test_*.py"]
+pythonpath = ["."]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"

authoringfw-0.1.0/src/authoringfw/__init__.py

@@ -0,0 +1,24 @@
+"""
+authoringfw — Authoring Framework
+
+Domain schemas for AI-assisted creative writing applications.
+"""
+
+__version__ = "0.1.0"
+
+from authoringfw.schema.style import StyleProfile
+from authoringfw.schema.character import CharacterProfile
+from authoringfw.schema.world import WorldContext
+from authoringfw.schema.versioning import VersionMetadata, ChangeType
+from authoringfw.formats.base import FormatProfile, WorkflowPhase
+
+__all__ = [
+    "StyleProfile",
+    "CharacterProfile",
+    "WorldContext",
+    "VersionMetadata",
+    "ChangeType",
+    "FormatProfile",
+    "WorkflowPhase",
+    "__version__",
+]

authoringfw-0.1.0/src/authoringfw/adapters/interfaces.py

@@ -0,0 +1,38 @@
+"""Protocol-based adapter interfaces for authoringfw.
+
+Implementations use duck typing — no inheritance required.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from authoringfw.schema.character import CharacterProfile
+from authoringfw.schema.style import StyleProfile
+from authoringfw.schema.world import WorldContext
+
+
+@runtime_checkable
+class IStyleAdapter(Protocol):
+    """Adapter for reading and scoring style profiles."""
+
+    async def get_profile(self, style_id: str) -> StyleProfile: ...
+    async def analyze_text(self, text: str) -> StyleProfile: ...
+    def generate_style_constraints(self, profile: StyleProfile) -> list[str]: ...
+    async def score_conformity(self, text: str, profile: StyleProfile) -> float: ...
+
+
+@runtime_checkable
+class ICharacterAdapter(Protocol):
+    """Adapter for reading character profiles."""
+
+    async def get_character(self, character_id: str) -> CharacterProfile: ...
+    async def list_characters(self, project_id: str) -> list[CharacterProfile]: ...
+
+
+@runtime_checkable
+class IWorldAdapter(Protocol):
+    """Adapter for reading world context."""
+
+    async def get_world(self, world_id: str) -> WorldContext: ...
+    async def list_locations(self, world_id: str) -> list[str]: ...

authoringfw-0.1.0/src/authoringfw/formats/base.py

@@ -0,0 +1,90 @@
+"""Base format profile and workflow phase definitions."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class WorkflowPhase(str, Enum):
+    IDEATION = "ideation"
+    CONCEPT = "concept"
+    OUTLINE = "outline"
+    FIRST_DRAFT = "first_draft"
+    REVISION = "revision"
+    CONSISTENCY = "consistency"
+    PRODUCTION = "production"
+
+
+class StepConfig(BaseModel):
+    """Configuration for a single workflow step."""
+
+    name: str
+    phase: WorkflowPhase
+    prompt_template_id: str
+    max_tokens: int = 2000
+    temperature: float = 0.7
+    requires_human_approval: bool = False
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class FormatProfile(BaseModel):
+    """Defines the writing format and its workflow phases."""
+
+    format_type: str
+    display_name: str
+    description: str = ""
+    phases: list[WorkflowPhase] = Field(
+        default_factory=lambda: list(WorkflowPhase)
+    )
+    steps: list[StepConfig] = Field(default_factory=list)
+    style_constraints: list[str] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    def steps_for_phase(self, phase: WorkflowPhase) -> list[StepConfig]:
+        return [s for s in self.steps if s.phase == phase]
+
+
+ROMAN = FormatProfile(
+    format_type="roman",
+    display_name="Novel",
+    description="Long-form fiction with chapters, characters, and story arcs.",
+    style_constraints=["Show don't tell", "Consistent POV", "Scene & sequel structure"],
+)
+
+ESSAY = FormatProfile(
+    format_type="essay",
+    display_name="Essay",
+    description="Argumentative or descriptive non-fiction prose.",
+    style_constraints=["Clear thesis", "Logical argumentation", "Evidence-based claims"],
+)
+
+SERIE = FormatProfile(
+    format_type="serie",
+    display_name="Series",
+    description="Multi-volume fiction with shared universe and recurring characters.",
+    style_constraints=["Series-wide consistency", "Character continuity", "World-building coherence"],
+)
+
+SCIENTIFIC = FormatProfile(
+    format_type="scientific",
+    display_name="Scientific Paper",
+    description="Academic writing with citations, methodology, and structured sections.",
+    style_constraints=["Objective tone", "Precise terminology", "Citation required"],
+)
+
+FORMAT_REGISTRY: dict[str, FormatProfile] = {
+    "roman": ROMAN,
+    "essay": ESSAY,
+    "serie": SERIE,
+    "scientific": SCIENTIFIC,
+}
+
+
+def get_format(format_type: str) -> FormatProfile:
+    """Get a built-in format profile by type string."""
+    if format_type not in FORMAT_REGISTRY:
+        raise KeyError(f"Unknown format type '{format_type}'. Available: {list(FORMAT_REGISTRY)}")
+    return FORMAT_REGISTRY[format_type]

authoringfw-0.1.0/src/authoringfw/schema/character.py

@@ -0,0 +1,31 @@
+"""Character profile schema for AI-assisted authoring."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class CharacterProfile(BaseModel):
+    """Represents a character in a story universe."""
+
+    name: str
+    role: str = "supporting"
+    description: str = ""
+    personality_traits: list[str] = Field(default_factory=list)
+    backstory: str = ""
+    relationships: dict[str, str] = Field(default_factory=dict)
+    arc: str = ""
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    def to_context_string(self) -> str:
+        """Format character for prompt injection."""
+        lines = [f"**{self.name}** ({self.role})"]
+        if self.description:
+            lines.append(self.description)
+        if self.personality_traits:
+            lines.append(f"Traits: {', '.join(self.personality_traits)}")
+        if self.arc:
+            lines.append(f"Arc: {self.arc}")
+        return "\n".join(lines)

authoringfw-0.1.0/src/authoringfw/schema/style.py

@@ -0,0 +1,30 @@
+"""Style profile schema for AI-assisted authoring."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class StyleProfile(BaseModel):
+    """Defines the stylistic characteristics of a writing project."""
+
+    tone: str = "neutral"
+    pov: str = "third_limited"
+    tense: str = "past"
+    vocabulary_level: str = "medium"
+    sentence_rhythm: str = "varied"
+    author_signature: dict[str, Any] = Field(default_factory=dict)
+
+    model_config = {"frozen": False}
+
+    def to_constraints(self) -> list[str]:
+        """Return a list of natural-language style constraints for prompt injection."""
+        return [
+            f"Tone: {self.tone}",
+            f"Point of view: {self.pov}",
+            f"Tense: {self.tense}",
+            f"Vocabulary level: {self.vocabulary_level}",
+            f"Sentence rhythm: {self.sentence_rhythm}",
+        ]

authoringfw-0.1.0/src/authoringfw/schema/versioning.py

@@ -0,0 +1,55 @@
+"""Versioning schema for AI-generated content snapshots."""
+
+from __future__ import annotations
+
+import hashlib
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ChangeType(str, Enum):
+    AI_GENERATED = "ai_generated"
+    HUMAN_EDITED = "human_edited"
+    MERGED = "merged"
+    REVERTED = "reverted"
+
+
+class VersionMetadata(BaseModel):
+    """Immutable metadata snapshot for a content version."""
+
+    version_id: str
+    semver: str = "1.0.0"
+    phase: str = ""
+    node_id: str = ""
+    change_type: ChangeType = ChangeType.AI_GENERATED
+    author: str = ""
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    parent_version_id: str | None = None
+    content_hash: str = ""
+    prompt_template_id: str = ""
+    prompt_template_version: str = ""
+    llm_model: str = ""
+    llm_temperature: float = 0.7
+    quality_scores: dict[str, Any] = Field(default_factory=dict)
+
+    model_config = {"frozen": True}
+
+    def compute_hash(self, content: str) -> "VersionMetadata":
+        """Return a new instance with content_hash filled in."""
+        h = hashlib.sha256(content.encode()).hexdigest()[:16]
+        return self.model_copy(update={"content_hash": h})
+
+
+class PhaseSnapshot(BaseModel):
+    """A complete snapshot of a project at a workflow phase boundary."""
+
+    snapshot_id: str
+    phase: str
+    project_id: str
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    node_versions: dict[str, str] = Field(default_factory=dict)
+    approved_by: str = ""
+    notes: str = ""

authoringfw-0.1.0/src/authoringfw/schema/world.py

@@ -0,0 +1,42 @@
+"""World context schema for AI-assisted authoring."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class Location(BaseModel):
+    """A location within a story world."""
+
+    name: str
+    description: str = ""
+    atmosphere: str = ""
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class WorldContext(BaseModel):
+    """The story universe — locations, lore, rules, and time period."""
+
+    title: str
+    genre: str = ""
+    setting: str = ""
+    time_period: str = ""
+    world_rules: list[str] = Field(default_factory=list)
+    locations: list[Location] = Field(default_factory=list)
+    lore: str = ""
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    def to_context_string(self) -> str:
+        """Format world context for prompt injection."""
+        lines = [f"World: {self.title}"]
+        if self.genre:
+            lines.append(f"Genre: {self.genre}")
+        if self.setting:
+            lines.append(f"Setting: {self.setting}")
+        if self.time_period:
+            lines.append(f"Time period: {self.time_period}")
+        if self.world_rules:
+            lines.append("Rules: " + "; ".join(self.world_rules))
+        return "\n".join(lines)

authoringfw-0.1.0/tests/test_schema.py

@@ -0,0 +1,99 @@
+"""Tests for authoringfw schema models."""
+
+import pytest
+from pydantic import ValidationError
+
+from authoringfw.schema.style import StyleProfile
+from authoringfw.schema.character import CharacterProfile
+from authoringfw.schema.world import WorldContext, Location
+from authoringfw.schema.versioning import VersionMetadata, ChangeType, PhaseSnapshot
+from authoringfw.formats.base import FormatProfile, WorkflowPhase, get_format
+
+
+def test_style_profile_defaults():
+    s = StyleProfile()
+    assert s.tone == "neutral"
+    assert s.pov == "third_limited"
+
+
+def test_style_profile_to_constraints():
+    s = StyleProfile(tone="dark", pov="first_person", tense="present")
+    constraints = s.to_constraints()
+    assert any("dark" in c for c in constraints)
+    assert any("first_person" in c for c in constraints)
+
+
+def test_character_profile_context_string():
+    c = CharacterProfile(
+        name="Alice",
+        role="protagonist",
+        personality_traits=["brave", "curious"],
+        arc="From fear to courage",
+    )
+    ctx = c.to_context_string()
+    assert "Alice" in ctx
+    assert "brave" in ctx
+    assert "courage" in ctx
+
+
+def test_world_context_to_string():
+    w = WorldContext(
+        title="Middle Earth",
+        genre="fantasy",
+        setting="medieval",
+        world_rules=["Magic exists", "Dragons are rare"],
+    )
+    ctx = w.to_context_string()
+    assert "Middle Earth" in ctx
+    assert "fantasy" in ctx
+    assert "Magic exists" in ctx
+
+
+def test_version_metadata_frozen():
+    v = VersionMetadata(version_id="v1", semver="1.0.0")
+    with pytest.raises(Exception):
+        v.version_id = "v2"
+
+
+def test_version_metadata_compute_hash():
+    v = VersionMetadata(version_id="v1")
+    v2 = v.compute_hash("Hello world content")
+    assert v2.content_hash != ""
+    assert len(v2.content_hash) == 16
+
+
+def test_change_type_values():
+    assert ChangeType.AI_GENERATED == "ai_generated"
+    assert ChangeType.HUMAN_EDITED == "human_edited"
+
+
+def test_get_format_roman():
+    f = get_format("roman")
+    assert f.format_type == "roman"
+    assert len(f.style_constraints) > 0
+
+
+def test_get_format_unknown():
+    with pytest.raises(KeyError) as exc:
+        get_format("nonexistent")
+    assert "nonexistent" in str(exc.value)
+
+
+def test_workflow_phase_values():
+    assert WorkflowPhase.FIRST_DRAFT == "first_draft"
+    assert WorkflowPhase.PRODUCTION == "production"
+
+
+def test_format_profile_steps_for_phase():
+    from authoringfw.formats.base import StepConfig
+    f = FormatProfile(
+        format_type="test",
+        display_name="Test",
+        steps=[
+            StepConfig(name="s1", phase=WorkflowPhase.OUTLINE, prompt_template_id="t1"),
+            StepConfig(name="s2", phase=WorkflowPhase.FIRST_DRAFT, prompt_template_id="t2"),
+        ],
+    )
+    outline_steps = f.steps_for_phase(WorkflowPhase.OUTLINE)
+    assert len(outline_steps) == 1
+    assert outline_steps[0].name == "s1"