agent-artifact-kit 0.1.0__py3-none-any.whl

agent_artifact_kit-0.1.0.dist-info/METADATA

@@ -0,0 +1,225 @@
+Metadata-Version: 2.5
+Name: agent-artifact-kit
+Version: 0.1.0
+Summary: Shared artifact-creation harness for agentic workflows: renders docx/pptx/xlsx/pdf or delivers arbitrary files, with pluggable destinations and verified writes. Installs as agent-artifact-kit, imports as artifactkit.
+Project-URL: Repository, https://github.com/drimal/artifactkit
+Project-URL: Issues, https://github.com/drimal/artifactkit/issues
+Author: Dipak Rimal
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,artifacts,docx,mcp,pdf,pptx,s3,strands,xlsx
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: openpyxl>=3.1.0
+Requires-Dist: pypdf>=4.0.0
+Requires-Dist: python-docx>=1.1.0
+Requires-Dist: python-pptx>=1.0.0
+Requires-Dist: reportlab>=4.2.0
+Provides-Extra: all
+Requires-Dist: boto3>=1.34.0; extra == 'all'
+Requires-Dist: mcp<2.0.0,>=1.0.0; extra == 'all'
+Requires-Dist: strands-agents; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == 'docs'
+Requires-Dist: mkdocs-material; extra == 'docs'
+Requires-Dist: mkdocstrings[python]; extra == 'docs'
+Requires-Dist: ruff; extra == 'docs'
+Provides-Extra: mcp
+Requires-Dist: mcp<2.0.0,>=1.0.0; extra == 'mcp'
+Provides-Extra: s3
+Requires-Dist: boto3>=1.34.0; extra == 's3'
+Provides-Extra: strands
+Requires-Dist: strands-agents; extra == 'strands'
+Description-Content-Type: text/markdown
+
+# artifactkit
+
+Installs as `agent-artifact-kit`, imports as `artifactkit`
+(same split as `beautifulsoup4` → `bs4`: the PyPI name is descriptive
+for discoverability, the import name is short because that's what you
+actually type in code).
+
+Generic artifact creation harness for agentic workflows. Agents build a
+declarative content spec; artifactkit renders it to docx/pptx/xlsx/pdf,
+writes it to a destination (local disk or S3), verifies the write, and
+returns the location. No agent workflow reimplements this on its own.
+
+## Install
+
+```
+pip install agent-artifact-kit[s3]        # local + S3
+pip install agent-artifact-kit[all]       # + Strands and MCP adapters
+```
+
+All code below imports the package as `artifactkit` regardless of
+which extras you installed.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+pytest tests/ --cov=artifactkit --cov-report=term-missing   # 92% with all extras installed
+```
+
+See `PUBLISHING.md` for how to build and release to PyPI, and
+`mkdocs.yml` / `docs/` for the full documentation site (`pip install
+-e ".[docs]"` then `mkdocs serve`).
+
+## Observability
+
+Every call is logged (structured, correlated by an `operation_id`
+returned on the result) and, if you supply a `MetricsSink`, measured.
+See `docs/observability.md` for the exact log events, fields, and
+metric names, or wire in your own sink:
+
+```python
+from artifactkit import ArtifactService, MetricsSink
+
+class MySink:
+    def increment(self, name, tags=None): ...
+    def timing(self, name, duration_ms, tags=None): ...
+
+service = ArtifactService(metrics=MySink())
+```
+
+## Plain Python
+
+```python
+from artifactkit import (
+    ArtifactService, ArtifactFormat, DocumentSpec, Heading, Paragraph,
+    destination_from_uri,
+)
+
+spec = DocumentSpec(
+    title="Q3 Summary",
+    blocks=(
+        Heading("Overview", level=1),
+        Paragraph.of("Revenue grew 12% quarter over quarter."),
+    ),
+    base_filename="q3_summary",  # optional — bare name, no extension
+)
+
+service = ArtifactService()
+result = service.create(
+    spec,
+    ArtifactFormat.DOCX,
+    destination=destination_from_uri("s3://reports-bucket/q3"),
+    include_presigned_url=True,
+    # filename omitted: resolves to "q3_summary.docx" from spec.base_filename,
+    # adapted to whatever format is requested. Pass filename= explicitly to
+    # override it for this call without changing the spec.
+)
+print(result.location, result.presigned_url)
+```
+
+## Strands agent
+
+```python
+from strands import Agent
+from artifactkit.adapters.strands_tools import create_docx, create_pptx, create_xlsx, create_pdf
+
+agent = Agent(tools=[create_docx, create_pptx, create_xlsx, create_pdf])
+```
+
+## MCP server
+
+```
+python -m artifactkit.adapters.mcp_server
+```
+
+Any MCP-capable agent can then call `create_docx` / `create_pptx` /
+`create_xlsx` / `create_pdf` with a JSON spec, a `destination_uri`, and
+a `filename`.
+
+## Spec shape
+
+See `artifactkit/core/parsing.py` for the exact dict shape each tool
+expects — it's the single source of truth both adapters parse against.
+
+## Styling
+
+Bare output from python-docx/pptx/openpyxl looks exactly like what it
+is: unstyled. Set `theme` on any structured spec for a named preset
+(`Theme.VIBRANT`, `Theme.CORPORATE`, `Theme.MINIMAL`) that each backend
+applies in whatever way fits its format — colored headings and an
+accent rule in a doc, a gradient hero slide with a decorative shape in
+a deck, a native Excel Table with banded rows and a colored tab in a
+workbook. See `docs/quickstart.md` for examples of all three.
+
+## Arbitrary files (code, images, anything else)
+
+`create()` is for structured content that needs rendering (docx/pptx/xlsx/pdf).
+For content you already have, code files, images, data files, whatever,
+use `create_files()` instead. It skips rendering entirely and goes
+straight to write + verify. If you hand it more than 5 files, it
+bundles them into a single `.zip` automatically rather than doing one
+write per file.
+
+Each `RawFile` takes its content one of two ways:
+
+```python
+from artifactkit import ArtifactService, RawFile, FileBundleSpec, destination_from_uri
+
+# In-memory bytes (e.g. code the agent just wrote)
+RawFile("main.py", content=b"print('hello')\n")
+
+# A path already on disk (e.g. output from code that ran, a generated
+# image, anything already written somewhere) -- read lazily at write
+# time, never loaded into memory until it's actually needed.
+RawFile("chart.png", source_path="/tmp/agent_run/chart.png")
+```
+
+If a piece of code produced a whole directory of output, skip
+building `RawFile`s by hand:
+
+```python
+bundle = FileBundleSpec.from_directory("/tmp/agent_run", bundle_filename="run_output")
+service = ArtifactService()
+result = service.create_files(bundle, destination_from_uri("s3://reports-bucket/runs"))
+# 5 or fewer files in the directory -> delivered individually
+# 6+ -> bundled into run_output.zip
+```
+
+Via Strands or MCP, this is the `deliver_files` tool. Each file entry
+needs exactly one of `content_base64` (for content the agent is
+holding directly) or `source_path` (for content already on disk,
+avoids hauling large payloads through the model's context just to
+hand them back to this tool).
+
+**artifactkit never executes code or generates content.** It only
+delivers bytes that already exist. If `app.py` needs to run and
+produce files, that execution happens entirely outside this library,
+with whatever sandboxed runtime the agent already has, and
+`create_files()` picks up only once the output exists on disk.
+
+## Design notes
+
+- Render, validate, and write/verify are three separate stages. Only
+  the write/verify stage retries; render and validate failures are
+  deterministic and retrying wastes time.
+- `ArtifactValidationError` (bad spec/render) and `ArtifactWriteError`
+  (write couldn't be verified) are distinct exception types so a
+  calling agent can choose the right remediation.
+- Destinations are pluggable via the `OutputDestination` protocol.
+  Adding GCS/Azure support means one new class, no changes to backends
+  or the service.
+- `create()` and `create_files()` share the same write/verify/retry/
+  presign machinery (`ArtifactService._write_verified`), the only
+  difference is whether there's a render+validate step first. Arbitrary
+  files skip it because there's no format-specific structure to check
+  on content the caller already fully formed.

agent_artifact_kit-0.1.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+artifactkit/__init__.py,sha256=3FPygYTi1Tu8hWcITwYckBqyTZLd7ehrd_59_eOSkrQ,2193
+artifactkit/adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+artifactkit/adapters/mcp_server.py,sha256=2ukZKZarL4lLhg3uX4l3H8mL3zpVGOmRWX0O_AfTYkk,6194
+artifactkit/adapters/strands_tools.py,sha256=liUv_tNbF8aLTfBolXJt4U9Ii8es_L9zc39wXWRTbLs,7081
+artifactkit/backends/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+artifactkit/backends/docx_backend.py,sha256=mk9I0lv9Wd3cQyiC-dSWM0dYe3AeZtjNCThhdr1jZEU,8074
+artifactkit/backends/pdf_backend.py,sha256=Ln3q5Icn-xX0QBItI-20wf-2kRkVvm2RykhIwYP7Vxc,4657
+artifactkit/backends/pptx_backend.py,sha256=_04-R7mwJqaebG3zZ4OiSwihhEZ24XW0VCxs1eWrU4w,10754
+artifactkit/backends/xlsx_backend.py,sha256=8CABxJqaaDrfm2GdaC5VmYtRrOvrqA3GOqXZ4kZZ56w,6887
+artifactkit/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+artifactkit/core/backend.py,sha256=Lj2Q_U6gqHFSrwcDyZmS36YujpHaiRvQclNEP8e1RZg,1294
+artifactkit/core/destinations.py,sha256=xfTauiy325XSlkFc2erUsLH05GHptoRYmk17hmLEBeU,6632
+artifactkit/core/errors.py,sha256=jKVauleNpXsKOvcF8FncQhqTQyf3fpBZm4guADOlgNA,1302
+artifactkit/core/models.py,sha256=DFZxzFq0ia_lCY4pgYDGicaG2KlCNSyoYODDLBOe14k,15971
+artifactkit/core/observability.py,sha256=Tuq3e_38TcP1RqN5KbV0twgRUFI_8iipC33urJF_uUA,3679
+artifactkit/core/parsing.py,sha256=1hFFCmeOcYX0cfWzeuDIrTDt8Qy2RF9TD0Aq_xyMYi4,5869
+artifactkit/core/registry.py,sha256=grcwYC60n6_ZbibIFxzCznPO__i8zBSvCoKSQzGA40U,1890
+artifactkit/core/retry.py,sha256=jIKmEtUU7SytYbn6jAnvJDhqrk-pGqP7Yv526CfC5-Y,1850
+artifactkit/core/service.py,sha256=2YFoqLniDif-XGeGStqBu8wnix36PC9onlyuMAZerQc,18983
+agent_artifact_kit-0.1.0.dist-info/METADATA,sha256=NB-E-ldoX4ZUcnI_tAON1xvTbKMXlBj-bODBRjUjJW8,8373
+agent_artifact_kit-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+agent_artifact_kit-0.1.0.dist-info/licenses/LICENSE,sha256=_qbBF4PexKUumWJrB_w2myr_zAeNLbbymtVKiD4iR54,1068
+agent_artifact_kit-0.1.0.dist-info/RECORD,,

agent_artifact_kit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agent_artifact_kit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dipak Rimal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

artifactkit/__init__.py

@@ -0,0 +1,89 @@
+"""artifactkit: a shared artifact-creation harness for agentic workflows.
+
+Public API surface — everything an agent or a plain-Python caller
+needs is importable from the top level:
+
+    from artifactkit import (
+        ArtifactService, ArtifactFormat, ArtifactResult,
+        DocumentSpec, PresentationSpec, WorkbookSpec,
+        Heading, Paragraph, ListBlock, Table, Image, PageBreak, TextRun, TextStyle,
+        destination_from_uri,
+        ArtifactError, ArtifactValidationError, ArtifactWriteError,
+    )
+"""
+
+from artifactkit.core.destinations import (
+    LocalDirectoryDestination,
+    OutputDestination,
+    S3Destination,
+    destination_from_uri,
+)
+from artifactkit.core.errors import (
+    ArtifactError,
+    ArtifactValidationError,
+    ArtifactWriteError,
+    DestinationError,
+    UnsupportedFormatError,
+)
+from artifactkit.core.models import (
+    ArtifactFormat,
+    ArtifactSpec,
+    DocumentSpec,
+    FileBundleSpec,
+    Heading,
+    Image,
+    ListBlock,
+    PageBreak,
+    Paragraph,
+    PresentationSpec,
+    Theme,
+    RawFile,
+    Sheet,
+    Slide,
+    Table,
+    TextRun,
+    TextStyle,
+    WorkbookSpec,
+)
+from artifactkit.core.observability import LoggingMetricsSink, MetricsSink, NoOpMetricsSink
+from artifactkit.core.retry import RetryPolicy
+from artifactkit.core.service import ArtifactResult, ArtifactService, FileDeliveryResult
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ArtifactService",
+    "ArtifactResult",
+    "ArtifactFormat",
+    "ArtifactSpec",
+    "RetryPolicy",
+    "DocumentSpec",
+    "Heading",
+    "Paragraph",
+    "ListBlock",
+    "Table",
+    "Image",
+    "PageBreak",
+    "TextRun",
+    "TextStyle",
+    "PresentationSpec",
+    "Theme",
+    "Slide",
+    "WorkbookSpec",
+    "Sheet",
+    "RawFile",
+    "FileBundleSpec",
+    "FileDeliveryResult",
+    "MetricsSink",
+    "NoOpMetricsSink",
+    "LoggingMetricsSink",
+    "OutputDestination",
+    "LocalDirectoryDestination",
+    "S3Destination",
+    "destination_from_uri",
+    "ArtifactError",
+    "ArtifactValidationError",
+    "ArtifactWriteError",
+    "UnsupportedFormatError",
+    "DestinationError",
+]

artifactkit/adapters/mcp_server.py

@@ -0,0 +1,170 @@
+"""FastMCP server exposing artifactkit as MCP tools.
+
+Deliberately duplicates the tool signatures in strands_tools.py rather
+than sharing decorated functions: @tool (Strands) and @mcp.tool
+(FastMCP) wrap differently, and trying to share one decorated function
+across both frameworks is exactly the kind of cross-framework coupling
+this harness exists to avoid at the call site. The logic underneath -
+parse spec, resolve destination, call ArtifactService - is shared via
+core/, which is the actual point of de-duplication.
+
+Run standalone with: python -m artifactkit.adapters.mcp_server
+"""
+
+from __future__ import annotations
+
+from mcp.server.fastmcp import FastMCP
+
+from artifactkit.core.destinations import destination_from_uri
+from artifactkit.core.errors import ArtifactError
+from artifactkit.core.models import ArtifactFormat
+from artifactkit.core.parsing import (
+    parse_document_spec,
+    parse_file_bundle_spec,
+    parse_presentation_spec,
+    parse_workbook_spec,
+)
+from artifactkit.core.service import ArtifactResult, ArtifactService, FileDeliveryResult
+
+mcp = FastMCP("artifactkit")
+_service = ArtifactService()
+
+
+def _result_to_dict(result: ArtifactResult) -> dict:
+    return {
+        "location": result.location,
+        "format": result.format.value,
+        "size_bytes": result.size_bytes,
+        "write_attempts": result.write_attempts,
+        "shareable_url": result.presigned_url,
+        "shareable_url_expires_at": (
+            result.presigned_expires_at.isoformat() if result.presigned_expires_at else None
+        ),
+    }
+
+
+def _delivery_result_to_dict(result: FileDeliveryResult) -> dict:
+    return {
+        "locations": list(result.locations),
+        "bundled": result.bundled,
+        "file_count": result.file_count,
+        "total_size_bytes": result.total_size_bytes,
+        "write_attempts": result.write_attempts,
+        "shareable_url": result.presigned_url,
+        "shareable_url_expires_at": (
+            result.presigned_expires_at.isoformat() if result.presigned_expires_at else None
+        ),
+    }
+
+
+@mcp.tool()
+def create_docx(
+    spec: dict, destination_uri: str, filename: str | None = None, include_shareable_link: bool = False
+) -> dict:
+    """Create a Word document from a structured content spec. See
+    parse_document_spec for the expected spec shape."""
+    try:
+        result = _service.create(
+            parse_document_spec(spec),
+            ArtifactFormat.DOCX,
+            destination_from_uri(destination_uri),
+            filename=filename,
+            include_presigned_url=include_shareable_link,
+        )
+        return _result_to_dict(result)
+    except ArtifactError as exc:
+        return {"error": str(exc), "error_type": type(exc).__name__}
+
+
+@mcp.tool()
+def create_pptx(
+    spec: dict, destination_uri: str, filename: str | None = None, include_shareable_link: bool = False
+) -> dict:
+    """Create a PowerPoint deck from a structured content spec. See
+    parse_presentation_spec for the expected spec shape."""
+    try:
+        result = _service.create(
+            parse_presentation_spec(spec),
+            ArtifactFormat.PPTX,
+            destination_from_uri(destination_uri),
+            filename=filename,
+            include_presigned_url=include_shareable_link,
+        )
+        return _result_to_dict(result)
+    except ArtifactError as exc:
+        return {"error": str(exc), "error_type": type(exc).__name__}
+
+
+@mcp.tool()
+def create_xlsx(
+    spec: dict, destination_uri: str, filename: str | None = None, include_shareable_link: bool = False
+) -> dict:
+    """Create an Excel workbook from a structured content spec. See
+    parse_workbook_spec for the expected spec shape."""
+    try:
+        result = _service.create(
+            parse_workbook_spec(spec),
+            ArtifactFormat.XLSX,
+            destination_from_uri(destination_uri),
+            filename=filename,
+            include_presigned_url=include_shareable_link,
+        )
+        return _result_to_dict(result)
+    except ArtifactError as exc:
+        return {"error": str(exc), "error_type": type(exc).__name__}
+
+
+@mcp.tool()
+def create_pdf(
+    spec: dict, destination_uri: str, filename: str | None = None, include_shareable_link: bool = False
+) -> dict:
+    """Create a PDF from a structured content spec. Uses the same spec
+    shape as create_docx."""
+    try:
+        result = _service.create(
+            parse_document_spec(spec),
+            ArtifactFormat.PDF,
+            destination_from_uri(destination_uri),
+            filename=filename,
+            include_presigned_url=include_shareable_link,
+        )
+        return _result_to_dict(result)
+    except ArtifactError as exc:
+        return {"error": str(exc), "error_type": type(exc).__name__}
+
+
+@mcp.tool()
+def deliver_files(
+    files: list[dict],
+    destination_uri: str,
+    bundle_filename: str | None = None,
+    zip_threshold: int = 5,
+    include_shareable_link: bool = False,
+) -> dict:
+    """Deliver an arbitrary set of files (code, images, data, anything
+    with content already in hand) to destination_uri. No rendering
+    happens; each file's content is written as-is.
+
+    If more than zip_threshold files are given (default 5), they are
+    bundled into a single .zip and delivered as one artifact instead
+    of one write per file.
+
+    files shape: [{"filename": "app.py", "content_base64": "..."}, ...]
+    Each entry needs exactly one of content_base64 (base64-encoded
+    bytes) or source_path (a path already on disk).
+    """
+    try:
+        bundle_spec = parse_file_bundle_spec({"files": files, "bundle_filename": bundle_filename})
+        result = _service.create_files(
+            bundle_spec,
+            destination_from_uri(destination_uri),
+            zip_threshold=zip_threshold,
+            include_presigned_url=include_shareable_link,
+        )
+        return _delivery_result_to_dict(result)
+    except ArtifactError as exc:
+        return {"error": str(exc), "error_type": type(exc).__name__}
+
+
+if __name__ == "__main__":
+    mcp.run()