Metadata-Version: 2.4
Name: concinno-skills-office
Version: 0.1.0
Summary: Local Office document skills (Word/Excel/PowerPoint/docx-template) for Concinno — native Python libraries, no MS 365 API. docxtpl LGPL-2.1 dynamic link.
Project-URL: Homepage, https://github.com/aiking931931/concinno
Project-URL: Issues, https://github.com/aiking931931/concinno/issues
Project-URL: Changelog, https://github.com/aiking931931/concinno/blob/main/projects/concinno-skills-office/CHANGELOG.md
Author-email: "AI King (Chen-Xuan Wang)" <me@ai-king.dev>
License-Expression: Apache-2.0
Keywords: agent,concinno,docx,excel,office,powerpoint,pptx,skills,word,xlsx
Classifier: Development Status :: 4 - Beta
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 :: Office/Business
Classifier: Topic :: Office/Business :: Office Suites
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: concinno>=2.15.1
Requires-Dist: docxtpl>=0.19
Requires-Dist: openpyxl>=3.1
Requires-Dist: python-docx>=1.1
Requires-Dist: python-pptx>=1.0
Requires-Dist: xlsxwriter>=3.2
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.7; extra == 'dev'
Description-Content-Type: text/markdown

# concinno-skills-office

Local Office document skills for [Concinno](https://pypi.org/project/concinno/).
Native Python libraries, no Microsoft 365 / Graph API round-trip, no network.

## Status

MVP (0.1.0) — five tools covering the core four-quadrant of local Office
document creation:

| Tool | Library | Purpose |
|---|---|---|
| `WordCreate`   | `python-docx` | build a .docx from heading / paragraphs / tables |
| `ExcelWrite`   | `openpyxl`    | build a .xlsx, write rows and formulas |
| `ExcelChart`   | `XlsxWriter`  | build a .xlsx containing a bar / line / pie chart |
| `PptCreate`    | `python-pptx` | build a .pptx from a list of slide dicts |
| `DocxTemplate` | `docxtpl`     | render a Jinja2 `.docx` template |

Future versions will extend the existing tools (images, styles, more
chart types) without bumping Concinno itself. A separate
`concinno-skills-office-365` sibling package will host the Microsoft
Graph API path when it ships; this package will never gain a cloud
dependency.

## Install

```bash
pip install concinno-skills-office
```

All five document libraries are hard dependencies — pulled in
automatically. The package is useless without them.

## License notes

The package itself is **Apache-2.0**. However `docxtpl` is licensed under
**LGPL-2.1**. We depend on it as a pip dependency — a dynamic link — so
the re-link rights the LGPL requires are preserved for any downstream
consumer that pip-installs Office skills the normal way.

If you statically bundle this package into a single-file binary (e.g.
PyInstaller with `--onefile`) the bundle's redistribution terms must
satisfy LGPL-2.1 §6 for the `docxtpl` code path specifically. The
upstream `docxtpl` project lives at
<https://github.com/elapouya/python-docx-template>.

## Safety

Every tool validates its ``output_path`` / ``template_path`` kwarg
before touching disk:

1. Must be a non-empty string.
2. After `Path.resolve()` it must live under either `Path.home()` or
   `Path.cwd()`.
3. It may not live under a well-known system root (`/etc`, `/Windows`,
   `/System`, `/Program Files`, …) — guards against the `HOME=/` edge
   case.

Violations return ``{"error": "..."}`` rather than writing the file.

## Usage via Concinno `ToolRegistry`

When the consumer sets `CONCINNO_LOAD_PLUGINS=1`, the default registry
auto-mounts all five tools:

```python
import os
os.environ["CONCINNO_LOAD_PLUGINS"] = "1"

from concinno.tools.registry import get_default_registry

reg = get_default_registry()
for name in (
    "WordCreate",
    "ExcelWrite",
    "ExcelChart",
    "PptCreate",
    "DocxTemplate",
):
    assert name in reg.list_deferred()
```

## Direct Python usage

```python
from concinno_skills_office import (
    WordCreate, ExcelWrite, ExcelChart, PptCreate, DocxTemplate,
)

# Word: heading + paragraphs + a table.
WordCreate().call(
    action="create",
    output_path="./report.docx",
    heading="Quarterly Report",
    paragraphs=["Summary paragraph.", "Details below."],
    tables=[[["Metric", "Value"], ["Revenue", "$1.2M"]]],
)

# Excel: rows + formula.
ExcelWrite().call(
    action="create",
    output_path="./sheet.xlsx",
    sheet="Sales",
    rows=[
        ["Name", "Units", "Total"],
        ["A", 10, "=B2*5"],
        ["B", 20, "=B3*5"],
    ],
)

# Excel + chart.
ExcelChart().call(
    action="create",
    output_path="./chart.xlsx",
    sheet="Data",
    rows=[["Q1", 10], ["Q2", 20], ["Q3", 15], ["Q4", 30]],
    chart={
        "type": "bar",
        "title": "Quarterly",
        "categories": "A1:A4",
        "values": "B1:B4",
    },
)

# PowerPoint.
PptCreate().call(
    action="create",
    output_path="./deck.pptx",
    slides=[
        {"title": "Agenda", "content": ["Intro", "Body", "Q&A"]},
        {"title": "Outro", "content": ["Thanks."]},
    ],
)

# Docx template render.
DocxTemplate().call(
    action="render",
    template_path="./letter_template.docx",
    context={"name": "Alice", "date": "2026-04-22"},
    output_path="./letter_alice.docx",
)
```

All tools return either `{"ok": True, ...}` on success or
`{"error": "..."}` on any validation or library failure — matching the
shape of other Concinno built-in tools.

## License

Apache-2.0. See `LICENSE` in the Concinno monorepo.
