reportkit 0.1.0

A developer-first document generation engine with flow-based layout

ReportKit

A developer-first document generation engine with flow-based layout system for PDF and DOCX documents.

Features

• Flow-based Layout: Stream-based document layout (no absolute positioning)
• Dynamic Pagination: Automatic page breaks and content splitting
• JSON Templates: Declarative template system with v1 standard
• AI Design Importer: [NEW] Automatically generate templates from Figma screenshots
• Data Binding: Jinja2-style variable binding
• Multiple Formats: PDF, DOCX, and HTML output
• Plugin System: Extensible block architecture
• Production Ready: Pip-installable Python package

Quick Start

Installation

pip install reportkit

To enable AI-powered design importing:

pip install "reportkit[ai]"

AI Setup (Bring Your Own Key): The AI importer requires a Google AI API key.

1. Get a free API key from Google AI Studio.
2. Set it as an environment variable (GOOGLE_API_KEY) or in a .env file in your project root:

GOOGLE_API_KEY=your_key_here

For PDF rendering, also install Playwright:

pip install playwright
playwright install chromium

For DOCX rendering, install docxtpl:

pip install docxtpl

Basic Usage

from reportkit import ReportEngine

# Create engine
engine = ReportEngine()

# Register template
engine.register_template("sales_report", "templates/sales.json")

# Render report
report = engine.render(
    "sales_report",
    data={
        "client": {"name": "ABC Corporation"},
        "sales": [
            {"product": "Widget A", "amount": 1500},
            {"product": "Widget B", "amount": 2300},
        ],
        "total": 3800
    }
)

# Export to different formats
report.to_pdf("sales_report.pdf")
report.to_docx("sales_report.docx")
report.to_html("sales_report.html")

Template System

ReportKit uses JSON-based templates with a flow-based layout system:

{
  "version": "1.0",
  "name": "Sales Report",
  "page_config": {
    "size": "A4",
    "orientation": "portrait",
    "margins": {
      "top": 72,
      "right": 72,
      "bottom": 72,
      "left": 72
    }
  },
  "groups": [
    {
      "id": "header",
      "flow": "block",
      "page_behavior": "keep_together",
      "blocks": [
        {
          "type": "text",
          "data": {
            "content": "Sales Report for {{client.name}}"
          },
          "style": {
            "font_size": 18,
            "font_weight": "bold",
            "alignment": "center"
          }
        }
      ]
    },
    {
      "id": "content",
      "flow": "block",
      "page_behavior": "can_split",
      "blocks": [
        {
          "type": "table",
          "data": {
            "headers": ["Product", "Amount"],
            "data": "{{sales}}"
          }
        },
        {
          "type": "text",
          "data": {
            "content": "Total: ${{total}}"
          },
          "style": {
            "font_weight": "bold"
          }
        }
      ]
    }
  ]
}

Block Types

Text Block

{
  "type": "text",
  "data": {
    "content": "Hello {{name}}!"
  },
  "style": {
    "font_family": "Arial",
    "font_size": 12,
    "color": "#000000",
    "alignment": "left"
  }
}

Image Block

{
  "type": "image",
  "data": {
    "source": "logo.png",
    "width": 200,
    "height": 100,
    "alt_text": "Company Logo"
  }
}

Table Block

{
  "type": "table",
  "data": {
    "headers": ["Name", "Age", "City"],
    "data": [
      ["John", 30, "New York"],
      ["Jane", 25, "Boston"]
    ]
  },
  "options": {
    "show_headers": true,
    "border": true,
    "striped": false
  }
}

Chart Block

{
  "type": "chart",
  "data": {
    "chart_type": "bar",
    "title": "Sales by Month",
    "labels": ["Jan", "Feb", "Mar"],
    "datasets": [
      {
        "label": "Sales",
        "data": [1000, 1500, 1200],
        "color": "#007bff"
      }
    ]
  },
  "options": {
    "width": 400,
    "height": 300,
    "legend": true
  }
}

Page Behavior

Groups can have different page break behaviors:

• normal_flow: Default flow behavior
• keep_together: Group stays on same page
• can_split: Group can split across pages
• start_new_page: Group always starts on new page

Custom Blocks

Create custom block types by extending BaseBlock:

from reportkit.blocks import BaseBlock, BlockContext

class CustomBlock(BaseBlock):
    type = "custom"
    
    def validate(self, data):
        # Validate block data
        pass
    
    def render(self, data, context: BlockContext):
        # Render block to intermediate format
        return {
            "type": "custom",
            "content": "...",
            "style": {}
        }

# Register custom block
engine.register_block(CustomBlock)

Development

Setup

git clone https://github.com/reportkit/reportkit
cd reportkit
pip install -e ".[dev]"

Running Tests

pytest

Code Formatting

black reportkit
isort reportkit

Architecture

ReportKit follows a clear rendering pipeline:

1. Template Parsing → Validate JSON template
2. Data Binding → Resolve variables with Jinja2-style binding
3. Layout Resolution → Create flow-based document tree
4. Pagination → Handle page breaks and content splitting
5. Rendering → Convert to HTML, then PDF/DOCX

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

Support

• Documentation: https://reportkit.readthedocs.io
• Issues: https://github.com/reportkit/reportkit/issues
• Discussions: https://github.com/reportkit/reportkit/discussions