seed-data 0.0.2__tar.gz → 0.0.3__tar.gz

seed_data-0.0.3/.github/workflows/docs.yml

@@ -0,0 +1,34 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'src/**'
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --group docs --frozen
+
+      - name: Deploy to GitHub Pages
+        run: |
+          cd docs
+          git config user.name github-actions
+          git config user.email github-actions@github.com
+          uv run mkdocs gh-deploy --force

seed_data-0.0.3/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Publish to PyPI
+
+# Publishes to PyPI when a GitHub Release is published. The package version is
+# whatever is set in pyproject.toml at that commit — bump it before releasing.
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    # Uses PyPI Trusted Publishing (OIDC) — no API token secret is stored.
+    # Requires a one-time setup on PyPI: project -> Manage -> Publishing ->
+    # add a GitHub publisher for this repo, workflow "publish.yml",
+    # and environment "pypi" (see README / release docs).
+    environment: pypi
+    permissions:
+      id-token: write   # required for Trusted Publishing OIDC
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          fetch-depth: 0   # setuptools-scm needs full history and tags to derive the version
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0

seed_data-0.0.3/.github/workflows/test.yml

@@ -0,0 +1,29 @@
+name: Tests
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  pytest:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run tests
+        run: uv run pytest

seed_data-0.0.3/.gitignore

@@ -0,0 +1,52 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+.pytest_cache/
+
+# Security scanner output
+.ash/
+
+# Environment
+.env
+.venv/
+env/
+
+# PDFs / generated output
+output/
+critiques/
+
+# Reference sample documents — never commit these. They are local-only
+# style references for the doc critic and may contain third-party / real
+# content. See any schemas/<type>/samples/README.md for details.
+src/doc_gen_agent/schemas/*/samples/*.pdf
+src/doc_gen_agent/schemas/*/samples/*.png
+src/doc_gen_agent/schemas/*/samples/*.jpg
+src/doc_gen_agent/schemas/*/samples/*.jpeg
+
+# Archives
+*.zip
+
+# MkDocs build output
+docs/site/
+site/
+
+# REPL state
+repl_state/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.vscode/
+.idea/
+
+# Playwright MCP scratch output (screenshots, console/network dumps)
+.playwright-mcp/
+*.log
+.ash/*

seed_data-0.0.3/CODE_OF_CONDUCT.md

@@ -0,0 +1,4 @@
+## Code of Conduct
+This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct).
+For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact
+opensource-codeofconduct@amazon.com with any additional questions or comments.

seed_data-0.0.3/CONTRIBUTING.md

@@ -0,0 +1,172 @@
+# Contributing Guidelines
+
+Thank you for your interest in contributing to Synthetically Engineered Evaluation Data (SEED)! Whether it's a bug report, new feature, correction, or additional documentation, we greatly value feedback and contributions from our community.
+
+Please read through this document before submitting any issues or pull requests to ensure we have all the necessary
+information to effectively respond to your bug report or contribution.
+
+
+## Quick Start for Contributors
+
+### Prerequisites
+
+- Python 3.12+
+- [uv](https://docs.astral.sh/uv/getting-started/installation/) (recommended) or pip
+- Git
+
+WeasyPrint (the default renderer) requires system libraries:
+
+```bash
+# macOS
+brew install pango gdk-pixbuf libffi
+
+# Ubuntu/Debian
+apt-get install libpango-1.0-0 libgdk-pixbuf2.0-0
+```
+
+### Setup
+
+```bash
+# Clone and setup
+git clone https://github.com/awslabs/synthetically-engineered-evaluation-data.git
+cd synthetically-engineered-evaluation-data
+
+# Option 1: uv (recommended)
+uv sync
+
+# Option 2: pip + venv
+pip install -e ".[dev]"
+```
+
+> **Using pip + venv?** If you installed with `pip install -e ".[dev]"`, run the tools directly (e.g., `python scripts/test_unit.py`). If you use uv, prefix commands with `uv run` (e.g., `uv run python scripts/test_unit.py`).
+
+### Development Workflow
+
+1. Create a branch from `develop`: `git checkout -b feature/your-feature develop`
+2. Make your changes
+3. Run the unit tests: `python scripts/test_unit.py`
+4. Run linting: `ruff check .`
+5. Commit with conventional format: `feat: add new feature`
+6. Submit PR to `develop` branch
+
+## Quick Reference
+
+### Common Commands
+
+| Task | Command |
+|------|---------|
+| Run unit tests | `python scripts/test_unit.py` |
+| Run the document generation smoke test | `python scripts/test_doc_gen.py` |
+| Lint check | `ruff check .` |
+| Lint fix | `ruff check --fix .` |
+
+### Commit Message Format
+
+```
+type: brief description
+```
+
+**Types:** `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
+
+### Documentation Contributions
+
+Documentation is built with MkDocs and lives in the `docs/` directory.
+
+```bash
+# Setup and serve docs locally
+cd docs
+make install  # Install dependencies
+make docs     # Start dev server at http://127.0.0.1:8000
+```
+
+When contributing documentation:
+- Edit Markdown files in `docs/docs/`
+- Follow existing structure and style
+- Test locally with `make docs` before submitting a PR
+- Documentation PRs should also target the `develop` branch
+
+---
+
+## Reporting Bugs/Feature Requests
+
+We welcome you to use the GitHub issue tracker to report bugs or suggest features.
+
+When filing an issue, please check existing open, or recently closed, issues to make sure somebody else hasn't already
+reported the issue. Please try to include as much information as you can. Details like these are incredibly useful:
+
+* A reproducible test case or series of steps
+* The version of our code being used
+* Any modifications you've made relevant to the bug
+* Anything unusual about your environment or deployment
+
+
+## Contributing via Pull Requests
+
+Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:
+
+1. You are working against the latest source on the **develop** branch.
+2. You check existing open, and recently merged, pull requests to make sure someone else hasn't addressed the problem already.
+3. You open an issue to discuss any significant work - we would hate for your time to be wasted.
+
+### Pull Request Process
+
+To send us a pull request, please:
+
+1. Fork the repository.
+2. Create a feature branch from the **develop** branch (not main).
+3. Modify the source; please focus on the specific change you are contributing. If you also reformat all the code, it will be hard for us to focus on your change.
+4. Ensure local tests pass.
+5. Commit to your fork using clear commit messages.
+6. **Submit your pull request to the develop branch** (not main).
+7. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.
+
+### Pull Request Template
+
+When creating a pull request, please use the following template to ensure all necessary information is included:
+
+```
+*Issue #, if available:*
+
+*Description of changes:*
+
+
+By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.
+```
+
+### Branch Guidelines
+
+- **All pull requests must target the `develop` branch**
+- The `main` branch is reserved for stable releases; releases are cut via a PR from `develop` to `main`
+- Use descriptive branch names (e.g., `feature/add-new-schema`, `bugfix/fix-memory-leak`)
+- Keep your branch up to date with the latest `develop` branch before submitting
+
+### Commit Message Guidelines
+
+- Use clear and meaningful commit messages
+- Follow the format: `type: brief description`
+- Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
+- Example: `feat: add new document schema`
+
+Refer to [this guide](https://www.conventionalcommits.org/en/v1.0.0/#examples) for clear commit guidelines <br>
+
+GitHub provides additional documentation on [forking a repository](https://help.github.com/articles/fork-a-repo/) and
+[creating a pull request](https://help.github.com/articles/creating-a-pull-request/).
+
+
+## Finding contributions to work on
+Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any 'help wanted' issues is a great place to start.
+
+
+## Code of Conduct
+This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct).
+For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact
+opensource-codeofconduct@amazon.com with any additional questions or comments.
+
+
+## Security issue notifications
+If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our [vulnerability reporting page](https://aws.amazon.com/security/vulnerability-reporting/), or by following the process described in [SECURITY.md](SECURITY.md). Please do **not** create a public GitHub issue.
+
+
+## Licensing
+
+See the [LICENSE](LICENSE) file for our project's licensing. Contributions are made under the Apache-2.0 license. We will ask you to confirm the licensing of your contribution.

seed_data-0.0.3/GETTING_STARTED.md

@@ -0,0 +1,254 @@
+# Getting Started with doc-gen-agent
+
+This guide walks you through creating a new document type and generating your first synthetic documents in under 10 minutes.
+
+## Install
+
+```bash
+conda create -n doc-gen-agent python=3.12 -y
+conda activate doc-gen-agent
+pip install -e .
+```
+
+## Prerequisites: AWS Access
+
+This tool uses Amazon Bedrock to run foundation models. You need an AWS account with Bedrock model access enabled.
+
+Configure your credentials using any method supported by [boto3](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html). We recommend setting up a named profile in `~/.aws/config`:
+
+```bash
+export AWS_PROFILE=your-profile-name
+```
+
+### About BYPASS_TOOL_CONSENT
+
+The Strands Agents SDK prompts for user confirmation before executing tools (like `python_repl`). Since this pipeline runs many tool calls autonomously, set this environment variable to skip those prompts:
+
+```bash
+export BYPASS_TOOL_CONSENT=true
+```
+
+This is safe — the agents only execute code they generate for PDF rendering, and all output is validated by the critic agents. You can omit this flag if you want to manually approve each tool call.
+
+## Step 1: Create a Document Type
+
+Every document type lives in its own directory with at least a `schema.json`. Create one:
+
+```bash
+mkdir -p src/seed_data/schemas/purchase-order
+```
+
+### Write the schema
+
+Create `src/seed_data/schemas/purchase-order/schema.json`:
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Purchase-Order",
+  "description": "A purchase order for goods from a supplier.",
+  "type": "object",
+  "required": ["Buyer", "Supplier", "PONumber", "Items", "Total"],
+  "properties": {
+    "Buyer": { "type": "string", "description": "Company placing the order" },
+    "Supplier": { "type": "string", "description": "Company fulfilling the order" },
+    "PONumber": { "type": "string", "description": "Purchase order number" },
+    "OrderDate": { "type": "string", "description": "Date in YYYY-MM-DD format" },
+    "Items": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["Description", "Quantity", "UnitPrice", "Amount"],
+        "properties": {
+          "Description": { "type": "string" },
+          "Quantity": { "type": "integer" },
+          "UnitPrice": { "type": "number" },
+          "Amount": { "type": "number", "description": "Must equal Quantity * UnitPrice" }
+        }
+      }
+    },
+    "Total": { "type": "number", "description": "Sum of all item Amounts" }
+  }
+}
+```
+
+The `title` field becomes the document type name used in output directories.
+
+### Add steering docs (optional but recommended)
+
+Create `src/seed_data/schemas/purchase-order/generation_guidance.md`:
+
+```markdown
+# Purchase Order — Generation Guidance
+
+## Visual Style
+- Clean business document with company letterhead
+- Table with columns: Item, Qty, Unit Price, Amount
+- Total prominently displayed at bottom right
+- Use 8-10pt body text, compact layout
+
+## Data Realism
+- Buyer: realistic company names (manufacturing, retail, construction)
+- Supplier: realistic vendor names matching the industry
+- PO numbers: format PO-YYYYMMDD-NNN
+- 3-10 line items typical
+- Unit prices: $5-$5,000 range
+
+## Math Rules (CRITICAL)
+- Each item Amount MUST equal Quantity * UnitPrice exactly
+- Total MUST equal sum of all item Amounts
+- All values to 2 decimal places
+```
+
+The pipeline reads all `*.md` files in the directory and injects them into every agent's prompt. This is where you put domain-specific rules — the agents will follow them.
+
+**Want diversity across runs?** Add optional fields with `x-probability` to your
+schema and a `## Layout Variations` section to your guidance. See
+[docs/generation_choices.md](docs/generation_choices.md) for the full guide.
+
+### Add reference samples (optional)
+
+If you have real examples of this document type, drop PDFs into a `samples/` subdirectory:
+
+```
+schemas/purchase-order/
+├── schema.json
+├── generation_guidance.md
+└── samples/
+    ├── real_po_001.pdf
+    └── real_po_002.pdf
+```
+
+The doc critic loads these as visual benchmarks and compares generated documents against them.
+
+## Step 2: Generate a Single Document
+
+```bash
+BYPASS_TOOL_CONSENT=true python -m seed_data \
+  --schema-dir src/seed_data/schemas/purchase-order \
+  --extra "Industrial plumbing supplies for a construction project in Denver"
+```
+
+This runs the full pipeline: data generation → data validation → PDF rendering → visual critique. You'll see each stage's output in the terminal. The final PDF lands in `output/purchase-order/`.
+
+### With image augmentation
+
+Add `--augment` to simulate scanning/faxing artifacts:
+
+```bash
+BYPASS_TOOL_CONSENT=true python -m seed_data \
+  --schema-dir src/seed_data/schemas/purchase-order \
+  --extra "Industrial plumbing supplies" \
+  --augment
+```
+
+This adds two more stages: an augmentor agent picks degradation effects, then an aug critic checks the result is still legible.
+
+## Step 3: Generate a Batch
+
+For training data, you want volume and diversity. The batch script (`scripts/batch_generate.py`)
+runs the pipeline N times in parallel, each with a unique scenario:
+
+```bash
+BYPASS_TOOL_CONSENT=true python scripts/batch_generate.py \
+  --schema-dir src/seed_data/schemas/purchase-order \
+  --extra "Diverse industries ordering from various suppliers across the US" \
+  --count 10 --workers 3 \
+  --batch-name po-training-set \
+  --augment
+```
+
+A scenario generator agent reads your brief and crafts a unique scenario for each
+document — different buyers, suppliers, industries, regions, and order types. Then
+each scenario runs through the full pipeline in parallel via `ThreadPoolExecutor`
+(controlled by `--workers`).
+
+Output goes to `output/po-training-set/`:
+
+```
+output/po-training-set/
+├── pdfs/              # 10 clean PDFs
+├── augmented/         # 10 augmented versions
+├── data/              # 10 JSON data files (ground truth)
+├── generation_scripts/  # The HTML used to render each PDF
+├── config/            # Copy of your schema + guidance for reproducibility
+└── config/batch_manifest.json   # CLI command, git hash, model config, per-doc results
+```
+
+Tips:
+- **Workers vs count**: a single doc takes ~60-100s. With `--count 10 --workers 3`
+  expect ~5-7 minutes wall-clock. Don't set `--workers` higher than 4-5; you'll hit
+  Bedrock rate limits.
+- **Brief specificity matters**: a vague brief produces same-y documents. A specific
+  brief ("CPG brands on local TV stations in the southwest") produces real diversity.
+- **Partial failures are OK**: if 1 of 10 docs fails, the other 9 are still saved.
+  The manifest shows which succeeded.
+
+
+## Step 4: Customize Models
+
+By default, the pipeline uses DeepSeek V3.2 for generation and Haiku for critics. Override per stage:
+
+```bash
+python -m seed_data \
+  --schema-dir src/seed_data/schemas/purchase-order \
+  --extra "Office supplies" \
+  --data-model qwen3-vl \
+  --doc-model deepseek-v3 \
+  --critic-model haiku \
+  --count 5 --batch-name office-supplies
+```
+
+**Constraint:** `--critic-model` must support document/PDF input (currently only Anthropic models: haiku, sonnet, opus). All other model flags can use any available model.
+
+## Step 5: Tune Quality
+
+### Adjust the acceptance threshold
+
+```bash
+--threshold 8    # stricter (more retries, higher quality)
+--threshold 5    # lenient (faster, lower quality)
+```
+
+### Edit steering docs
+
+The fastest way to improve output quality is editing the `*.md` steering files. The agents read these on every run. Common tweaks:
+
+- Add specific layout instructions ("use alternating row colors in tables")
+- Tighten math rules ("tax rate must be between 6% and 10.25%")
+- Add augmentation context ("these documents were faxed in the 1990s")
+- Specify data constraints ("dates must be within the last 90 days")
+
+### Edit prompt templates
+
+For deeper customization, edit the Jinja2 templates in `src/seed_data/prompts/`:
+
+| Template | Controls |
+|----------|----------|
+| `data_generator.j2` | How the LLM generates JSON data |
+| `data_critic.j2` | What the data critic checks for |
+| `doc_generator.j2` | How the LLM writes PDF rendering code |
+| `critic_vision.j2` | What the vision critic evaluates |
+| `augmentor.j2` | Available augmentations and selection rules |
+| `aug_critic.j2` | Augmentation quality criteria |
+
+## Quick Reference
+
+```bash
+# Single doc, defaults
+python -m seed_data --schema-dir schemas/my-type --extra "context"
+
+# Batch of 20 with augmentation
+python scripts/batch_generate.py --schema-dir schemas/my-type \
+  --extra "brief for diversity" --count 20 --workers 3 \
+  --batch-name my-batch --augment
+
+# Use specific models (single-doc; same flags work for batch)
+python -m seed_data --schema-dir schemas/my-type \
+  --data-model nova2-lite --doc-model gpt-oss --critic-model sonnet
+
+# See all options
+python -m seed_data --help
+python scripts/batch_generate.py --help
+python scripts/packet_generate.py --help
+```

seed_data-0.0.3/Makefile

@@ -0,0 +1,34 @@
+# Makefile for Synthetically Engineered Evaluation Data (SEED)
+#
+# Convenience targets for common development tasks. All targets run inside the
+# uv-managed environment; run `make install` first if you have not synced yet.
+
+# Declare phony targets (targets that don't represent files)
+.PHONY: help install test
+
+# help: List the available targets
+#
+# Usage: make help (or just `make`)
+help:
+	@echo "Available targets:"
+	@echo "  make install  Sync the uv environment (including the dev group)"
+	@echo "  make test     Run the unit test suite (integration tests excluded)"
+
+# install: Sync the uv environment
+#
+# Installs all dependencies from uv.lock, including the dev group (pytest, ruff,
+# docs tooling). Requires Python 3.12+.
+#
+# Usage: make install
+install:
+	uv sync
+
+# test: Run the unit test suite
+#
+# Runs pytest inside the uv environment. Integration tests under
+# tests/integration/ are excluded by default (see addopts in pyproject.toml),
+# since they require live AWS credentials.
+#
+# Usage: make test
+test:
+	uv run pytest

{seed_data-0.0.2/src/seed_data.egg-info → seed_data-0.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: seed-data
-Version: 0.0.2
+Version: 0.0.3
 Summary: AI-powered synthetic document generation pipeline for benchmarking document extraction (IDP/KIE) systems
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://github.com/awslabs/synthetically-engineered-evaluation-data

seed_data-0.0.3/SECURITY.md

@@ -0,0 +1,22 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a potential security issue in this project we ask that you notify
+AWS/Amazon Security via our [vulnerability reporting page](https://aws.amazon.com/security/vulnerability-reporting/)
+or directly via email to aws-security@amazon.com.
+
+Please do **not** create a public GitHub issue for security vulnerabilities.
+
+Please include as much of the information listed below as you can to help us
+better understand and resolve the issue:
+
+* The type of issue
+* Full paths of source file(s) related to the manifestation of the issue
+* The location of the affected source code (tag/branch/commit or direct URL)
+* Any special configuration required to reproduce the issue
+* Step-by-step instructions to reproduce the issue
+* Proof-of-concept or exploit code (if possible)
+* Impact of the issue, including how an attacker might exploit the issue
+
+This information will help us triage your report more quickly.