recombinase 0.1.0__tar.gz

recombinase-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.pytest_cache/
+.coverage
+htmlcov/
+*.pptx
+*.pptm
+!tests/fixtures/*.pptx
+!examples/*.pptx

recombinase-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Terry Li
+
+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.

recombinase-0.1.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: recombinase
+Version: 0.1.0
+Summary: Template-guided document synthesis: extract structured content from source pptx files and recombine into a canonical template
+Project-URL: Homepage, https://github.com/terry-li-hm/recombinase
+Project-URL: Issues, https://github.com/terry-li-hm/recombinase/issues
+Author: Terry Li
+License-Expression: MIT
+License-File: LICENSE
+Keywords: credentials,cv,extraction,generation,powerpoint,pptx,template
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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 :: Text Processing
+Requires-Python: >=3.10
+Requires-Dist: python-pptx>=0.6.23
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# recombinase
+
+> Biology: a recombinase is an enzyme that extracts DNA fragments and recombines them into new molecules using a homologous template as the structural guide. This package does the same for PowerPoint documents.
+
+Template-guided pptx synthesis. Take a styled "filled example" slide in a `.pptx`/`.pptm` template, a folder of per-record YAML data files, and produce a populated output deck — one slide per record, visually identical to the template because the fill operation duplicates the source slide and replaces text in-place by shape name.
+
+## Install
+
+```
+pip install --user recombinase
+```
+
+Or from source:
+
+```
+git clone https://github.com/terry-li-hm/recombinase.git
+cd recombinase
+pip install --user -e .
+```
+
+Dependencies: `python-pptx`, `pyyaml`. That's it.
+
+## Concepts
+
+**Three steps**, loosely coupled by file:
+
+1. **Template** — a `.pptx`/`.pptm` file with at least one slide where every field you want to populate is a named shape (e.g. a text box named `Consultant_Name`).
+2. **Config** — a small YAML file declaring which shape name on the template corresponds to which data field. One config per template. Templates change; configs go with them.
+3. **Data** — a directory of per-record YAML files, one file per record (e.g. one per consultant). Each file has a flat map of field names to values. List values become bullet paragraphs automatically.
+
+The template config is intentionally per-template rather than hardcoded in the package. Same package, different config → different template. You can build a CV pack, a use-case slide deck, or a client case study collection with the same tool and three different configs.
+
+## Usage
+
+### 1. Inspect a template
+
+Discover the shape names on each slide — structural metadata only, never the actual text content. Safe to share the output.
+
+```
+recombinase inspect "path/to/template.pptm"
+```
+
+Example output:
+
+```
+File: /path/to/template.pptm
+Slide count: 1
+
+=== Slide 1 (layout: 'Blank') ===
+  - 'Consultant_Name' | type=TEXT_BOX (17) | text_chars=12 | paras=1, runs=1
+  - 'Role_Title' | type=TEXT_BOX (17) | text_chars=18 | paras=1, runs=1
+  - 'Summary_Body' | type=TEXT_BOX (17) | text_chars=140 | paras=2, runs=3
+  - 'Background_Bullets' | type=TEXT_BOX (17) | text_chars=220 | paras=5, runs=5
+```
+
+### 2. Scaffold a config
+
+Generate a starter config file from the template's shape names:
+
+```
+recombinase init "path/to/template.pptm" --output template-config.yaml
+```
+
+This reads the shape names from slide 1 and writes a config like:
+
+```yaml
+template: /path/to/template.pptm
+source_slide_index: 1
+clear_source_slide: true
+
+placeholders:
+  consultant_name: Consultant_Name
+  role_title: Role_Title
+  summary_body: Summary_Body
+  background_bullets: Background_Bullets
+```
+
+Edit the left side (data field names) to match how your records are keyed. For example, if your YAML data files use `name:` not `consultant_name:`, rename the left side:
+
+```yaml
+placeholders:
+  name: Consultant_Name
+  role: Role_Title
+  summary: Summary_Body
+  background: Background_Bullets
+```
+
+### 3. Write per-record data files
+
+Create a directory with one YAML file per record. Filenames become the sort order:
+
+```
+cv-data/
+├── 01-jane-doe.yaml
+├── 02-john-smith.yaml
+└── 03-alice-wong.yaml
+```
+
+Each file is a flat map — lists become bullet paragraphs:
+
+```yaml
+id: jane-doe
+name: Jane Doe
+role: Senior Consultant
+summary: >-
+  Twelve years across global wealth management with a focus on
+  regulatory data and risk modelling.
+background:
+  - Bank A — Risk modelling lead (2010-2015)
+  - Bank B — Head of analytics (2015-2020)
+  - Bank C — CDO, Asia Pacific (2020-present)
+key_skills:
+  - Risk modelling
+  - Governance
+  - Wealth data architecture
+```
+
+The field names on the left must match the keys in your template config's `placeholders:` section.
+
+### 4. Generate the output deck
+
+```
+recombinase generate \
+  --config template-config.yaml \
+  --data-dir cv-data/ \
+  --output output/deck.pptx
+```
+
+Produces a populated pptx with one slide per YAML file. If `clear_source_slide: true` in the config, the original example slide is removed from the output.
+
+### One-line end-to-end
+
+After the config exists:
+
+```
+recombinase generate -c template-config.yaml -d cv-data/ -o out.pptx
+```
+
+## Design notes
+
+### Why duplicate a filled example slide?
+
+The alternative is creating slides from a layout and writing text into empty placeholders. That approach loses any hand-tweaks the template designer made (custom colours, tweaked positions, decorative shapes, non-placeholder elements). Duplicating a known-good filled slide inherits 100% of its visual styling by design — `deepcopy` of the shape tree carries every property.
+
+Trade-off: the template must contain one "canonical good example" slide to clone from. This is usually natural for CV templates and pack-prep work.
+
+### Rich text and the flattening caveat
+
+When a value is written into a shape with `shape.text_frame.text = "..."`, rich-text runs within that shape (bold name, italic subtitle in one text frame) collapse to the placeholder's default run style. For most modern consulting templates this isn't an issue — each styled fragment lives in its own shape. If your template has a multi-run placeholder, either split it into separate shapes or accept the flattening.
+
+### Variable-length lists
+
+List values in the YAML data become separate paragraphs in the target text frame, inheriting the placeholder's paragraph-level bullet formatting automatically. No bullet markers in the source data — the template supplies them. A consultant with three background bullets and another with seven both work without any config change.
+
+### Warnings, not errors
+
+If a config references a shape name that doesn't exist, or a record is missing a field, `generate` produces a **warning** but continues. This is deliberate: partial output is more useful than total failure during iteration. Pass `--strict` if you want non-zero exit on warnings.
+
+## Scope (v0.1)
+
+- ✓ Inspect: print template structural metadata
+- ✓ Init: scaffold a config from shape names
+- ✓ Generate: populate template from YAML records
+- ✗ Extract: reverse direction (pptx → YAML) — v0.2 — needs a sample source file for structure before it can be implemented reliably
+
+## License
+
+MIT

recombinase-0.1.0/README.md

@@ -0,0 +1,168 @@
+# recombinase
+
+> Biology: a recombinase is an enzyme that extracts DNA fragments and recombines them into new molecules using a homologous template as the structural guide. This package does the same for PowerPoint documents.
+
+Template-guided pptx synthesis. Take a styled "filled example" slide in a `.pptx`/`.pptm` template, a folder of per-record YAML data files, and produce a populated output deck — one slide per record, visually identical to the template because the fill operation duplicates the source slide and replaces text in-place by shape name.
+
+## Install
+
+```
+pip install --user recombinase
+```
+
+Or from source:
+
+```
+git clone https://github.com/terry-li-hm/recombinase.git
+cd recombinase
+pip install --user -e .
+```
+
+Dependencies: `python-pptx`, `pyyaml`. That's it.
+
+## Concepts
+
+**Three steps**, loosely coupled by file:
+
+1. **Template** — a `.pptx`/`.pptm` file with at least one slide where every field you want to populate is a named shape (e.g. a text box named `Consultant_Name`).
+2. **Config** — a small YAML file declaring which shape name on the template corresponds to which data field. One config per template. Templates change; configs go with them.
+3. **Data** — a directory of per-record YAML files, one file per record (e.g. one per consultant). Each file has a flat map of field names to values. List values become bullet paragraphs automatically.
+
+The template config is intentionally per-template rather than hardcoded in the package. Same package, different config → different template. You can build a CV pack, a use-case slide deck, or a client case study collection with the same tool and three different configs.
+
+## Usage
+
+### 1. Inspect a template
+
+Discover the shape names on each slide — structural metadata only, never the actual text content. Safe to share the output.
+
+```
+recombinase inspect "path/to/template.pptm"
+```
+
+Example output:
+
+```
+File: /path/to/template.pptm
+Slide count: 1
+
+=== Slide 1 (layout: 'Blank') ===
+  - 'Consultant_Name' | type=TEXT_BOX (17) | text_chars=12 | paras=1, runs=1
+  - 'Role_Title' | type=TEXT_BOX (17) | text_chars=18 | paras=1, runs=1
+  - 'Summary_Body' | type=TEXT_BOX (17) | text_chars=140 | paras=2, runs=3
+  - 'Background_Bullets' | type=TEXT_BOX (17) | text_chars=220 | paras=5, runs=5
+```
+
+### 2. Scaffold a config
+
+Generate a starter config file from the template's shape names:
+
+```
+recombinase init "path/to/template.pptm" --output template-config.yaml
+```
+
+This reads the shape names from slide 1 and writes a config like:
+
+```yaml
+template: /path/to/template.pptm
+source_slide_index: 1
+clear_source_slide: true
+
+placeholders:
+  consultant_name: Consultant_Name
+  role_title: Role_Title
+  summary_body: Summary_Body
+  background_bullets: Background_Bullets
+```
+
+Edit the left side (data field names) to match how your records are keyed. For example, if your YAML data files use `name:` not `consultant_name:`, rename the left side:
+
+```yaml
+placeholders:
+  name: Consultant_Name
+  role: Role_Title
+  summary: Summary_Body
+  background: Background_Bullets
+```
+
+### 3. Write per-record data files
+
+Create a directory with one YAML file per record. Filenames become the sort order:
+
+```
+cv-data/
+├── 01-jane-doe.yaml
+├── 02-john-smith.yaml
+└── 03-alice-wong.yaml
+```
+
+Each file is a flat map — lists become bullet paragraphs:
+
+```yaml
+id: jane-doe
+name: Jane Doe
+role: Senior Consultant
+summary: >-
+  Twelve years across global wealth management with a focus on
+  regulatory data and risk modelling.
+background:
+  - Bank A — Risk modelling lead (2010-2015)
+  - Bank B — Head of analytics (2015-2020)
+  - Bank C — CDO, Asia Pacific (2020-present)
+key_skills:
+  - Risk modelling
+  - Governance
+  - Wealth data architecture
+```
+
+The field names on the left must match the keys in your template config's `placeholders:` section.
+
+### 4. Generate the output deck
+
+```
+recombinase generate \
+  --config template-config.yaml \
+  --data-dir cv-data/ \
+  --output output/deck.pptx
+```
+
+Produces a populated pptx with one slide per YAML file. If `clear_source_slide: true` in the config, the original example slide is removed from the output.
+
+### One-line end-to-end
+
+After the config exists:
+
+```
+recombinase generate -c template-config.yaml -d cv-data/ -o out.pptx
+```
+
+## Design notes
+
+### Why duplicate a filled example slide?
+
+The alternative is creating slides from a layout and writing text into empty placeholders. That approach loses any hand-tweaks the template designer made (custom colours, tweaked positions, decorative shapes, non-placeholder elements). Duplicating a known-good filled slide inherits 100% of its visual styling by design — `deepcopy` of the shape tree carries every property.
+
+Trade-off: the template must contain one "canonical good example" slide to clone from. This is usually natural for CV templates and pack-prep work.
+
+### Rich text and the flattening caveat
+
+When a value is written into a shape with `shape.text_frame.text = "..."`, rich-text runs within that shape (bold name, italic subtitle in one text frame) collapse to the placeholder's default run style. For most modern consulting templates this isn't an issue — each styled fragment lives in its own shape. If your template has a multi-run placeholder, either split it into separate shapes or accept the flattening.
+
+### Variable-length lists
+
+List values in the YAML data become separate paragraphs in the target text frame, inheriting the placeholder's paragraph-level bullet formatting automatically. No bullet markers in the source data — the template supplies them. A consultant with three background bullets and another with seven both work without any config change.
+
+### Warnings, not errors
+
+If a config references a shape name that doesn't exist, or a record is missing a field, `generate` produces a **warning** but continues. This is deliberate: partial output is more useful than total failure during iteration. Pass `--strict` if you want non-zero exit on warnings.
+
+## Scope (v0.1)
+
+- ✓ Inspect: print template structural metadata
+- ✓ Init: scaffold a config from shape names
+- ✓ Generate: populate template from YAML records
+- ✗ Extract: reverse direction (pptx → YAML) — v0.2 — needs a sample source file for structure before it can be implemented reliably
+
+## License
+
+MIT

recombinase-0.1.0/examples/consultant.example.yaml

@@ -0,0 +1,46 @@
+# Example per-record data file for recombinase.
+#
+# One file per record (e.g. one per consultant). File names become the sort
+# order in the output deck, so prefix with 01-, 02-, etc. if you want a
+# specific ordering.
+#
+# The field names on the LEFT must match the keys in your template config's
+# `placeholders:` section. Values can be scalar strings, integers, or lists.
+# Lists become separate paragraphs (bullet points) in the target shape,
+# inheriting the template's paragraph-level bullet formatting automatically.
+
+id: jane-doe
+name: Jane Doe
+role: Senior Consultant
+years_experience: 12
+
+summary: >-
+  Wealth-data specialist with twelve years across global banking and
+  consulting. Led data governance and AI strategy engagements at
+  tier-1 APAC financial institutions.
+
+background:
+  - Bank A — Risk modelling lead (2010-2015)
+  - Bank B — Head of analytics (2015-2020)
+  - Bank C — Chief Data Officer, Asia Pacific (2020-present)
+
+key_skills:
+  - Risk modelling and stress testing
+  - AI governance and model risk management
+  - Wealth data architecture
+  - Regulatory reporting automation
+
+clients:
+  - HSBC
+  - UBS
+  - DBS
+
+qualifications:
+  - CFA Charterholder
+  - FRM
+  - MSc Financial Engineering
+
+languages:
+  - English (native)
+  - Cantonese (fluent)
+  - Mandarin (working)

recombinase-0.1.0/examples/template-config.example.yaml

@@ -0,0 +1,33 @@
+# Example template config for recombinase.
+#
+# One config per pptx template. The `template:` path can be absolute or
+# relative to this config file's directory. The `placeholders:` section
+# maps data field names (left) to the shape .Name property in the template
+# (right). You find the shape names by running `recombinase inspect` or
+# `recombinase init` on the template first.
+
+template: ./CV_template.pptx
+
+# 1-based index of the slide inside the template that should be duplicated
+# once per record. Usually this is the "filled example" slide that's already
+# styled correctly.
+source_slide_index: 1
+
+# Remove the source (example) slide from the final output so only the
+# generated per-record slides remain. Set to false if you want the example
+# preserved as slide 1 of the output for reference.
+clear_source_slide: true
+
+# Map from data field name → shape .Name in the template.
+# The LEFT side must match the keys in your per-record YAML data files.
+# The RIGHT side must match the shape names reported by `recombinase inspect`.
+placeholders:
+  name: Consultant_Name
+  role: Role_Title
+  years_experience: Years_Experience
+  summary: Summary_Body
+  background: Background_Bullets
+  key_skills: Key_Skills
+  clients: Clients_Served
+  qualifications: Qualifications
+  languages: Languages

recombinase-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "recombinase"
+version = "0.1.0"
+description = "Template-guided document synthesis: extract structured content from source pptx files and recombine into a canonical template"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "Terry Li" },
+]
+keywords = ["pptx", "powerpoint", "template", "cv", "credentials", "extraction", "generation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business",
+    "Topic :: Text Processing",
+]
+dependencies = [
+    "python-pptx>=0.6.23",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+]
+
+[project.scripts]
+recombinase = "recombinase.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/terry-li-hm/recombinase"
+Issues = "https://github.com/terry-li-hm/recombinase/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/recombinase"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100

recombinase-0.1.0/src/recombinase/__init__.py

@@ -0,0 +1,21 @@
+"""recombinase — template-guided document synthesis.
+
+Biology: a recombinase is an enzyme that extracts DNA fragments and recombines
+them into new molecules using a homologous template as the structural guide.
+This package does the same for PowerPoint documents: extract content from
+heterogeneous source files, then recombine into a canonical template.
+"""
+
+from recombinase.config import TemplateConfig, load_config
+from recombinase.generate import generate_deck
+from recombinase.inspect import inspect_template
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "TemplateConfig",
+    "load_config",
+    "generate_deck",
+    "inspect_template",
+    "__version__",
+]