agent-artifact-kit 0.1.0__tar.gz

agent_artifact_kit-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+*.egg-info/
+.pytest_cache/
+.venv/
+venv/
+dist/
+build/
+.coverage
+htmlcov/

agent_artifact_kit-0.1.0/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.

agent_artifact_kit-0.1.0/PKG-INFO

@@ -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/PUBLISHING.md

@@ -0,0 +1,70 @@
+# Publishing artifactkit to PyPI
+
+## First-time setup
+
+1. Confirm the name is still free: https://pypi.org/project/agent-artifact-kit/
+   (a text search can miss a reserved-but-empty name -- check the URL directly)
+2. Create a PyPI account and, separately, a TestPyPI account: https://pypi.org/account/register/
+3. Fix the placeholder URLs in `pyproject.toml` (`[project.urls]`) once the
+   repo has a real home -- PyPI displays these on the project page.
+4. Recommended: use Trusted Publishing (OIDC from GitHub Actions) instead of
+   a long-lived API token: https://docs.pypi.org/trusted-publishers/
+   If publishing manually instead, generate a scoped API token under
+   PyPI account settings and use `__token__` as the username when prompted.
+
+Note the name split: the PyPI/distribution name is
+`agent-artifact-kit` (set in `pyproject.toml`'s `[project] name`),
+but the importable package stays `artifactkit` (`[tool.hatch.build.targets.wheel]`
+still points at the `artifactkit/` directory). Don't rename one without
+checking the other -- `pip install agent-artifact-kit` should
+always leave you with `import artifactkit` working, and the `all` extra's
+self-reference (`agent-artifact-kit[s3,strands,mcp]`) must use
+the distribution name, not the import name, or extras resolution breaks.
+
+## Documentation
+
+```bash
+pip install -e ".[docs]"
+mkdocs serve          # live preview at http://127.0.0.1:8000
+mkdocs build --strict # what CI should run before merging docs changes
+```
+
+`--strict` turns warnings (broken `::` autodoc references, bad internal
+links) into build failures — always run it before publishing, not just
+`mkdocs build`.
+
+## Every release
+
+```bash
+# from the package root
+pip install --upgrade build twine
+
+# 1. bump version in pyproject.toml, then:
+rm -rf dist/
+python -m build
+twine check dist/*          # catches metadata/README rendering problems
+                             # before they reach PyPI
+
+# 2. dry run against TestPyPI first
+twine upload --repository testpypi dist/*
+pip install --index-url https://test.pypi.org/simple/ agent-artifact-kit
+
+# 3. the real upload
+twine upload dist/*
+```
+
+## Before the first real upload
+
+- Run the test suite: `pytest tests/ -v` (87 tests with all extras
+  installed; 78 pass + 9 skip cleanly without `[strands]`/`[mcp]`)
+- Run `pytest --cov=artifactkit` if you want a coverage number to publish
+- Confirm `pip install agent-artifact-kit[all]` in a fresh venv pulls everything
+  cleanly (this is what a new user's first experience will be)
+- Double check `LICENSE` and the `authors` field in `pyproject.toml` reflect
+  who should actually be listed
+
+## Versioning
+
+`pyproject.toml` version is the single source of truth. There is no
+dynamic versioning configured, so bump it by hand before each release
+and tag the commit to match (`git tag v0.1.1`).

agent_artifact_kit-0.1.0/README.md

@@ -0,0 +1,177 @@
+# 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/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",
+]