Metadata-Version: 2.4
Name: reportkit
Version: 0.1.0
Summary: A developer-first document generation engine with flow-based layout
Author-email: Ujjwal MV <ujwalmm5@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/uju11/reportkit
Project-URL: Documentation, https://github.com/uju11/reportkit#readme
Project-URL: Repository, https://github.com/uju11/reportkit
Project-URL: Issues, https://github.com/uju11/reportkit/issues
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.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing
Classifier: Topic :: Office/Business
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jinja2>=3.0.0
Requires-Dist: jsonschema>=4.0.0
Requires-Dist: playwright>=1.40.0
Requires-Dist: docxtpl>=0.16.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: typing-extensions>=4.0.0
Provides-Extra: ai
Requires-Dist: google-generativeai>=0.5.0; extra == "ai"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Dynamic: license-file

# 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

```bash
pip install reportkit
```

To enable AI-powered design importing:
```bash
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](https://aistudio.google.com/app/apikey).
2. Set it as an environment variable (`GOOGLE_API_KEY`) or in a `.env` file in your project root:
```env
GOOGLE_API_KEY=your_key_here
```

For PDF rendering, also install Playwright:
```bash
pip install playwright
playwright install chromium
```

For DOCX rendering, install docxtpl:
```bash
pip install docxtpl
```

### Basic Usage

```python
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:

```json
{
  "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
```json
{
  "type": "text",
  "data": {
    "content": "Hello {{name}}!"
  },
  "style": {
    "font_family": "Arial",
    "font_size": 12,
    "color": "#000000",
    "alignment": "left"
  }
}
```

### Image Block
```json
{
  "type": "image",
  "data": {
    "source": "logo.png",
    "width": 200,
    "height": 100,
    "alt_text": "Company Logo"
  }
}
```

### Table Block
```json
{
  "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
```json
{
  "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`:

```python
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

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

### Running Tests

```bash
pytest
```

### Code Formatting

```bash
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
