deepagents-printshop 0.1.0__tar.gz

deepagents_printshop-0.1.0/.env.example

@@ -0,0 +1,11 @@
+# DeepAgents API Keys
+# Copy this file to .env and fill in your API keys
+
+# Required: Anthropic API key for Claude
+ANTHROPIC_API_KEY=your_anthropic_api_key_here
+
+# Optional: OpenAI API key (alternative to Anthropic)
+OPENAI_API_KEY=your_openai_api_key_here
+
+# Optional: Tavily API key for web search functionality
+TAVILY_API_KEY=your_tavily_api_key_here

deepagents_printshop-0.1.0/.gitattributes

@@ -0,0 +1,10 @@
+# Binary files
+*.pdf binary
+*.png binary
+*.jpg binary
+*.jpeg binary
+
+# Large file tracking (enable if using Git LFS)
+# *.pdf filter=lfs diff=lfs merge=lfs -text
+# *.png filter=lfs diff=lfs merge=lfs -text
+# *.jpg filter=lfs diff=lfs merge=lfs -text

deepagents_printshop-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,18 @@
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Test
+        run: pytest tests/ -v

deepagents_printshop-0.1.0/.gitignore

@@ -0,0 +1,84 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Test and Development Files (root-level ad-hoc scripts only; tests/ dir is tracked)
+/test_*.py
+/demo_*.py
+/debug_*.py
+/*_test.py
+MILESTONE_*.md
+*SUMMARY.md
+
+# Virtual Environment
+venv/
+ENV/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Environment variables
+.env
+
+# DeepAgents
+.deepagents/
+
+# Claude Code
+.claude/
+
+# LaTeX
+*.aux
+*.log
+*.out
+*.toc
+*.bbl
+*.blg
+*.fls
+*.fdb_latexmk
+*.synctex.gz
+
+# Output files and directories (generated content)
+artifacts/output/*
+artifacts/visual_qa/*
+artifacts/reviewed_content/*
+artifacts/version_history/
+artifacts/agent_reports/*
+!artifacts/output/.gitkeep
+!artifacts/visual_qa/.gitkeep
+!artifacts/reviewed_content/.gitkeep
+!artifacts/agent_reports/quality/.gitkeep
+!artifacts/agent_reports/orchestration/.gitkeep
+
+# Keep input content
+!artifacts/sample_content/
+
+# OS
+.DS_Store
+Thumbs.db
+nul
+
+# Docker
+.dockerignore

deepagents_printshop-0.1.0/CLAUDE.md

@@ -0,0 +1,200 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+DeepAgents PrintShop is a document generation system that produces professional LaTeX documents with comprehensive formatting, citations, tables, images, and diagrams. It uses the DeepAgents CLI framework, LangGraph for pipeline orchestration, and runs in Docker with TeX Live for PDF compilation.
+
+**Important: Do not hardcode LaTeX output into deterministic Python logic.** Rendering behavior is controlled by natural language instructions in `content_types/*/type.md` files, which the LaTeX agent reads at generation time. To change how a document looks (disclaimers, footers, spacing, section formatting), edit the type.md rendering instructions — not the Python code.
+
+## Common Commands
+
+### Running the Pipeline
+```bash
+# Full QA pipeline (content editing → LaTeX generation → Visual QA)
+python agents/qa_orchestrator/agent.py
+
+# Run individual agents
+python agents/content_editor/versioned_agent.py
+python agents/latex_specialist/agent.py
+python agents/visual_qa/agent.py
+
+# Run tests
+python -m pytest tests/ -v
+```
+
+### Development Environment
+```bash
+# Build and run Docker container
+docker-compose build
+docker-compose run --rm deepagents-printshop
+
+# Run the QA pipeline inside Docker
+docker-compose run --rm deepagents-printshop python agents/qa_orchestrator/agent.py
+
+# Access container shell
+docker-compose run --rm deepagents-printshop bash
+```
+
+### LaTeX/PDF Operations
+```bash
+# Manual PDF compilation (requires texlive)
+pdflatex artifacts/output/research_report.tex
+
+# Test LaTeX generator import
+python -c "from tools.latex_generator import LaTeXGenerator; print('LaTeX generator loaded')"
+
+# Test PDF compiler
+python -c "from tools.pdf_compiler import PDFCompiler; PDFCompiler().compile_pdf('artifacts/output/research_report.tex')"
+```
+
+## Prerequisites
+
+**LaTeX Distribution Required**: PDF compilation requires a LaTeX distribution. The Docker container includes TeX Live, but if running outside Docker:
+- **Windows**: [MiKTeX](https://miktex.org/)
+- **macOS**: [MacTeX](https://www.tug.org/mactex/) or `brew install --cask mactex`
+- **Linux**: TeX Live via `apt install texlive-full` or equivalent
+
+Without a LaTeX distribution, the system can generate `.tex` files but cannot compile them to PDF.
+
+## Architecture
+
+### Pipeline (LangGraph StateGraph)
+
+The QA orchestrator (`agents/qa_orchestrator/agent.py`) runs a LangGraph StateGraph with three stages, each gated by a quality threshold:
+
+1. **Content Editor** (gate: 80) — Reviews markdown for grammar, academic tone, readability. Iterates up to 4 times.
+2. **LaTeX Specialist** (gate: 85) — Converts edited markdown to `.tex` using config manifest and content type instructions. Applies automated optimizations.
+3. **Visual QA** (gate: 80) — Compiles PDF, renders pages as images, uses Claude vision to find formatting issues, applies fixes. Iterates up to 3 times.
+
+Each stage creates versioned artifacts in `artifacts/reviewed_content/` (e.g., `v0_original`, `v1_content_edited`, `v2_latex_optimized`, `v3_visual_qa`). Pipeline reports are saved to `artifacts/agent_reports/`.
+
+### Core Components
+
+**agents/qa_orchestrator/agent.py**: Main pipeline entry point. Orchestrates the LangGraph workflow with quality gates and iteration limits.
+
+**agents/qa_orchestrator/langgraph_workflow.py**: LangGraph StateGraph definition with conditional edges for quality gate decisions.
+
+**agents/content_editor/versioned_agent.py**: Content editing agent that reviews and improves markdown files using Claude. Scores content on grammar, readability (Flesch Reading Ease), and academic tone.
+
+**agents/latex_specialist/latex_optimizer.py**: Core LaTeX generation logic. Converts markdown to LaTeX using LLM, processes inline references (`<!-- IMAGE: -->`, `<!-- CSV_TABLE: -->`, `<!-- TIKZ: -->`), sanitizes Unicode for pdflatex, and applies automated optimizations. This is where most LaTeX logic lives.
+
+**agents/visual_qa/agent.py**: Compiles PDF, renders pages to images, inspects with Claude vision, and applies targeted LaTeX fixes.
+
+**tools/latex_generator.py**: LaTeXGenerator class with DocumentConfig for building LaTeX document structure (preamble, sections, tables, figures).
+
+**tools/pdf_compiler.py**: PDFCompiler class for LaTeX-to-PDF conversion with multi-pass compilation.
+
+**tools/content_type_loader.py**: Loads content type definitions from `content_types/` directory.
+
+### Content Types
+
+Content type definitions live in `content_types/<type_id>/type.md`. Each file contains:
+- **Type metadata**: document class, font size, paper size
+- **Rendering instructions**: Natural language instructions that the LaTeX agent follows when generating the document (disclaimers, headers/footers, typography, table formatting, figure placement, citation style, etc.)
+- **LaTeX requirements**: Required packages and preamble configuration
+- **Structure rules**: Constraints for valid output
+
+To change how a document renders, edit the rendering instructions in the appropriate type.md file. The LaTeX agent reads these at generation time.
+
+### Sample Content Structure
+
+Each sample content directory (`artifacts/sample_content/<type_id>/`) contains:
+- **config.md**: Document metadata (title, author, abstract) and a content manifest listing sections in order
+- **Section files**: Markdown files referenced by the manifest (e.g., `introduction.md`, `results.md`)
+- **images/**: Images referenced by inline `<!-- IMAGE: -->` comments in markdown
+- **data/**: CSV files referenced by inline `<!-- CSV_TABLE: -->` comments in markdown
+
+### Inline Reference Syntax
+
+Markdown content files use HTML comments to reference external assets. The LaTeX optimizer processes these into proper LaTeX:
+
+```markdown
+<!-- IMAGE: path=images/chart.png, caption=Performance Chart, label=fig:chart -->
+
+<!-- CSV_TABLE: path=data/results.csv, caption=Model Results, label=tab:results -->
+
+<!-- TIKZ:
+caption: Neural Network Architecture
+label: fig:neural_net
+code:
+\node[circle, draw] (input) at (0,0) {Input};
+\node[circle, draw] (output) at (3,0) {Output};
+\draw[->] (input) -- (output);
+-->
+```
+
+### Data Flow
+
+1. Orchestrator loads content from `artifacts/sample_content/<type_id>/`
+2. Content editor iteratively improves markdown files, saving versions to `artifacts/reviewed_content/`
+3. LaTeX specialist reads the final edited markdown + config manifest + content type instructions, generates `.tex`
+4. LaTeX optimizer processes inline references (images, CSV tables, TikZ), sanitizes Unicode, applies formatting fixes
+5. Visual QA compiles PDF, inspects rendered pages, applies fixes, recompiles
+6. Final output saved to `artifacts/output/<run_id>/`
+
+### Memory System
+
+DeepAgents persistent memory stored in `.deepagents/`:
+
+**Research Agent** (`.deepagents/research_agent/memories/`):
+- `latex_knowledge.md`: LaTeX best practices and patterns
+- `report_structure.md`: Research report structure templates
+- `artifacts_tracking.md`: Artifact and content management
+
+**Content Editor Agent** (`.deepagents/content_editor/memories/`):
+- `grammar_rules.md`: Grammar and style correction rules
+- `readability_patterns.md`: Readability improvement patterns
+- `quality_metrics.md`: Content quality scoring criteria
+
+### Configuration
+
+**DocumentConfig** (tools/latex_generator.py): Controls document class, formatting, headers/footers, bibliography, and layout options.
+
+**Environment**: Uses `.env` file for ANTHROPIC_API_KEY, Docker volumes for persistence.
+
+## Development Patterns
+
+### Adding New Content Types
+1. Create `content_types/<type_id>/type.md` with metadata, rendering instructions, and LaTeX requirements
+2. Create `artifacts/sample_content/<type_id>/` with `config.md` and section markdown files
+3. Add images to `artifacts/sample_content/<type_id>/images/` and CSV data to `data/`
+4. Reference assets from markdown using inline `<!-- IMAGE: -->`, `<!-- CSV_TABLE: -->`, or `<!-- TIKZ: -->` comments
+
+### Changing Document Appearance
+- Edit `content_types/<type_id>/type.md` rendering instructions (preferred — changes are picked up by the LLM at generation time)
+- For structural changes to inline reference processing: edit `agents/latex_specialist/latex_optimizer.py`
+- For changes to the LaTeX document builder: edit `tools/latex_generator.py`
+- Add new LaTeX packages to Dockerfile if needed
+
+### Quality Tuning
+- Quality gate thresholds: `agents/qa_orchestrator/quality_gates.py`
+- Content scoring (Flesch readability, grammar): `agents/content_editor/content_reviewer.py`
+- LaTeX scoring (structure, typography, tables/figures, best practices): `agents/latex_specialist/latex_optimizer.py`
+- Iteration limits: `agents/qa_orchestrator/langgraph_workflow.py`
+
+### Pipeline Status Reporting
+- **Completed / Human Handoff Ready**: All quality gates passed. Report as "completed successfully."
+- **Escalated**: Pipeline hit iteration limits or quality gates were not met. Report as "completed with issues" and note what failed (e.g., visual QA score plateaued below threshold). Do NOT call this a successful run.
+- **Failed**: A stage crashed or errored out. Report as "failed" with the error.
+
+### Known Gotchas
+- **Flesch readability vs. academic tone**: The content editor may lower scores on first pass by making prose more academic. Dense sentences score poorly on Flesch Reading Ease. If content consistently fails the gate, simplify sentence structure in the source markdown rather than lowering thresholds.
+- **Unicode in LaTeX**: pdflatex cannot handle Unicode math symbols (superscripts, subscripts like `⁻`, `²`). The `_sanitize_unicode_for_latex()` method in latex_optimizer.py handles known cases, but new Unicode characters from LLM output may need to be added to the replacement map.
+- **Duplicate figure labels**: If images appear both via inline `<!-- IMAGE: -->` comments and via a separate image-walking step, you get duplicate `\label{}` errors. All images should be referenced inline from markdown — there is no separate image directory scan.
+
+## Dependencies
+
+Python packages (requirements.txt):
+- deepagents-cli: Core agent framework
+- anthropic, openai: LLM APIs
+- langchain, langchain-anthropic, langchain-openai: LLM orchestration
+- langgraph: Pipeline state graph orchestration
+- pandas: Data processing
+- pillow, matplotlib: Image handling
+
+System dependencies (Dockerfile):
+- texlive-latex-base, texlive-latex-extra: LaTeX distribution
+- texlive-fonts-recommended, texlive-science: LaTeX packages
+- ghostscript, imagemagick: Image processing

deepagents_printshop-0.1.0/Dockerfile

@@ -0,0 +1,35 @@
+FROM python:3.11-slim
+
+# Install all system dependencies and LaTeX in one step to reduce update calls
+RUN apt-get update && apt-get install -y \
+    wget \
+    curl \
+    git \
+    texlive-latex-base \
+    texlive-fonts-recommended \
+    texlive-latex-extra \
+    texlive-science \
+    ghostscript \
+    imagemagick \
+    poppler-utils \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set working directory
+WORKDIR /app
+
+# Copy requirements first for better caching
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy project files
+COPY . .
+
+# Create artifact directories
+RUN mkdir -p artifacts/sample_content artifacts/images artifacts/data artifacts/output
+
+# Set environment variables
+ENV PYTHONUNBUFFERED=1
+ENV DEEPAGENTS_HOME=/app/.deepagents
+
+# Default command
+CMD ["bash"]

deepagents_printshop-0.1.0/HANDOFF.md

@@ -0,0 +1,112 @@
+# Handoff: LangGraph Migration, Packaging & Promotion
+
+**Branch**: `feature/langgraph-migration` (off `main`)
+**Last updated**: 2026-01-30
+
+---
+
+## Plan Overview
+
+Migrate the QA orchestrator from a manual state machine to a LangGraph StateGraph, add inter-agent communication, package for PyPI, and prepare for open-source promotion.
+
+Four phases:
+1. **LangGraph StateGraph Migration** — replace the `while` loop in `workflow_coordinator.py` with a declarative graph
+2. **Inter-Agent Communication** — `agent_context` dict flows upstream notes between nodes
+3. **Python Package** — `pyproject.toml`, tests, CI
+4. **Promotion Prep** — `llms.txt`, README updates, badges
+
+---
+
+## Current Progress
+
+### DONE
+
+| # | Item | Status |
+|---|------|--------|
+| 1 | `requirements.txt` — add `langgraph` | Done |
+| 2 | `agents/qa_orchestrator/langgraph_workflow.py` — StateGraph, nodes, conditional edges, inter-agent context | Done |
+| 3 | `agents/qa_orchestrator/agent.py` — `orchestrate_qa_pipeline()` now uses `compile_qa_pipeline()` + `app.invoke()` | Done |
+| 4 | `tests/__init__.py`, `conftest.py`, `test_langgraph_workflow.py`, `test_quality_gates.py` — 37 tests, all passing | Done |
+| 5 | `pyproject.toml` — hatchling build, `printshop` entry point, `[dev]` extras | Done |
+| 6 | `.github/workflows/ci.yml` — ruff + pytest on push/PR | Done |
+| 7 | `SYSTEM_DEPS.md` — system dependency install docs | Done |
+| 8 | `llms.txt` — AI-discoverable project summary | Done |
+| 9 | `README.md` — badges, gallery, Mermaid diagram, PyPI install, GitHub topics | Done |
+
+### NOT YET COMMITTED
+
+All changes are staged but not committed. Run:
+```bash
+git add ... && git commit
+```
+
+### NOT YET DONE
+
+| Item | Notes |
+|------|-------|
+| Push to remote | Branch exists locally only |
+| Create PR | After push |
+| `pip install -e .` verification | Works locally but not formally tested in CI yet |
+| Docker build verification | Needs `docker-compose build` — not run yet |
+| Full pipeline E2E test | Requires API key + Docker/TeX Live |
+| PyPI publish | Not in scope yet — `pyproject.toml` is ready |
+
+---
+
+## Key Architecture Decisions
+
+### LangGraph integration is additive, not destructive
+- `workflow_coordinator.py` and `quality_gates.py` are **untouched**
+- Node functions in `langgraph_workflow.py` are thin wrappers that call existing `WorkflowCoordinator` methods
+- `state_to_workflow_execution()` converts the final LangGraph state back to `WorkflowExecution` so all existing reporting works
+
+### Inter-agent communication (Phase 2)
+- `agent_context` field in `PipelineState` uses a custom `merge_dicts` reducer
+- Content editor writes `content_editor_notes` (quality_score, issues, has_complex_tables)
+- LaTeX specialist reads those notes and writes `latex_specialist_notes` (structure_score, typography_issues, packages_used)
+- Visual QA reads both upstream note sets for prioritization
+
+### Graph structure
+```
+START → content_review
+content_review → [latex_optimization | iteration | escalation]
+latex_optimization → [visual_qa | iteration | escalation]
+visual_qa → quality_assessment
+quality_assessment → [completion | iteration | escalation]
+iteration → content_review (back-edge)
+completion → END
+escalation → END
+```
+
+Recursion limit: 30. Checkpointer: `MemorySaver` (in-memory, per invocation).
+
+---
+
+## Files Changed/Created
+
+| File | Action |
+|------|--------|
+| `requirements.txt` | Modified — added `langgraph` |
+| `agents/qa_orchestrator/langgraph_workflow.py` | **New** — ~300 lines |
+| `agents/qa_orchestrator/agent.py` | Modified — new `orchestrate_qa_pipeline()` using LangGraph |
+| `tests/__init__.py` | **New** — empty |
+| `tests/conftest.py` | **New** — fixtures |
+| `tests/test_langgraph_workflow.py` | **New** — 17 tests |
+| `tests/test_quality_gates.py` | **New** — 20 tests |
+| `pyproject.toml` | **New** — package config |
+| `.github/workflows/ci.yml` | **New** — CI |
+| `SYSTEM_DEPS.md` | **New** — system deps docs |
+| `llms.txt` | **New** — AI discoverability |
+| `README.md` | Modified — badges, gallery, install, architecture |
+
+---
+
+## Verification Checklist
+
+- [x] `pytest tests/ -v` — 37/37 passing
+- [x] `ruff check` on new files — clean
+- [x] `python -c "from agents.qa_orchestrator.langgraph_workflow import export_mermaid_diagram; print(export_mermaid_diagram())"` — valid Mermaid output
+- [ ] `pip install -e .` — editable install
+- [ ] `docker-compose build` — Docker still works
+- [ ] `printshop --content research_report` — CLI entry point
+- [ ] Full pipeline E2E with API key

deepagents_printshop-0.1.0/LICENSE

@@ -0,0 +1,86 @@
+# DeepAgents PrintShop License
+
+## Software License (Apache 2.0)
+
+Copyright 2025-2026 DeepAgents PrintShop Contributors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+---
+
+## Attribution Requirement for Generated Works
+
+Any documents, publications, or media generated using DeepAgents PrintShop
+must include the following attribution in a reasonably visible location
+(such as in the document's footer, credits page, colophon, or acknowledgments):
+
+    "Generated with DeepAgents PrintShop (https://github.com/kormco/deepagents-printshop)"
+
+or the shorter form:
+
+    "Powered by DeepAgents PrintShop"
+
+This attribution requirement applies to:
+- PDF documents generated by the system
+- LaTeX source files distributed to others
+- Published works derived from PrintShop output
+- Any derivative media products
+
+This requirement does NOT apply to:
+- Internal drafts and working documents not distributed publicly
+- Documents where you substantially rewrite the generated content
+- Uses where attribution is technically impractical
+
+---
+
+## Sample Content License (CC BY-SA 4.0)
+
+The sample content in `artifacts/sample_content/` is licensed under the
+Creative Commons Attribution-ShareAlike 4.0 International License.
+
+You are free to:
+- **Share** — copy and redistribute the material in any medium or format
+- **Adapt** — remix, transform, and build upon the material for any purpose
+
+Under the following terms:
+- **Attribution** — You must give appropriate credit, provide a link to the
+  license, and indicate if changes were made.
+- **ShareAlike** — If you remix, transform, or build upon the material, you
+  must distribute your contributions under the same license.
+
+Full license text: https://creativecommons.org/licenses/by-sa/4.0/legalcode
+
+---
+
+## Third-Party Content
+
+Images in `artifacts/sample_content/images/` are sourced from Pixabay and are
+used under the Pixabay License (https://pixabay.com/service/license-summary/).
+These images are free for commercial use with no attribution required, but
+attribution is appreciated.
+
+---
+
+## Disclaimer
+
+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.
+
+This software uses third-party AI services (Claude API). Users are responsible
+for compliance with those services' terms of use. Content processed through
+these services is subject to their respective privacy policies.