Metadata-Version: 2.5
Name: agent-html
Version: 0.1.1
Summary: Turn structured agent output into polished, self-contained HTML artifacts
Project-URL: Homepage, https://github.com/breathOfTech/agent-html
Project-URL: Documentation, https://github.com/breathOfTech/agent-html#readme
Project-URL: Repository, https://github.com/breathOfTech/agent-html
Project-URL: Issues, https://github.com/breathOfTech/agent-html/issues
Author-email: Pratik Baniya <baniyapratik@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent,ai,artifact,html,llm,report
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software 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 :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Markup :: HTML
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: jinja2>=3.1
Requires-Dist: markdown-it-py>=3.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pygments>=2.17
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: server
Requires-Dist: starlette>=0.36; extra == 'server'
Requires-Dist: uvicorn>=0.27; extra == 'server'
Description-Content-Type: text/markdown

# agent-html

Turn structured agent output into polished, self-contained HTML artifacts.

**One conversation in. One shareable HTML file out.**

[![PyPI](https://img.shields.io/pypi/v/agent-html)](https://pypi.org/project/agent-html/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10+-blue)](https://python.org)

---

## Why

AI conversations are great for exploration but terrible for sharing. Chat transcripts are long, unstructured, and die in the thread. **agent-html** gives you a one-line way to turn any structured data into a professional, self-contained HTML report that anyone can open.

Works with any agent framework: LangGraph, OpenAI Agents, Claude Code, CrewAI, or plain Python.

## Install

```bash
pip install agent-html
```

## Quick Start

```python
from agent_html import Report, Section

report = Report(
    title="Weekly Summary",
    subtitle="Engineering — Aug 14-21, 2026",
    metadata={"messages": 142},
)

report.add_section(Section(
    title="Overview",
    content="Team focused on infrastructure stability after the outage.",
    style="highlight",
))

report.add_section(Section(
    title="Decisions",
    icon="✅",
    items=["Shut down UAE region", "Migrate to EU-West by Q3"],
))

report.add_section(Section(
    title="Architecture",
    mermaid="graph TD\n  A[Client] --> B[Gateway] --> C[Service]",
))

report.save("summary.html")
```

Output: a single `summary.html` file with all CSS/JS inlined. No external dependencies. Double-click to open.

## CLI

```bash
# From JSON
agent-html render --input data.json --output report.html

# From Markdown
agent-html render --input notes.md --title "Design Review" --output report.html

# Dark theme
agent-html render --input data.json --theme dark --output report.html

# Pipe from stdin
echo '{"title":"Quick","sections":[{"title":"Note","content":"Hello"}]}' | agent-html render --stdin --output note.html

# Preview server
agent-html serve ./reports/
```

## Features

- **Single-file output** — all CSS/JS inlined, no external deps
- **Themes** — light, dark, or auto (respects system preference)
- **Mermaid diagrams** — flowcharts, sequence diagrams, state machines
- **Syntax highlighting** — language-aware code blocks with copy button
- **Table of contents** — auto-generated with scroll-spy
- **Collapsible sections** — `<details>/<summary>` for long content
- **Callout blocks** — note, warning, danger, tip
- **Tables** — from structured data
- **Badges/pills** — for tags, participants, status
- **Print-optimized** — clean PDF via browser print
- **Accessible** — semantic HTML, ARIA labels, keyboard nav

## Section Styles

```python
Section(title="Info", content="...", style="highlight")        # Accent-bordered
Section(title="Note", content="...", style="callout-note")     # Blue info box
Section(title="Warn", content="...", style="callout-warning")  # Yellow warning
Section(title="Error", content="...", style="callout-danger")  # Red danger
Section(title="Tip", content="...", style="callout-tip")       # Green tip
Section(title="Tasks", items=[...], style="checklist")         # Checkbox list
```

## Integration Examples

### LangGraph / LangChain Tool

```python
from langchain_core.tools import tool
from agent_html import Report, Section

@tool
def create_report(title: str, sections: list[dict]) -> str:
    """Generate a shareable HTML report."""
    report = Report(title=title)
    for s in sections:
        report.add_section(Section(**s))
    report.save(f"/tmp/reports/{report.id}.html")
    return f"Report: http://localhost:8080/reports/{report.id}"
```

### FastAPI

```python
from fastapi.responses import HTMLResponse
from agent_html import Report, Section

@app.post("/reports")
async def create(data: ReportRequest):
    report = Report(title=data.title)
    for s in data.sections:
        report.add_section(Section(**s.dict()))
    return HTMLResponse(report.to_html())
```

## JSON Input Format

```json
{
  "title": "My Report",
  "subtitle": "Optional subtitle",
  "metadata": {"key": "value"},
  "sections": [
    {"title": "Overview", "content": "Markdown content here", "style": "highlight"},
    {"title": "Items", "items": ["one", "two", "three"], "icon": "📋"},
    {"title": "Diagram", "mermaid": "graph TD\n  A --> B"},
    {"title": "Code", "code": "print('hello')", "code_language": "python"},
    {"title": "Table", "table": {"headers": ["A","B"], "rows": [["1","2"]]}}
  ]
}
```

## Inspiration

Built on ideas from:
- [ThariqS/html-effectiveness](https://github.com/ThariqS/html-effectiveness) (Apache-2.0) — demonstrating HTML as an AI output medium
- The "Unreasonable Effectiveness of HTML" thesis by Thariq Shihipar

## License

Apache-2.0
