Office-Editor

## Follow These Rules First

1. Confirm the target format first: Word uses `python-docx`, Excel uses `openpyxl`, and PowerPoint uses `python-pptx`.
2. Check whether the required dependency can be imported. If something is missing, tell the user exactly which package is required. Do not run `pip`, `pip3`, `python -m pip`, `sudo`, or similar install commands automatically.
3. When editing an existing file, preserve the original by default and save the result as a new file. Only overwrite the original if the user explicitly asks for that.
4. Do structural edits before visual fine-tuning. Avoid writing a large amount of low-value formatting code upfront.
5. Only open the matching document in `references/` when an advanced API is needed. Do not load every reference file into context at once.

## Dependency Tiers

### Core Dependencies

- `python-docx`: for Word documents.
- `openpyxl`: for Excel workbooks.
- `python-pptx`: for PowerPoint presentations.

### Optional Dependencies

- `pandas`: only needed when converting between DataFrames and Excel.
- `pillow`: only needed when inserting images into Excel.

## Check Dependencies

Use a read-only import check like this. If the check fails, stop implementation and report the missing package(s) directly.

```python
import importlib

PACKAGE_MAP = {
    "docx": "python-docx",
    "openpyxl": "openpyxl",
    "pptx": "python-pptx",
    "pandas": "pandas",
    "PIL": "pillow",
}

missing = []
for module_name, package_name in PACKAGE_MAP.items():
    try:
        importlib.import_module(module_name)
    except ModuleNotFoundError:
        missing.append(package_name)

print(missing)
```

Choose what to check based on the task:

- `.docx` tasks: check `docx`
- `.xlsx` tasks: check `openpyxl`
- `.pptx` tasks: check `pptx`
- DataFrame-related Excel tasks: also check `pandas`
- Excel image tasks: also check `PIL`

## Handle Word Documents

Use `python-docx` for `.docx` files.

### Create a New File

```python
from docx import Document

document = Document()
document.add_heading("Document Title", level=1)
document.add_paragraph("This is a paragraph.")
document.save("new_doc.docx")
```

### Modify an Existing File

```python
from docx import Document

document = Document("existing_doc.docx")
document.add_paragraph("Appended content")
document.save("updated_doc.docx")
```

### Read These Resources First

- Core API summary: `{baseDir}/references/docx_api_summary.md`
- Create example: `{baseDir}/scripts/create_basic_doc.py`
- Edit example: `{baseDir}/scripts/edit_existing_doc.py`

## Handle Excel Workbooks

Use `openpyxl` for `.xlsx` files.

### Create a New File

```python
from openpyxl import Workbook

wb = Workbook()
ws = wb.active
ws.title = "Data"
ws["A1"] = "Hello"
ws.append(["Data 1", "Data 2", "Data 3"])
wb.save("new_workbook.xlsx")
```

### Modify an Existing File

```python
from openpyxl import load_workbook

wb = load_workbook("existing_workbook.xlsx")
ws = wb["Sheet1"]
ws["A1"] = "Updated value"
wb.save("updated_workbook.xlsx")
```

### Read These Resources First

- Create example: `{baseDir}/scripts/create_basic_workbook.py`
- Charts: `{baseDir}/references/xlsx_charts.md`
- Advanced features: `{baseDir}/references/xlsx_features.md`
- DataFrame integration: `{baseDir}/references/xlsx_pandas.md`

## Handle PowerPoint Presentations

Use `python-pptx` for `.pptx` files.

### Create a New File

```python
from pptx import Presentation

prs = Presentation()
slide = prs.slides.add_slide(prs.slide_layouts[1])
slide.shapes.title.text = "Slide Title"
slide.placeholders[1].text = "This is the content placeholder."
prs.save("new_presentation.pptx")
```

### Modify an Existing File

```python
from pptx import Presentation

prs = Presentation("existing_presentation.pptx")
slide = prs.slides.add_slide(prs.slide_layouts[1])
slide.shapes.title.text = "New Slide"
slide.placeholders[1].text = "Additional content"
prs.save("updated_presentation.pptx")
```

### Read These Resources First

- API quick reference: `{baseDir}/references/pptx_api_reference.md`
- Chart guide: `{baseDir}/references/pptx_chart_guide.md`
- Full example: `{baseDir}/scripts/create_presentation.py`

## Resource Selection Rules

- Basic Word file creation only: start with `{baseDir}/scripts/create_basic_doc.py`
- Modify an existing Word file: start with `{baseDir}/scripts/edit_existing_doc.py`
- Basic Excel creation only: start with `{baseDir}/scripts/create_basic_workbook.py`
- Excel charts or conditional formatting: read `{baseDir}/references/xlsx_charts.md` or `{baseDir}/references/xlsx_features.md` first
- DataFrame, CSV to Excel, or worksheet analysis: confirm `pandas` is available, then read `{baseDir}/references/xlsx_pandas.md`
- Basic PowerPoint generation only: start with `{baseDir}/scripts/create_presentation.py`
- PowerPoint charts: read `{baseDir}/references/pptx_chart_guide.md` first

## Output Rules

- Always save to a concrete target filename. Do not leave changes only in memory.
- If the user does not provide a filename, use a clear default such as `report.docx`, `budget.xlsx`, or `deck.pptx`.
- For edits to existing files, default to `updated_*.ext` to avoid accidental overwrites.