altr-oss 0.2.0__py3-none-any.whl

altr/__init__.py

@@ -0,0 +1,24 @@
+"""altr - open source doc/excel/ppt skills for LLMs."""
+
+from .agent import DEFAULT_MODEL, GROQ_BASE_URL, OfficeAgent, RunResult
+from .markdown import markdown_to_blocks
+from .pdf import soffice_available, to_pdf
+from .prompts import SYSTEM_PROMPT
+from .schemas import DocumentSpec, PresentationSpec, SpreadsheetSpec
+from .tools import dispatch, get_tools
+
+__all__ = [
+    "OfficeAgent",
+    "RunResult",
+    "SYSTEM_PROMPT",
+    "DEFAULT_MODEL",
+    "GROQ_BASE_URL",
+    "DocumentSpec",
+    "SpreadsheetSpec",
+    "PresentationSpec",
+    "get_tools",
+    "dispatch",
+    "markdown_to_blocks",
+    "to_pdf",
+    "soffice_available",
+]

altr/agent.py

@@ -0,0 +1,111 @@
+"""A minimal tool-calling loop for any OpenAI-compatible endpoint.
+
+Defaults target Groq and openai/gpt-oss-120b, but base_url/model can point at
+Ollama, vLLM, LM Studio, or anything else that speaks chat completions.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from openai import OpenAI
+
+from .prompts import SYSTEM_PROMPT
+from .tools import dispatch, get_tools
+
+GROQ_BASE_URL = "https://api.groq.com/openai/v1"
+DEFAULT_MODEL = "openai/gpt-oss-120b"
+
+
+@dataclass
+class RunResult:
+    """Files created during a run, plus the model's final text reply."""
+
+    files: list[Path] = field(default_factory=list)
+    reply: str = ""
+
+
+class OfficeAgent:
+    def __init__(
+        self,
+        model: str = DEFAULT_MODEL,
+        base_url: str = GROQ_BASE_URL,
+        api_key: str | None = None,
+        out_dir: str | Path = "output",
+        max_rounds: int = 8,
+        docx_template: str | Path | None = None,
+        pptx_template: str | Path | None = None,
+        client: OpenAI | None = None,
+    ) -> None:
+        api_key = api_key or os.environ.get("GROQ_API_KEY") or os.environ.get("OPENAI_API_KEY")
+        if client is None and not api_key:
+            raise ValueError(
+                "no API key: pass api_key= or set GROQ_API_KEY (or OPENAI_API_KEY)"
+            )
+        self.client = client or OpenAI(base_url=base_url, api_key=api_key)
+        self.model = model
+        self.out_dir = Path(out_dir)
+        self.max_rounds = max_rounds
+        self.templates: dict[str, Path] = {}
+        if docx_template:
+            self.templates["docx"] = Path(docx_template)
+        if pptx_template:
+            self.templates["pptx"] = Path(pptx_template)
+
+    def run(self, prompt: str) -> RunResult:
+        """Ask the model to fulfil `prompt`, executing its tool calls."""
+        messages: list[dict] = [
+            {"role": "system", "content": SYSTEM_PROMPT},
+            {"role": "user", "content": prompt},
+        ]
+        result = RunResult()
+
+        for _ in range(self.max_rounds):
+            response = self.client.chat.completions.create(
+                model=self.model,
+                messages=messages,
+                tools=get_tools(),
+                tool_choice="auto",
+            )
+            message = response.choices[0].message
+
+            if not message.tool_calls:
+                result.reply = message.content or ""
+                return result
+
+            messages.append(
+                {
+                    "role": "assistant",
+                    "content": message.content or "",
+                    "tool_calls": [
+                        {
+                            "id": tc.id,
+                            "type": "function",
+                            "function": {
+                                "name": tc.function.name,
+                                "arguments": tc.function.arguments,
+                            },
+                        }
+                        for tc in message.tool_calls
+                    ],
+                }
+            )
+            for tc in message.tool_calls:
+                outcome = dispatch(
+                    tc.function.name, tc.function.arguments, self.out_dir, self.templates
+                )
+                if outcome.get("ok"):
+                    result.files.append(Path(outcome["file"]))
+                messages.append(
+                    {
+                        "role": "tool",
+                        "tool_call_id": tc.id,
+                        "content": json.dumps(outcome),
+                    }
+                )
+
+        result.reply = "stopped: reached max tool-call rounds"
+        return result

altr/cli.py

@@ -0,0 +1,104 @@
+"""Command-line entry points.
+
+    altr make "Create a pitch deck about solar drones"
+    altr render presentation examples/pitch.json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .agent import DEFAULT_MODEL, GROQ_BASE_URL, OfficeAgent
+from .pdf import to_pdf
+from .renderers import render_document, render_presentation, render_spreadsheet
+from .schemas import DocumentSpec, PresentationSpec, SpreadsheetSpec
+
+_RENDERERS = {
+    "document": (DocumentSpec, render_document),
+    "spreadsheet": (SpreadsheetSpec, render_spreadsheet),
+    "presentation": (PresentationSpec, render_presentation),
+}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="altr",
+        description="Office document skills (docx/xlsx/pptx) for open-weight models.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    make = sub.add_parser("make", help="ask a model to create documents from a prompt")
+    make.add_argument("prompt", help="what to create, in plain language")
+    make.add_argument("--model", default=DEFAULT_MODEL)
+    make.add_argument("--base-url", default=GROQ_BASE_URL, help="any OpenAI-compatible endpoint")
+    make.add_argument("--api-key", default=None, help="defaults to $GROQ_API_KEY / $OPENAI_API_KEY")
+    make.add_argument("--out", default="output", help="output directory (default: ./output)")
+    make.add_argument("--max-rounds", type=int, default=8)
+    make.add_argument("--docx-template", default=None, help="template .docx for brand styling")
+    make.add_argument("--pptx-template", default=None, help="template .pptx for brand styling")
+    make.add_argument("--pdf", action="store_true", help="also export each file to PDF (needs LibreOffice)")
+
+    render = sub.add_parser("render", help="render a JSON spec to a file, no model involved")
+    render.add_argument("type", choices=sorted(_RENDERERS))
+    render.add_argument("spec", help="path to a JSON spec file")
+    render.add_argument("--out", default="output", help="output directory (default: ./output)")
+    render.add_argument("--template", default=None, help="template .docx/.pptx for brand styling")
+    render.add_argument("--pdf", action="store_true", help="also export to PDF (needs LibreOffice)")
+
+    args = parser.parse_args(argv)
+
+    if args.command == "render":
+        return _render(args)
+    return _make(args)
+
+
+def _render(args: argparse.Namespace) -> int:
+    spec_cls, render_fn = _RENDERERS[args.type]
+    spec = spec_cls.model_validate(json.loads(Path(args.spec).read_text()))
+    if args.type == "spreadsheet":
+        if args.template:
+            print("altr: --template is not supported for spreadsheets", file=sys.stderr)
+            return 2
+        path = render_fn(spec, Path(args.out))
+    else:
+        template = Path(args.template) if args.template else None
+        path = render_fn(spec, Path(args.out), template=template)
+    print(f"created {path}")
+    if args.pdf:
+        print(f"created {to_pdf(path)}")
+    return 0
+
+
+def _make(args: argparse.Namespace) -> int:
+    try:
+        agent = OfficeAgent(
+            model=args.model,
+            base_url=args.base_url,
+            api_key=args.api_key,
+            out_dir=args.out,
+            max_rounds=args.max_rounds,
+            docx_template=args.docx_template,
+            pptx_template=args.pptx_template,
+        )
+    except ValueError as e:
+        print(f"altr: {e}", file=sys.stderr)
+        return 2
+
+    result = agent.run(args.prompt)
+    for path in result.files:
+        print(f"created {path}")
+        if args.pdf:
+            print(f"created {to_pdf(path)}")
+    if result.reply:
+        print(result.reply)
+    if not result.files:
+        print("altr: the model created no files", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

altr/markdown.py

@@ -0,0 +1,103 @@
+"""A small markdown-to-blocks converter.
+
+Supports the subset that maps cleanly onto document blocks: #-headings,
+bullet (-/*) and numbered (1.) lists, pipe tables, and paragraphs. Inline
+formatting (**bold**, *italic*, `code`) is left in the text; the docx
+renderer turns it into styled runs.
+"""
+
+from __future__ import annotations
+
+import re
+
+from .schemas import BulletList, Heading, NumberedList, Paragraph, Table
+
+_HEADING = re.compile(r"^(#{1,9})\s+(.*)$")
+_BULLET = re.compile(r"^[-*]\s+(.*)$")
+_NUMBERED = re.compile(r"^\d+[.)]\s+(.*)$")
+_TABLE_DIVIDER = re.compile(r"^\|?[\s:|-]+\|?$")
+
+MarkdownBlock = Heading | Paragraph | BulletList | NumberedList | Table
+
+
+def markdown_to_blocks(text: str) -> list[MarkdownBlock]:
+    """Convert markdown text into document blocks."""
+    blocks: list[MarkdownBlock] = []
+    paragraph: list[str] = []
+    bullets: list[str] = []
+    numbered: list[str] = []
+    table: list[list[str]] = []
+
+    def flush() -> None:
+        nonlocal paragraph, bullets, numbered, table
+        if paragraph:
+            blocks.append(Paragraph(text=" ".join(paragraph)))
+            paragraph = []
+        if bullets:
+            blocks.append(BulletList(items=bullets))
+            bullets = []
+        if numbered:
+            blocks.append(NumberedList(items=numbered))
+            numbered = []
+        if table:
+            blocks.append(Table(headers=table[0], rows=table[1:]))
+            table = []
+
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line:
+            flush()
+            continue
+
+        if m := _HEADING.match(line):
+            flush()
+            blocks.append(Heading(level=len(m.group(1)), text=m.group(2).strip()))
+            continue
+
+        if line.startswith("|") and "|" in line[1:]:
+            if _TABLE_DIVIDER.match(line):
+                continue  # the |---|---| row under the header
+            if paragraph or bullets or numbered:
+                flush()
+            cells = [c.strip() for c in line.strip("|").split("|")]
+            table.append(cells)
+            continue
+
+        if m := _BULLET.match(line):
+            if paragraph or numbered or table:
+                flush()
+            bullets.append(m.group(1).strip())
+            continue
+
+        if m := _NUMBERED.match(line):
+            if paragraph or bullets or table:
+                flush()
+            numbered.append(m.group(1).strip())
+            continue
+
+        if bullets or numbered or table:
+            flush()
+        paragraph.append(line)
+
+    flush()
+    return blocks
+
+
+_INLINE = re.compile(r"(\*\*.+?\*\*|\*.+?\*|`.+?`)")
+
+
+def split_inline(text: str) -> list[tuple[str, str]]:
+    """Split text into (style, text) runs; style is '', 'bold', 'italic', or 'code'."""
+    runs: list[tuple[str, str]] = []
+    for part in _INLINE.split(text):
+        if not part:
+            continue
+        if part.startswith("**") and part.endswith("**") and len(part) > 4:
+            runs.append(("bold", part[2:-2]))
+        elif part.startswith("`") and part.endswith("`") and len(part) > 2:
+            runs.append(("code", part[1:-1]))
+        elif part.startswith("*") and part.endswith("*") and len(part) > 2:
+            runs.append(("italic", part[1:-1]))
+        else:
+            runs.append(("", part))
+    return runs

altr/pdf.py

@@ -0,0 +1,39 @@
+"""PDF export via LibreOffice's headless converter."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+
+def soffice_available() -> bool:
+    return _soffice() is not None
+
+
+def _soffice() -> str | None:
+    return shutil.which("soffice") or shutil.which("libreoffice")
+
+
+def to_pdf(path: str | Path, out_dir: str | Path | None = None) -> Path:
+    """Convert a docx/xlsx/pptx file to PDF. Requires LibreOffice on PATH."""
+    soffice = _soffice()
+    if soffice is None:
+        raise RuntimeError(
+            "PDF export requires LibreOffice: install it so 'soffice' is on PATH"
+        )
+    path = Path(path)
+    out_dir = Path(out_dir) if out_dir else path.parent
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    result = subprocess.run(
+        [soffice, "--headless", "--convert-to", "pdf", "--outdir", str(out_dir), str(path)],
+        capture_output=True,
+        text=True,
+        timeout=180,
+    )
+    pdf_path = out_dir / (path.stem + ".pdf")
+    if result.returncode != 0 or not pdf_path.is_file():
+        detail = result.stderr.strip() or result.stdout.strip() or "no output produced"
+        raise RuntimeError(f"PDF conversion failed for {path.name}: {detail}")
+    return pdf_path

altr/prompts.py

@@ -0,0 +1,28 @@
+"""The system prompt that turns a bare model into a document-making skill."""
+
+SYSTEM_PROMPT = """\
+You are a document production assistant. You create real files using the
+provided tools:
+
+- create_document - Word documents (.docx): reports, letters, guides, notes.
+- create_spreadsheet - Excel workbooks (.xlsx): budgets, trackers, datasets.
+- create_presentation - PowerPoint decks (.pptx): pitches, talks, overviews.
+
+Rules:
+1. Always produce the file by calling a tool. Never paste document content
+   into the chat instead of calling a tool.
+2. Write complete, substantive content in one call. Do not use placeholders
+   like "TODO" or "add content here" - invent sensible, specific content when
+   the user gives only a topic.
+3. Choose descriptive filenames (e.g. 'q3-marketing-report.docx').
+4. In spreadsheets, use formulas (cells starting with '=') for totals and
+   derived values instead of precomputing numbers. Add a chart when the data
+   would benefit from one.
+5. In presentations, start with a 'title' slide and keep bullets short -
+   put detail into speaker notes. Use 'chart' slides for numeric comparisons.
+6. Only reference image files the user explicitly told you exist; never
+   invent image paths.
+7. If a tool returns an error, fix your arguments and call it again.
+8. If the user asks for multiple files, make one tool call per file.
+After the tools succeed, reply with one short sentence per file created.
+"""

altr/renderers/__init__.py

@@ -0,0 +1,25 @@
+"""Renderers turn validated specs into real files on disk."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .docx import render_document
+from .pptx import render_presentation
+from .xlsx import render_spreadsheet
+
+__all__ = ["render_document", "render_spreadsheet", "render_presentation", "output_path"]
+
+
+def output_path(out_dir: Path, filename: str, ext: str) -> Path:
+    """Resolve a model-supplied filename to a safe path inside out_dir.
+
+    Only the base name is kept, so a hostile or confused model cannot write
+    outside the output directory.
+    """
+    name = Path(filename.strip()).name or f"output{ext}"
+    if not name.lower().endswith(ext):
+        name += ext
+    out_dir = Path(out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    return out_dir / name

altr/renderers/docx.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from docx import Document
+from docx.shared import Inches
+
+from ..markdown import markdown_to_blocks, split_inline
+from ..schemas import (
+    BulletList,
+    DocumentSpec,
+    Heading,
+    Image,
+    Markdown,
+    NumberedList,
+    PageBreak,
+    Paragraph,
+    Table,
+)
+
+
+def render_document(
+    spec: DocumentSpec, out_dir: Path, template: Path | None = None
+) -> Path:
+    from . import output_path
+
+    doc = Document(str(template)) if template else Document()
+    if spec.title:
+        doc.add_heading(spec.title, 0)
+
+    for block in spec.blocks:
+        _add_block(doc, block)
+
+    path = output_path(out_dir, spec.filename, ".docx")
+    doc.save(str(path))
+    return path
+
+
+def _add_block(doc: Document, block) -> None:
+    if isinstance(block, Heading):
+        doc.add_heading(block.text, block.level)
+    elif isinstance(block, Paragraph):
+        _add_styled_paragraph(doc, block.text)
+    elif isinstance(block, BulletList):
+        for item in block.items:
+            _add_styled_paragraph(doc, item, style="List Bullet")
+    elif isinstance(block, NumberedList):
+        for item in block.items:
+            _add_styled_paragraph(doc, item, style="List Number")
+    elif isinstance(block, Table):
+        table = doc.add_table(rows=1, cols=len(block.headers))
+        table.style = "Table Grid"
+        for i, header in enumerate(block.headers):
+            run = table.rows[0].cells[i].paragraphs[0].add_run(header)
+            run.bold = True
+        for row in block.rows:
+            cells = table.add_row().cells
+            for i, value in enumerate(row[: len(block.headers)]):
+                cells[i].text = value
+    elif isinstance(block, Image):
+        image_path = Path(block.path)
+        if not image_path.is_file():
+            raise FileNotFoundError(f"image not found: {block.path}")
+        width = Inches(block.width_inches) if block.width_inches else None
+        doc.add_picture(str(image_path), width=width)
+        if block.caption:
+            doc.add_paragraph(block.caption, style="Caption")
+    elif isinstance(block, Markdown):
+        for sub_block in markdown_to_blocks(block.text):
+            _add_block(doc, sub_block)
+    elif isinstance(block, PageBreak):
+        doc.add_page_break()
+
+
+def _add_styled_paragraph(doc: Document, text: str, style: str | None = None) -> None:
+    """Add a paragraph, turning inline **bold**/*italic*/`code` into runs."""
+    para = doc.add_paragraph(style=style)
+    for kind, part in split_inline(text):
+        run = para.add_run(part)
+        if kind == "bold":
+            run.bold = True
+        elif kind == "italic":
+            run.italic = True
+        elif kind == "code":
+            run.font.name = "Courier New"

altr/renderers/pptx.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from pptx import Presentation
+from pptx.chart.data import CategoryChartData
+from pptx.enum.chart import XL_CHART_TYPE
+from pptx.util import Inches
+
+from ..schemas import PresentationSpec, Slide
+
+# Layout indexes in the standard template. Custom templates must keep the
+# stock layout order (0 title, 1 title+content, 2 section header, 5 title only).
+_TITLE_LAYOUT = 0
+_BULLETS_LAYOUT = 1
+_SECTION_LAYOUT = 2
+_TITLE_ONLY_LAYOUT = 5
+
+_CHART_TYPES = {
+    "bar": XL_CHART_TYPE.COLUMN_CLUSTERED,
+    "line": XL_CHART_TYPE.LINE,
+    "pie": XL_CHART_TYPE.PIE,
+}
+
+# Body area below the title on a 10 x 7.5 inch slide.
+_BODY = (Inches(0.8), Inches(1.8), Inches(8.4), Inches(5.0))
+
+
+def render_presentation(
+    spec: PresentationSpec, out_dir: Path, template: Path | None = None
+) -> Path:
+    from . import output_path
+
+    prs = Presentation(str(template)) if template else Presentation()
+
+    for slide_spec in spec.slides:
+        slide = prs.slides.add_slide(prs.slide_layouts[_layout_index(slide_spec)])
+        slide.shapes.title.text = slide_spec.title
+
+        if slide_spec.layout in ("title", "section") and slide_spec.subtitle:
+            slide.placeholders[1].text = slide_spec.subtitle
+
+        if slide_spec.layout == "bullets" and slide_spec.bullets:
+            body = slide.placeholders[1].text_frame
+            for i, bullet in enumerate(slide_spec.bullets):
+                para = body.paragraphs[0] if i == 0 else body.add_paragraph()
+                para.text = bullet.text
+                para.level = bullet.level
+
+        if slide_spec.layout == "chart":
+            _add_chart(slide, slide_spec)
+
+        if slide_spec.layout == "image":
+            _add_image(slide, slide_spec)
+
+        if slide_spec.notes:
+            slide.notes_slide.notes_text_frame.text = slide_spec.notes
+
+    path = output_path(out_dir, spec.filename, ".pptx")
+    prs.save(str(path))
+    return path
+
+
+def _layout_index(slide_spec: Slide) -> int:
+    if slide_spec.layout == "title":
+        return _TITLE_LAYOUT
+    if slide_spec.layout == "section":
+        return _SECTION_LAYOUT
+    if slide_spec.layout in ("chart", "image"):
+        return _TITLE_ONLY_LAYOUT
+    return _BULLETS_LAYOUT
+
+
+def _add_chart(slide, slide_spec: Slide) -> None:
+    chart = slide_spec.chart
+    data = CategoryChartData()
+    data.categories = chart.categories
+    for series in chart.series:
+        # Pad or trim so every series aligns with the category axis.
+        values = list(series.values[: len(chart.categories)])
+        values += [0.0] * (len(chart.categories) - len(values))
+        data.add_series(series.name, values)
+    slide.shapes.add_chart(_CHART_TYPES[chart.kind], *_BODY, data)
+
+
+def _add_image(slide, slide_spec: Slide) -> None:
+    image_path = Path(slide_spec.image.path)
+    if not image_path.is_file():
+        raise FileNotFoundError(f"image not found: {slide_spec.image.path}")
+    left, top, width, _ = _BODY
+    slide.shapes.add_picture(str(image_path), left, top, width=width)

altr/renderers/xlsx.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from openpyxl import Workbook
+from openpyxl.chart import BarChart, LineChart, PieChart, Reference
+from openpyxl.styles import Font
+from openpyxl.utils import get_column_letter
+from openpyxl.worksheet.worksheet import Worksheet
+
+from ..schemas import Sheet, SpreadsheetSpec
+
+_CHART_CLASSES = {"bar": BarChart, "line": LineChart, "pie": PieChart}
+_CHART_ROWS = 15  # vertical space to leave per chart when stacking
+
+
+def render_spreadsheet(spec: SpreadsheetSpec, out_dir: Path) -> Path:
+    from . import output_path
+
+    wb = Workbook()
+    wb.remove(wb.active)
+
+    for sheet in spec.sheets:
+        ws = wb.create_sheet(title=sheet.name)
+        first_data_row = 1
+        if sheet.columns:
+            for i, col in enumerate(sheet.columns, start=1):
+                cell = ws.cell(row=1, column=i, value=col.header)
+                cell.font = Font(bold=True)
+                if col.width:
+                    ws.column_dimensions[get_column_letter(i)].width = col.width
+            if sheet.freeze_header:
+                ws.freeze_panes = "A2"
+            first_data_row = 2
+
+        for r, row in enumerate(sheet.rows, start=first_data_row):
+            for c, value in enumerate(row, start=1):
+                ws.cell(row=r, column=c, value=value)
+
+        _add_charts(ws, sheet, first_data_row)
+
+    path = output_path(out_dir, spec.filename, ".xlsx")
+    wb.save(str(path))
+    return path
+
+
+def _add_charts(ws: Worksheet, sheet: Sheet, first_data_row: int) -> None:
+    if not sheet.charts or not sheet.rows:
+        return
+    last_row = first_data_row + len(sheet.rows) - 1
+    data_cols = max(len(row) for row in sheet.rows)
+    anchor_col = get_column_letter(data_cols + 2)
+
+    for i, chart_spec in enumerate(sheet.charts):
+        chart = _CHART_CLASSES[chart_spec.kind]()
+        chart.title = chart_spec.title
+        has_header = bool(sheet.columns)
+        for col in chart_spec.value_columns:
+            data = Reference(
+                ws,
+                min_col=col,
+                min_row=1 if has_header else first_data_row,
+                max_row=last_row,
+            )
+            chart.add_data(data, titles_from_data=has_header)
+        categories = Reference(
+            ws, min_col=chart_spec.label_column, min_row=first_data_row, max_row=last_row
+        )
+        chart.set_categories(categories)
+        ws.add_chart(chart, f"{anchor_col}{2 + i * _CHART_ROWS}")

altr/schemas.py

@@ -0,0 +1,195 @@
+"""Pydantic specs for the three document types.
+
+These models serve double duty: they validate what the model sends, and their
+JSON schemas become the tool-call parameter schemas the model sees. Keep the
+field descriptions model-facing - they are effectively prompt text.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal, Union
+
+from pydantic import BaseModel, Field, model_validator
+
+ChartType = Literal["bar", "line", "pie"]
+
+# --- Word documents (.docx) -------------------------------------------------
+
+
+class Heading(BaseModel):
+    type: Literal["heading"] = "heading"
+    level: int = Field(1, ge=1, le=9, description="1 is the largest heading.")
+    text: str
+
+
+class Paragraph(BaseModel):
+    type: Literal["paragraph"] = "paragraph"
+    text: str = Field(
+        description="Supports inline markdown: **bold**, *italic*, `code`."
+    )
+
+
+class BulletList(BaseModel):
+    type: Literal["bullet_list"] = "bullet_list"
+    items: list[str] = Field(min_length=1)
+
+
+class NumberedList(BaseModel):
+    type: Literal["numbered_list"] = "numbered_list"
+    items: list[str] = Field(min_length=1)
+
+
+class Table(BaseModel):
+    type: Literal["table"] = "table"
+    headers: list[str] = Field(min_length=1)
+    rows: list[list[str]] = Field(
+        default_factory=list,
+        description="Each row must have the same number of cells as headers.",
+    )
+
+
+class Image(BaseModel):
+    type: Literal["image"] = "image"
+    path: str = Field(
+        description="Path to an existing local image file (.png/.jpg). Only "
+        "reference files the user explicitly told you about."
+    )
+    width_inches: float | None = Field(None, gt=0, le=10)
+    caption: str | None = None
+
+
+class Markdown(BaseModel):
+    type: Literal["markdown"] = "markdown"
+    text: str = Field(
+        description="Markdown converted to document content. Supports #-headings, "
+        "-/1. lists, | pipe tables |, paragraphs, and inline **bold**/*italic*/`code`."
+    )
+
+
+class PageBreak(BaseModel):
+    type: Literal["page_break"] = "page_break"
+
+
+Block = Annotated[
+    Union[Heading, Paragraph, BulletList, NumberedList, Table, Image, Markdown, PageBreak],
+    Field(discriminator="type"),
+]
+
+
+class DocumentSpec(BaseModel):
+    """A Word document composed of ordered content blocks."""
+
+    filename: str = Field(description="Output file name, e.g. 'report.docx'.")
+    title: str | None = Field(None, description="Optional document title heading.")
+    blocks: list[Block] = Field(min_length=1, description="Document content, in order.")
+
+
+# --- Spreadsheets (.xlsx) ---------------------------------------------------
+
+Cell = Union[str, int, float, bool, None]
+
+
+class Column(BaseModel):
+    header: str
+    width: float | None = Field(None, gt=0, description="Column width in characters.")
+
+
+class SheetChart(BaseModel):
+    """A chart embedded in a worksheet, built from the sheet's own data."""
+
+    kind: ChartType = "bar"
+    title: str
+    label_column: int = Field(
+        1, ge=1, description="1-based index of the column holding category labels."
+    )
+    value_columns: list[int] = Field(
+        min_length=1,
+        description="1-based indexes of numeric columns to plot as series.",
+    )
+
+
+class Sheet(BaseModel):
+    name: str = Field(max_length=31, description="Worksheet tab name.")
+    columns: list[Column] = Field(
+        default_factory=list, description="Header row; rendered bold."
+    )
+    rows: list[list[Cell]] = Field(
+        default_factory=list,
+        description="Data rows. String cells starting with '=' are Excel formulas, "
+        "e.g. '=SUM(B2:B10)'.",
+    )
+    freeze_header: bool = Field(True, description="Keep the header row visible on scroll.")
+    charts: list[SheetChart] = Field(
+        default_factory=list,
+        description="Charts plotting this sheet's data, placed beside it.",
+    )
+
+
+class SpreadsheetSpec(BaseModel):
+    """An Excel workbook with one or more worksheets."""
+
+    filename: str = Field(description="Output file name, e.g. 'budget.xlsx'.")
+    sheets: list[Sheet] = Field(min_length=1)
+
+
+# --- Presentations (.pptx) --------------------------------------------------
+
+
+class BulletPoint(BaseModel):
+    text: str
+    level: int = Field(0, ge=0, le=4, description="Indent level; 0 is top level.")
+
+
+class ChartSeries(BaseModel):
+    name: str
+    values: list[float] = Field(min_length=1)
+
+
+class SlideChart(BaseModel):
+    """A chart drawn on a slide from inline data."""
+
+    kind: ChartType = "bar"
+    categories: list[str] = Field(min_length=1)
+    series: list[ChartSeries] = Field(
+        min_length=1,
+        description="Each series must have exactly one value per category.",
+    )
+
+
+class SlideImage(BaseModel):
+    path: str = Field(
+        description="Path to an existing local image file (.png/.jpg). Only "
+        "reference files the user explicitly told you about."
+    )
+
+
+class Slide(BaseModel):
+    layout: Literal["title", "bullets", "section", "chart", "image"] = Field(
+        "bullets",
+        description="'title' for the opening slide, 'section' for a divider, "
+        "'bullets' for a regular content slide, 'chart' for a chart slide, "
+        "'image' for a full-width image slide.",
+    )
+    title: str
+    subtitle: str | None = Field(None, description="Only used by title/section layouts.")
+    bullets: list[BulletPoint] = Field(
+        default_factory=list, description="Body content for the 'bullets' layout."
+    )
+    chart: SlideChart | None = Field(None, description="Required for the 'chart' layout.")
+    image: SlideImage | None = Field(None, description="Required for the 'image' layout.")
+    notes: str | None = Field(None, description="Speaker notes for this slide.")
+
+    @model_validator(mode="after")
+    def _check_layout_content(self) -> "Slide":
+        if self.layout == "chart" and self.chart is None:
+            raise ValueError("a 'chart' slide needs the 'chart' field")
+        if self.layout == "image" and self.image is None:
+            raise ValueError("an 'image' slide needs the 'image' field")
+        return self
+
+
+class PresentationSpec(BaseModel):
+    """A PowerPoint deck built from a list of slides."""
+
+    filename: str = Field(description="Output file name, e.g. 'pitch.pptx'.")
+    slides: list[Slide] = Field(min_length=1)

altr/tools.py

@@ -0,0 +1,99 @@
+"""Tool-call definitions and dispatch.
+
+`get_tools()` returns OpenAI-format tool definitions you can pass straight to
+any chat-completions endpoint (Groq, Ollama, vLLM, ...). `dispatch()` executes
+a tool call the model made and returns a JSON-safe result dict - errors are
+returned rather than raised, so the model can read them and self-correct.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, ValidationError
+
+from .renderers import render_document, render_presentation, render_spreadsheet
+from .schemas import DocumentSpec, PresentationSpec, SpreadsheetSpec
+
+# name -> (spec class, renderer, template key or None, description)
+_REGISTRY: dict[str, tuple[type[BaseModel], Any, str | None, str]] = {
+    "create_document": (
+        DocumentSpec,
+        render_document,
+        "docx",
+        "Create a Word document (.docx) from ordered content blocks: headings, "
+        "paragraphs, bullet/numbered lists, tables, images, markdown, and page "
+        "breaks.",
+    ),
+    "create_spreadsheet": (
+        SpreadsheetSpec,
+        render_spreadsheet,
+        None,
+        "Create an Excel workbook (.xlsx) with one or more worksheets. Supports "
+        "bold header rows, column widths, frozen headers, formulas (string cells "
+        "starting with '='), and bar/line/pie charts of the sheet's data.",
+    ),
+    "create_presentation": (
+        PresentationSpec,
+        render_presentation,
+        "pptx",
+        "Create a PowerPoint deck (.pptx) from slides: a title slide, section "
+        "dividers, bulleted content slides, chart slides, and image slides, "
+        "with optional speaker notes.",
+    ),
+}
+
+
+def get_tools() -> list[dict[str, Any]]:
+    """OpenAI-format tool definitions for the three document skills."""
+    return [
+        {
+            "type": "function",
+            "function": {
+                "name": name,
+                "description": description,
+                "parameters": spec.model_json_schema(),
+            },
+        }
+        for name, (spec, _, _, description) in _REGISTRY.items()
+    ]
+
+
+def dispatch(
+    name: str,
+    arguments: str | dict[str, Any],
+    out_dir: str | Path,
+    templates: dict[str, Path] | None = None,
+) -> dict[str, Any]:
+    """Execute one tool call and return {"ok": True, "file": path} or an error.
+
+    `templates` optionally maps 'docx'/'pptx' to a template file the renderer
+    starts from, for brand styling.
+    """
+    entry = _REGISTRY.get(name)
+    if entry is None:
+        return {"ok": False, "error": f"unknown tool {name!r}"}
+    spec_cls, render, template_key, _ = entry
+
+    if isinstance(arguments, str):
+        try:
+            arguments = json.loads(arguments)
+        except json.JSONDecodeError as e:
+            return {"ok": False, "error": f"arguments are not valid JSON: {e}"}
+
+    try:
+        spec = spec_cls.model_validate(arguments)
+    except ValidationError as e:
+        return {"ok": False, "error": f"invalid arguments: {e}"}
+
+    template = (templates or {}).get(template_key) if template_key else None
+    try:
+        if template_key:
+            path = render(spec, Path(out_dir), template=template)
+        else:
+            path = render(spec, Path(out_dir))
+    except Exception as e:  # surface renderer failures to the model
+        return {"ok": False, "error": f"failed to render: {e}"}
+    return {"ok": True, "file": str(path)}

altr_oss-0.2.0.dist-info/METADATA

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: altr-oss
+Version: 0.2.0
+Summary: Open source doc / excel / ppt skills for LLMs - Groq, Ollama, vLLM, any OpenAI-compatible endpoint.
+Project-URL: Homepage, https://github.com/PasinduSuraweera/altr-oss
+Author: Pasindu Suraweera
+License: MIT License
+        
+        Copyright (c) 2026 Pasindu Suraweera
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        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.
+License-File: LICENSE
+Keywords: docx,gpt-oss,groq,llm,pptx,skills,tool-calling,xlsx
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT 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: Topic :: Office/Business :: Office Suites
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: openai>=1.40
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: pydantic>=2.7
+Requires-Dist: python-docx>=1.1
+Requires-Dist: python-pptx>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# altr
+
+> Open source doc / excel / ppt skills for LLMs.
+
+[![CI](https://github.com/PasinduSuraweera/altr-oss/actions/workflows/ci.yml/badge.svg)](https://github.com/PasinduSuraweera/altr-oss/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
+
+Claude has document skills. ChatGPT has them. **Open-weight models don't.**
+Point `gpt-oss-120b` on Groq (or any model behind an OpenAI-compatible API) at
+altr and it gains three tools it can call to produce real files:
+
+| Tool                  | Output  | Good for                                   |
+| --------------------- | ------- | ------------------------------------------ |
+| `create_document`     | `.docx` | reports, guides, letters, meeting notes    |
+| `create_spreadsheet`  | `.xlsx` | budgets, trackers, datasets - with formulas |
+| `create_presentation` | `.pptx` | pitch decks, talks - with speaker notes    |
+
+The model sends structured JSON through standard tool calling; altr
+validates it (Pydantic) and renders it (`python-docx`, `openpyxl`,
+`python-pptx`). Renderer errors are fed back to the model so it can correct
+itself. No code execution, no sandboxes - the model can only emit document
+content.
+
+## Install
+
+```sh
+pip install altr-oss
+```
+
+The PyPI distribution is `altr-oss`; the import and the CLI command are both
+plain `altr`.
+
+Or straight from the repo:
+
+```sh
+pip install git+https://github.com/PasinduSuraweera/altr-oss
+```
+
+## Quickstart (CLI)
+
+```sh
+export GROQ_API_KEY=gsk_...
+
+altr make "Create a 6-slide pitch deck for a solar-powered drone startup"
+altr make "Make a 12-month SaaS budget spreadsheet with formula totals"
+altr make "Write a 2-page onboarding doc for new backend engineers"
+```
+
+Files land in `./output`. Works with any OpenAI-compatible server:
+
+```sh
+# Groq (default)
+altr make "..." --model openai/gpt-oss-120b
+
+# Ollama, fully local
+altr make "..." --base-url http://localhost:11434/v1 --model llama3.3 --api-key ollama
+
+# vLLM / LM Studio / anything else that speaks chat completions
+altr make "..." --base-url http://localhost:8000/v1 --model my-model
+```
+
+Render a JSON spec directly, no model involved (great for testing):
+
+```sh
+altr render presentation examples/pitch-deck.json
+altr render spreadsheet examples/budget.json
+altr render document examples/onboarding-doc.json
+```
+
+## Use it as a library
+
+```python
+from altr import OfficeAgent
+
+agent = OfficeAgent(model="openai/gpt-oss-120b", out_dir="out")
+result = agent.run("Create a quarterly report with a KPI table")
+print(result.files)   # [PosixPath('out/quarterly-report.docx')]
+print(result.reply)   # the model's final message
+```
+
+## Use it as a skill in your own agent
+
+Already have an agent loop? Take just the tools:
+
+```python
+from altr import SYSTEM_PROMPT, get_tools, dispatch
+
+response = client.chat.completions.create(
+    model="openai/gpt-oss-120b",
+    messages=[{"role": "system", "content": SYSTEM_PROMPT}, ...],
+    tools=get_tools(),          # OpenAI-format tool definitions
+)
+
+for call in response.choices[0].message.tool_calls:
+    result = dispatch(call.function.name, call.function.arguments, out_dir="out")
+    # {"ok": True, "file": "out/report.docx"}  - or {"ok": False, "error": ...}
+```
+
+`dispatch` never raises on bad model output - validation and render errors come
+back as data you can hand to the model for self-correction.
+
+## What the model can express
+
+- **Documents**: headings (9 levels), paragraphs with inline
+  **bold**/*italic*/`code`, bullet & numbered lists, tables with bold headers,
+  images with captions, whole markdown blocks, page breaks.
+- **Spreadsheets**: multiple worksheets, bold header rows, column widths,
+  frozen header rows, live Excel formulas (`=SUM(B2:B10)`), and bar/line/pie
+  charts built from the sheet's data.
+- **Presentations**: title slides, section dividers, bulleted slides with
+  indent levels, chart slides, full-width image slides, speaker notes.
+
+Filenames from the model are sanitized to their base name, so output can never
+escape the output directory. Image paths must point at existing local files -
+the system prompt tells the model to only use files you mention.
+
+## Brand templates
+
+Start every generated file from your own template so fonts, colors, and slide
+masters match your brand:
+
+```sh
+altr make "..." --docx-template brand.docx --pptx-template brand.pptx
+altr render presentation deck.json --template brand.pptx
+```
+
+Custom `.pptx` templates must keep the stock layout order (0 title,
+1 title+content, 2 section header, 5 title only).
+
+## PDF export
+
+Pass `--pdf` to `make` or `render` to also export each created file as PDF.
+Requires LibreOffice (`soffice`) on your PATH. From Python:
+
+```python
+from altr import to_pdf
+to_pdf("output/report.docx")
+```
+
+## Roadmap
+
+- [ ] Recipe/preset library of reusable prompts
+- [ ] Chart styling options (colors, axis titles, legends)
+- [ ] Nested markdown lists and blockquotes
+- [ ] Watermarks and headers/footers
+
+## Contributing
+
+PRs welcome - see [CONTRIBUTING.md](CONTRIBUTING.md). Good first issues:
+roadmap items above, or new block types for the document schema.
+
+## License
+
+[MIT](LICENSE) © Pasindu Suraweera

altr_oss-0.2.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+altr/__init__.py,sha256=557k_EfSQsia3iZ7qkTJFn_8FQgHx-DZYnFXY3tD63o,635
+altr/agent.py,sha256=bqHAswOupvhF1Xa-ksOO07a-TtSs98ql0uC5qk2b7YA,3717
+altr/cli.py,sha256=3v2wejkFAmzTZOJ_WEQcNpTnwgnAfJsIjc-fChamIiE,3901
+altr/markdown.py,sha256=2Buob3DDU_m9FmOgV1Y9C1uArLHIxPsPaG4DobvBSCs,3309
+altr/pdf.py,sha256=SVIsFNedhFr8GnlfvEuUBYkIOyzEm7RbtxWw6EgudVI,1251
+altr/prompts.py,sha256=2C0Pc77GYUVFcOjRzSI11huRgqcGS1FzMLm6QFTUvws,1440
+altr/schemas.py,sha256=ojgIG9tYsKKaH3bsh4TtyIbRLHUg8Uug_HqWHAwjBSE,6307
+altr/tools.py,sha256=ceN37TYe0UG7ujuF79bs99C1MOluPPAgpcxTDhSskBA,3452
+altr/renderers/__init__.py,sha256=LXfYjOoG7g-iH_sMLhH6QUyYUWAMtNWj0ymrBXndvAg,800
+altr/renderers/docx.py,sha256=1skG8Oafn2zzEfn1-B4N7cUfy7skH8Gvd0NYEHuagfs,2773
+altr/renderers/pptx.py,sha256=s3KO2iljQRVAoMDNxIhQBNBaOw9FbdJnTRBtfK1Fkrg,3051
+altr/renderers/xlsx.py,sha256=Tm6fQouaCrEfY0xgro5DLrQikaVmJVFwFiBKmH-lyJA,2465
+altr_oss-0.2.0.dist-info/METADATA,sha256=bnZTZqT031k3ZoyTxanwLLr0vNRQ_E2yqQB1nLsZmsY,7579
+altr_oss-0.2.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+altr_oss-0.2.0.dist-info/entry_points.txt,sha256=VH5Lm7ca5UbF7e1DhnjMOQcE7rBarodnt3vCRPhWsIA,39
+altr_oss-0.2.0.dist-info/licenses/LICENSE,sha256=89BZWbKYY4VKs3SoPPyQnzpGncMgkX8KCImF2gp87_E,1074
+altr_oss-0.2.0.dist-info/RECORD,,

altr_oss-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

altr_oss-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+altr = altr.cli:main

altr_oss-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pasindu Suraweera
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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.