asta-artifact 1.0.0__tar.gz

asta_artifact-1.0.0/.gitignore

@@ -0,0 +1,136 @@
+# =========================
+# OS / System files
+# =========================
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+# =========================
+# Editor / IDE files
+# =========================
+.vscode/
+.idea/
+*.swp
+*.swo
+*.swn
+*~
+*.bak
+*.tmp
+*.orig
+
+# =========================
+# Logs
+# =========================
+logs/
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# =========================
+# Environment variables / secrets
+# =========================
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+*.crt
+
+# =========================
+# Build / dist artifacts
+# =========================
+dist/
+build/
+out/
+target/
+bin/
+obj/
+
+# =========================
+# Dependency directories
+# =========================
+node_modules/
+vendor/
+.venv/
+venv/
+env/
+__pycache__/
+
+# Yarn
+**/.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions
+.pnp.*
+
+# =========================
+# Test / coverage output
+# =========================
+coverage/
+.coverage
+.nyc_output/
+test-results/
+pytest_cache/
+
+# =========================
+# Temporary / cache files
+# =========================
+.cache/
+.tmp/
+.temp/
+*.cache
+
+# =========================
+# Archive files
+# =========================
+*.zip
+*.tar
+*.tar.gz
+*.rar
+*.7z
+
+# =========================
+# Runtime files
+# =========================
+*.pid
+*.seed
+*.pid.lock
+
+# =========================
+# Misc
+# =========================
+*.lock
+!.gitignore
+
+# =========================
+# Terraform
+# =========================
+*.tfstate
+*.tfstate.*
+.terraform/
+.terraform.lock.hcl
+infra/terraform.tfvars
+
+# =========================
+# Generated deploy files
+# =========================
+_asta_modal_*.py
+
+# =========================
+# Python packaging
+# =========================
+*.egg-info/
+
+# =========================
+# Claude Code worktrees
+# =========================
+.claude/worktrees/

asta_artifact-1.0.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: asta-artifact
+Version: 1.0.0
+Summary: Asta artifact builder, models, content blocks, and HTML exporter
+Requires-Python: >=3.10
+Requires-Dist: asta-types
+Requires-Dist: markdown>=3.4
+Requires-Dist: pydantic>=2.0
+Provides-Extra: cli
+Requires-Dist: click>=8.0; extra == 'cli'

asta_artifact-1.0.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "asta-artifact"
+version = "1.0.0"
+description = "Asta artifact builder, models, content blocks, and HTML exporter"
+requires-python = ">=3.10"
+dependencies = [
+    "markdown>=3.4",
+    "pydantic>=2.0",
+    "asta-types",
+]
+
+[tool.uv.sources]
+asta-types = { path = "../types" }
+
+[project.optional-dependencies]
+cli = ["click>=8.0"]
+
+[project.scripts]
+artifacts = "asta_artifact.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/asta_artifact"]

asta_artifact-1.0.0/src/asta_artifact/__init__.py

@@ -0,0 +1,60 @@
+from .models import (
+    _AstaModel,
+    AnnotationType,
+    S2Author,
+    ContentBlockType,
+    DisplayText,
+    EntityType,
+    Facet,
+    Paper,
+    S2Paper,
+    Snippet,
+    paper_tag,
+)
+
+from .content import (
+    Code,
+    Figure,
+    Markdown,
+    Section,
+    SectionContext,
+    Sections,
+    SectionsContext,
+)
+
+from .artifact import Artifact
+from .exporter import (
+    ArtifactExporter,
+    export_artifact_to_html,
+    export_artifacts_to_html_directory,
+)
+
+__all__ = [
+    # Enums
+    "EntityType",
+    "AnnotationType",
+    "ContentBlockType",
+    # Entity models
+    "S2Author",
+    "S2Paper",
+    "Paper",
+    # Annotation models
+    "Snippet",
+    "Facet",
+    "DisplayText",
+    "paper_tag",
+    # Content blocks
+    "Section",
+    "Sections",
+    "Markdown",
+    "Figure",
+    "Code",
+    "SectionContext",
+    "SectionsContext",
+    # Builder
+    "Artifact",
+    # Exporter
+    "ArtifactExporter",
+    "export_artifact_to_html",
+    "export_artifacts_to_html_directory",
+]

asta_artifact-1.0.0/src/asta_artifact/artifact.py

@@ -0,0 +1,281 @@
+"""Artifact builder producing canonical format::
+
+    {
+        "id": "...", "name": "...", "description": "...",
+        "entities": {"paper-1": {id, type, displayLabel, s2Metadata}},
+        "annotations": {"ann-1": {id, type, entityId, text, ...}},
+        "content": [{id, type, title, childIds}, {id, type, text}, ...]
+    }
+"""
+
+from __future__ import annotations
+
+import json
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any
+
+from .models import (
+    Annotation,
+    AnnotationType,
+    DisplayText,
+    EntityType,
+    Facet,
+    Paper,
+    S2Paper,
+    Snippet,
+)
+from .content import (
+    ContentBlock,
+    Markdown,
+    Section,
+    SectionContext,
+    Sections,
+    SectionsContext,
+    content_block_from_dict,
+)
+
+
+class Artifact:
+    """Asta artifact with structured content, annotations, and entities."""
+
+    def __init__(self, artifact_id: str, name: str,
+                 description: str | None = None):
+        if not artifact_id:
+            raise ValueError("artifact_id is required")
+        if not name:
+            raise ValueError("name is required")
+
+        self._id = artifact_id
+        self._name = name
+        self._description = description
+
+        self._content: list[ContentBlock] = []
+        self._entities: dict[str, Paper] = {}
+        self._annotations: dict[str, Annotation] = {}
+
+        self._content_counter = 0
+        self._entity_counter = 0
+        self._annotation_counter = 0
+
+    @property
+    def id(self) -> str:
+        return self._id
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def description(self) -> str | None:
+        return self._description
+
+    @property
+    def content(self) -> list[ContentBlock]:
+        return self._content
+
+    @property
+    def entities(self) -> dict[str, Paper]:
+        return self._entities
+
+    @property
+    def annotations(self) -> dict[str, Annotation]:
+        return self._annotations
+
+    def _next_content_id(self) -> str:
+        self._content_counter += 1
+        return f"c_{self._content_counter:03d}"
+
+    def _next_entity_id(self) -> str:
+        self._entity_counter += 1
+        return f"ent_{self._entity_counter:03d}"
+
+    def _next_annotation_id(self) -> str:
+        self._annotation_counter += 1
+        return f"ann_{self._annotation_counter:03d}"
+
+    def _update_counter(self, counter_attr: str, id_str: str) -> None:
+        """Update a counter to avoid ID collisions after loading."""
+        try:
+            num = int(id_str.split("_")[1])
+            setattr(self, counter_attr, max(getattr(self, counter_attr), num))
+        except (IndexError, ValueError):
+            pass
+
+    # --- Entity Methods ---
+
+    def add_paper_entity(self, display_label: str,
+                         s2_metadata: S2Paper | dict | None = None,
+                         entity_id: str | None = None) -> str:
+        """Add a Paper entity and return its ID."""
+        entity_id = entity_id or self._next_entity_id()
+        if isinstance(s2_metadata, dict):
+            s2_metadata = S2Paper.model_validate(s2_metadata)
+        entity = Paper(
+            id=entity_id,
+            display_label=display_label,
+            s2_metadata=s2_metadata,
+        )
+        self._entities[entity_id] = entity
+        return entity_id
+
+    # --- Annotation Methods ---
+
+    def add_snippet(self, entity_id: str, text: str = "",
+                    heading: str | None = None,
+                    sentence_id: str | None = None) -> str:
+        """Add a Snippet annotation and return its ID.
+
+        To link the snippet to a content block, append the returned ID
+        to the block's ``annotation_ids`` list.
+        """
+        ann_id = self._next_annotation_id()
+        ann = Snippet(
+            id=ann_id, entity_id=entity_id,
+            text=text, heading=heading, sentence_id=sentence_id,
+        )
+        self._annotations[ann_id] = ann
+        return ann_id
+
+    def add_facet(self, entity_id: str, name: str = "",
+                  value: str | int | float | bool = "") -> str:
+        """Add a Facet annotation and return its ID."""
+        ann_id = self._next_annotation_id()
+        ann = Facet(
+            id=ann_id, entity_id=entity_id,
+            name=name, value=value,
+        )
+        self._annotations[ann_id] = ann
+        return ann_id
+
+    def add_display_text(self, entity_id: str, text: str = "") -> str:
+        """Add a DisplayText annotation and return its ID."""
+        ann_id = self._next_annotation_id()
+        ann = DisplayText(
+            id=ann_id, entity_id=entity_id,
+            text=text,
+        )
+        self._annotations[ann_id] = ann
+        return ann_id
+
+    # --- Content Methods ---
+
+    def markdown(self, text: str) -> Markdown:
+        """Add a top-level markdown block (not inside a section)."""
+        content_id = self._next_content_id()
+        block = Markdown(id=content_id, text=text)
+        self._content.append(block)
+        return block
+
+    def table(self, headers: list[str], rows: list[list[str]]) -> Markdown:
+        """Add a top-level markdown table."""
+        from .content import SectionContext
+        # Reuse SectionContext's table logic without a section
+        def _esc(v: str) -> str:
+            return str(v).replace("|", "\\|").replace("\n", " ")
+        lines = [
+            "| " + " | ".join(headers) + " |",
+            "| " + " | ".join("---" for _ in headers) + " |",
+        ]
+        for row in rows:
+            lines.append("| " + " | ".join(_esc(v) for v in row) + " |")
+        return self.markdown("\n".join(lines))
+
+    @contextmanager
+    def section(self, title: str, description: str | None = None,
+                section_id: str | None = None):
+        """Create a section and yield a SectionContext for adding content."""
+        content_id = section_id or self._next_content_id()
+        sec = Section(id=content_id, title=title, description=description)
+        self._content.append(sec)
+        ctx = SectionContext(self, sec)
+        yield ctx
+
+    @contextmanager
+    def sections(self, title: str):
+        """Create a SECTIONS container and yield a SectionsContext."""
+        content_id = self._next_content_id()
+        block = Sections(id=content_id, title=title)
+        self._content.append(block)
+        ctx = SectionsContext(self, block)
+        yield ctx
+
+    # --- Export ---
+
+    def to_dict(self) -> dict:
+        """Export as a dictionary matching the canonical schema."""
+        result: dict[str, Any] = {
+            "id": self._id,
+            "name": self._name,
+        }
+
+        if self._description:
+            result["description"] = self._description
+
+        result["entities"] = {
+            eid: e.to_dict() for eid, e in self._entities.items()
+        }
+        result["annotations"] = {
+            aid: a.to_dict() for aid, a in self._annotations.items()
+        }
+        result["content"] = [block.to_dict() for block in self._content]
+
+        return result
+
+    def to_json(self, indent: int = 2) -> str:
+        return json.dumps(self.to_dict(), indent=indent)
+
+    # --- Load from existing ---
+
+    @classmethod
+    def load(cls, path: str | Path) -> Artifact:
+        """Load an artifact from a JSON file."""
+        path = Path(path)
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        return cls.from_dict(data)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> Artifact:
+        """Create an Artifact from a canonical dictionary or A2A envelope."""
+        # Unwrap A2A envelope if present
+        if "artifactId" in data and "parts" in data:
+            part = data["parts"][0]
+            data = part["data"] if isinstance(part, dict) else part.root.data
+        builder = cls(
+            artifact_id=data["id"],
+            name=data["name"],
+            description=data.get("description"),
+        )
+
+        # Load content
+        for block_data in data.get("content", []):
+            block = content_block_from_dict(block_data)
+            builder._content.append(block)
+            builder._update_counter("_content_counter", block.id)
+
+        # Load entities
+        for entity_id, entity_data in data.get("entities", {}).items():
+            entity_type = entity_data.get("type")
+            if entity_type == EntityType.PAPER.value:
+                entity = Paper.from_dict(entity_data)
+            else:
+                raise ValueError(f"Unknown entity type: {entity_type}")
+            builder._entities[entity_id] = entity
+            builder._update_counter("_entity_counter", entity_id)
+
+        # Load annotations
+        for ann_id, ann_data in data.get("annotations", {}).items():
+            ann_type = ann_data.get("type")
+            if ann_type == AnnotationType.SNIPPET.value:
+                ann = Snippet.from_dict(ann_data)
+            elif ann_type == AnnotationType.FACET.value:
+                ann = Facet.from_dict(ann_data)
+            elif ann_type == AnnotationType.DISPLAY_TEXT.value:
+                ann = DisplayText.from_dict(ann_data)
+            else:
+                raise ValueError(f"Unknown annotation type: {ann_type}")
+            builder._annotations[ann_id] = ann
+            builder._update_counter("_annotation_counter", ann_id)
+
+        return builder

asta_artifact-1.0.0/src/asta_artifact/cli.py

@@ -0,0 +1,77 @@
+"""Artifacts CLI — export A2A task artifacts to various formats.
+
+Usage:
+    artifacts --input test-output/ --output export/
+    artifacts --input test-output/ --output export/ --format html
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+import click
+
+from asta_artifact import Artifact
+from asta_artifact.exporter import export_artifacts_to_html_directory
+
+
+def _load_artifacts_from_dir(input_dir: str) -> list[Artifact]:
+    """Load artifacts from all JSON files in a directory."""
+    artifacts = []
+    for fname in sorted(os.listdir(input_dir)):
+        if not fname.endswith(".json"):
+            continue
+        path = os.path.join(input_dir, fname)
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        # Support both raw artifact dicts and A2A envelopes with parts
+        if "artifacts" in data:
+            for art_data in data["artifacts"]:
+                if "parts" in art_data:
+                    for part in art_data["parts"]:
+                        part_data = part.get("data") or part
+                        if "entities" in part_data and "content" in part_data:
+                            artifacts.append(Artifact.from_dict(part_data))
+                elif "entities" in art_data and "content" in art_data:
+                    artifacts.append(Artifact.from_dict(art_data))
+        elif "parts" in data:
+            for part in data["parts"]:
+                part_data = part.get("data") or part
+                if "entities" in part_data and "content" in part_data:
+                    artifacts.append(Artifact.from_dict(part_data))
+        elif "entities" in data and "content" in data:
+            artifacts.append(Artifact.from_dict(data))
+    return artifacts
+
+
+@click.command()
+@click.option("--input", "input_dir", required=True,
+              help="Directory containing result JSON files")
+@click.option("--output", "output_dir", required=True,
+              help="Directory to write exported files")
+@click.option("--format", "fmt", default="html",
+              type=click.Choice(["html"]),
+              help="Output format (default: html)")
+def main(input_dir: str, output_dir: str, fmt: str) -> None:
+    """Export A2A task artifacts to HTML."""
+    if not os.path.isdir(input_dir):
+        click.echo(f"Error: {input_dir} is not a directory")
+        sys.exit(1)
+
+    artifacts = _load_artifacts_from_dir(input_dir)
+    if not artifacts:
+        click.echo(f"Error: no artifacts found in {input_dir}")
+        sys.exit(1)
+
+    click.echo(f"Loaded {len(artifacts)} artifacts from {input_dir}")
+
+    if fmt == "html":
+        export_artifacts_to_html_directory(artifacts, output_dir)
+
+    click.echo(f"Exported to {output_dir}")
+
+
+if __name__ == "__main__":
+    main()