python-hwpx-automation 6.1.3__tar.gz → 6.3.1__tar.gz

{python_hwpx_automation-6.1.3/src/python_hwpx_automation.egg-info → python_hwpx_automation-6.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx-automation
-Version: 6.1.3
+Version: 6.3.1
 Summary: Task-oriented HWPX document automation for Python, with an optional MCP adapter.
 Author: Kohkyuhyun
 License-Expression: Apache-2.0
@@ -20,7 +20,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: NOTICE
-Requires-Dist: python-hwpx<6,>=5.1.0
+Requires-Dist: python-hwpx<6,>=5.3.0
 Requires-Dist: pydantic<3,>=2.11
 Requires-Dist: cryptography>=42.0
 Requires-Dist: anyio>=4.0
@@ -74,11 +74,12 @@ Dynamic: license-file
 
 <!-- release-state: release-approved -->
 > [!NOTE]
-> 이 소스 트리는 아직 공개되지 않은 6.1.3 후보입니다(누름틀 필드 저작
-> `add_form_field`, 계약 `ac1a422376b5ac84`, 128 도구). 현재 공개 트레인은
-> `python-hwpx 5.0.2 → python-hwpx-automation 6.0.4 → hwpx-plugin 1.0.1`
-> (계약 `0ce938371f0b55a6`)입니다. core·automation PyPI와 plugin GitHub
-> Release·marketplace·실제 marketplace 설치까지 확인한 뒤 승격하며, 기존
+> 이 저장소의 main은 아직 공개되지 않은 6.3.1 후보 — release-approved 상태(네이티브 차트 생성
+> `add_chart`, 계약 `236f8ea855c875fe`, 130 도구)입니다. 현재 공개 트레인은
+> `python-hwpx 5.2.0 → python-hwpx-automation 6.2.1 → hwpx-plugin 1.2.0`
+> (계약 `342cf672f29cd183`, 2026-07-31 released)입니다. 공개 트레인은
+> core·automation PyPI와 plugin GitHub
+> Release·marketplace·실제 marketplace 설치까지 확인한 뒤 승격했으며, 기존
 > 5.x 설치는 별도 발행된 `hwpx-mcp-server 5.1.1`이 보호합니다. 절차와 상태
 > 머신: [릴리스 runbook](docs/release-runbook.md)
 
@@ -134,7 +135,7 @@ Gemini CLI는 `~/.gemini/settings.json`, Cursor·Windsurf는 각 에디터의 MC
       "command": "uvx",
       "args": [
         "--from",
-        "python-hwpx-automation[mcp]==6.0.4",
+        "python-hwpx-automation[mcp]==6.1.3",
         "hwpx-automation-mcp"
       ],
       "env": {

{python_hwpx_automation-6.1.3 → python_hwpx_automation-6.3.1}/README.md

@@ -14,11 +14,12 @@
 
 <!-- release-state: release-approved -->
 > [!NOTE]
-> 이 소스 트리는 아직 공개되지 않은 6.1.3 후보입니다(누름틀 필드 저작
-> `add_form_field`, 계약 `ac1a422376b5ac84`, 128 도구). 현재 공개 트레인은
-> `python-hwpx 5.0.2 → python-hwpx-automation 6.0.4 → hwpx-plugin 1.0.1`
-> (계약 `0ce938371f0b55a6`)입니다. core·automation PyPI와 plugin GitHub
-> Release·marketplace·실제 marketplace 설치까지 확인한 뒤 승격하며, 기존
+> 이 저장소의 main은 아직 공개되지 않은 6.3.1 후보 — release-approved 상태(네이티브 차트 생성
+> `add_chart`, 계약 `236f8ea855c875fe`, 130 도구)입니다. 현재 공개 트레인은
+> `python-hwpx 5.2.0 → python-hwpx-automation 6.2.1 → hwpx-plugin 1.2.0`
+> (계약 `342cf672f29cd183`, 2026-07-31 released)입니다. 공개 트레인은
+> core·automation PyPI와 plugin GitHub
+> Release·marketplace·실제 marketplace 설치까지 확인한 뒤 승격했으며, 기존
 > 5.x 설치는 별도 발행된 `hwpx-mcp-server 5.1.1`이 보호합니다. 절차와 상태
 > 머신: [릴리스 runbook](docs/release-runbook.md)
 
@@ -74,7 +75,7 @@ Gemini CLI는 `~/.gemini/settings.json`, Cursor·Windsurf는 각 에디터의 MC
       "command": "uvx",
       "args": [
         "--from",
-        "python-hwpx-automation[mcp]==6.0.4",
+        "python-hwpx-automation[mcp]==6.1.3",
         "hwpx-automation-mcp"
       ],
       "env": {

{python_hwpx_automation-6.1.3 → python_hwpx_automation-6.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx-automation"
-version = "6.1.3"
+version = "6.3.1"
 description = "Task-oriented HWPX document automation for Python, with an optional MCP adapter."
 readme = "README.md"
 authors = [{ name = "Kohkyuhyun" }]
@@ -29,7 +29,7 @@ dependencies = [
     # the bounded major here is what makes "no valid install has two declarers"
     # true rather than hopeful, and prevents the next core major from silently
     # breaking an already-published automation line.
-    "python-hwpx>=5.1.0,<6", # HWPX object model, OXML/OPC, format-native primitives
+    "python-hwpx>=5.3.0,<6", # HWPX object model, OXML/OPC, format-native primitives
 
     "pydantic>=2.11,<3",
     "cryptography>=42.0",

{python_hwpx_automation-6.1.3 → python_hwpx_automation-6.3.1}/src/hwpx_automation/handlers/content_edit.py

@@ -42,6 +42,7 @@ from ._shared import (
     _normalize_fill_mappings,
     _revision_guard,
     _save_doc_verification,
+    _with_document_state,
     _with_dry_run_verification,
     _with_save_verification,
 )
@@ -679,6 +680,81 @@ def add_page_break(
     return _with_save_verification({"success": True}, verification)
 
 
+def add_chart(
+    filename: str,
+    chart_type: str,
+    categories: list,
+    series: list,
+    title: str = None,
+    paragraph_index: int = None,
+    table_index: int = None,
+    row: int = None,
+    col: int = None,
+    treat_as_char: bool = False,
+    dry_run: bool = False,
+    expected_revision: str = None,
+) -> dict:
+    """네이티브 차트(<hp:chart>+ECMA-376 chartML part)를 삽입합니다. 렌더 검증된
+    MVP 3종(bar·line·pie)만 지원 — 밖이면 CHART_UNSUPPORTED로 typed 거부(무음
+    근사 없음). series=[{"name": str, "values": [number,...]}], values 길이는
+    categories와 일치해야 합니다. 실한컴은 chartML만으로 차트를 그립니다(OLE
+    폴백·사전렌더 이미지 불요). 배치: 기본=문서 끝 새 문단(float),
+    paragraph_index=기존 문단, tableIndex+row+col=표 셀, treat_as_char=인라인."""
+    path = resolve_path(filename)
+    guard = _revision_guard(path, expected_revision)
+    if guard is not None:
+        return guard
+    result = RUNTIME_SERVICES.ops.add_chart(
+        path,
+        chart_type=chart_type,
+        categories=categories,
+        series=series,
+        title=title,
+        paragraph_index=paragraph_index,
+        table_index=table_index,
+        row=row,
+        col=col,
+        treat_as_char=treat_as_char,
+        dry_run=dry_run,
+    )
+    return _with_document_state(result, path)
+
+
+def add_equation(
+    filename: str,
+    latex: str = None,
+    script: str = None,
+    paragraph_index: int = None,
+    table_index: int = None,
+    row: int = None,
+    col: int = None,
+    base_unit: int = 1100,
+    dry_run: bool = False,
+    expected_revision: str = None,
+) -> dict:
+    """네이티브 수식(<hp:equation>)을 삽입합니다. latex(권장) 또는 EqEdit script 중
+    하나만 지정 — LaTeX는 렌더 검증된 토큰셋만 EqEdit로 변환하고, 밖이면
+    EQUATION_LATEX_UNSUPPORTED로 거부합니다(무음 근사 없음). 산출 수식은 실한컴이
+    조판하고 기존 리더(eqedit_to_latex)가 되읽습니다(응답 readerLatex).
+    배치: 기본=문서 끝 새 문단, paragraph_index=기존 문단, tableIndex+row+col=표 셀."""
+    path = resolve_path(filename)
+    guard = _revision_guard(path, expected_revision)
+    if guard is not None:
+        return guard
+    result = RUNTIME_SERVICES.ops.add_equation(
+        path,
+        latex=latex,
+        script=script,
+        paragraph_index=paragraph_index,
+        table_index=table_index,
+        row=row,
+        col=col,
+        base_unit=base_unit,
+        dry_run=dry_run,
+    )
+    return _with_document_state(result, path)
+
+
 def insert_picture(
     filename: str,
     image_base64: str,
@@ -1060,6 +1136,8 @@ __all__ = [
     "insert_paragraph",
     "delete_paragraph",
     "add_page_break",
+    "add_equation",
+    "add_chart",
     "apply_edits",
     "undo_last_edit",
     "replace_by_anchor",

{python_hwpx_automation-6.1.3 → python_hwpx_automation-6.3.1}/src/hwpx_automation/hwpx_ops.py

@@ -517,6 +517,60 @@ class HwpxOps:
             path, text, section_index=section_index, run_style=run_style
         )
 
+    def add_chart(
+        self,
+        path: str,
+        *,
+        chart_type: str,
+        categories: list[str],
+        series: list[dict],
+        title: Optional[str] = None,
+        paragraph_index: Optional[int] = None,
+        table_index: Optional[int] = None,
+        row: Optional[int] = None,
+        col: Optional[int] = None,
+        treat_as_char: bool = False,
+        dry_run: bool = False,
+    ) -> Dict[str, Any]:
+        return self._services.content_layout.add_chart(
+            path,
+            chart_type=chart_type,
+            categories=categories,
+            series=series,
+            title=title,
+            paragraph_index=paragraph_index,
+            table_index=table_index,
+            row=row,
+            col=col,
+            treat_as_char=treat_as_char,
+            dry_run=dry_run,
+        )
+
+    def add_equation(
+        self,
+        path: str,
+        *,
+        latex: Optional[str] = None,
+        script: Optional[str] = None,
+        paragraph_index: Optional[int] = None,
+        table_index: Optional[int] = None,
+        row: Optional[int] = None,
+        col: Optional[int] = None,
+        base_unit: int = 1100,
+        dry_run: bool = False,
+    ) -> Dict[str, Any]:
+        return self._services.content_layout.add_equation(
+            path,
+            latex=latex,
+            script=script,
+            paragraph_index=paragraph_index,
+            table_index=table_index,
+            row=row,
+            col=col,
+            base_unit=base_unit,
+            dry_run=dry_run,
+        )
+
     def insert_paragraphs_bulk(
         self,
         path: str,

python_hwpx_automation-6.3.1/src/hwpx_automation/identity.json

@@ -0,0 +1,263 @@
+{
+ "schemaVersion": "python-hwpx-automation.identity/v1",
+ "product": "python-hwpx-automation",
+ "releaseMajor": 6,
+ "releaseState": {
+  "status": "release-approved",
+  "candidate": {
+   "pythonHwpx": "5.3.0",
+   "canonicalDistribution": "python-hwpx-automation",
+   "canonicalAutomation": "6.3.1",
+   "compatibilityDistribution": "hwpx-mcp-server",
+   "compatibility": "6.3.1",
+   "plugin": "1.3.0",
+   "contractHash": "236f8ea855c875fe"
+  },
+  "currentPublic": {
+   "pythonHwpx": "5.2.0",
+   "primaryDistribution": "python-hwpx-automation",
+   "primaryApplication": "6.2.1",
+   "plugin": "1.2.0",
+   "contractHash": "342cf672f29cd183"
+  },
+  "promotionGate": "Three states are mandatory: unreleased-candidate while auditing; release-approved only after separate owner approval and while currentPublic still names the previously observed coherent stack; released only in a follow-up commit after remote truth is observed for core, canonical automation, the compatibility distribution, the plugin GitHub release, the marketplace entry, and a real marketplace install. The automation tag workflow publishes only release-approved, leaves currentPublic unchanged, and hands an attached receipt to plugin publication."
+ },
+ "identifiers": [
+  {
+   "surface": "repository",
+   "value": "airmang/python-hwpx-automation",
+   "classification": "canonical"
+  },
+  {
+   "surface": "distribution",
+   "value": "python-hwpx-automation",
+   "classification": "canonical"
+  },
+  {
+   "surface": "import-namespace",
+   "value": "hwpx_automation",
+   "classification": "canonical"
+  },
+  {
+   "surface": "task-console",
+   "value": "hwpx",
+   "classification": "canonical"
+  },
+  {
+   "surface": "mcp-console",
+   "value": "hwpx-automation-mcp",
+   "classification": "canonical"
+  },
+  {
+   "surface": "fastmcp-server-info-name",
+   "value": "python-hwpx-automation",
+   "classification": "canonical"
+  },
+  {
+   "surface": "host-config-key",
+   "value": "hwpx",
+   "classification": "host-local-alias"
+  },
+  {
+   "surface": "environment-prefix",
+   "value": "HWPX_AUTOMATION_",
+   "classification": "canonical"
+  },
+  {
+   "surface": "distribution",
+   "value": "hwpx-mcp-server",
+   "classification": "compatibility"
+  },
+  {
+   "surface": "import-namespace",
+   "value": "hwpx_mcp_server",
+   "classification": "compatibility"
+  },
+  {
+   "surface": "mcp-console",
+   "value": "hwpx-mcp-server",
+   "classification": "compatibility"
+  },
+  {
+   "surface": "environment-prefix",
+   "value": "HWPX_MCP_",
+   "classification": "compatibility"
+  },
+  {
+   "surface": "capability-version-field",
+   "value": "versions.automation",
+   "classification": "canonical"
+  },
+  {
+   "surface": "capability-version-field",
+   "value": "versions.mcp",
+   "classification": "compatibility-preserved"
+  },
+  {
+   "surface": "capability-floor-field",
+   "value": "minAutomationVersion",
+   "classification": "canonical"
+  },
+  {
+   "surface": "capability-floor-field",
+   "value": "minMcpVersion",
+   "classification": "compatibility-preserved"
+  },
+  {
+   "surface": "contract-floor-constant",
+   "value": "MIN_AUTOMATION_VERSION",
+   "classification": "canonical"
+  },
+  {
+   "surface": "contract-floor-constant",
+   "value": "MIN_MCP_VERSION",
+   "classification": "compatibility-preserved"
+  },
+  {
+   "surface": "protocol-error-schema",
+   "value": "hwpx.mcp-error/v1",
+   "classification": "compatibility-preserved"
+  },
+  {
+   "surface": "frozen-receipt-schema",
+   "value": "hwpx-mcp.authoring-runtime-owner/v1",
+   "classification": "compatibility-preserved"
+  },
+  {
+   "surface": "frozen-receipt-schema",
+   "value": "hwpx-mcp.compliance-quality-utilities-owner/v1",
+   "classification": "compatibility-preserved"
+  },
+  {
+   "surface": "frozen-receipt-schema",
+   "value": "hwpx-mcp.document-operations-owner/v1",
+   "classification": "compatibility-preserved"
+  },
+  {
+   "surface": "frozen-receipt-schema",
+   "value": "hwpx-mcp.evalplan-runtime-owner/v1",
+   "classification": "compatibility-preserved"
+  },
+  {
+   "surface": "frozen-receipt-schema",
+   "value": "hwpx-mcp.exam-runtime-owner/v1",
+   "classification": "compatibility-preserved"
+  },
+  {
+   "surface": "frozen-receipt-schema",
+   "value": "hwpx-mcp.form-fill-runtime-owner/v1",
+   "classification": "compatibility-preserved"
+  },
+  {
+   "surface": "frozen-receipt-schema",
+   "value": "hwpx-mcp.form-fill-runtime-parity/v1",
+   "classification": "compatibility-preserved"
+  },
+  {
+   "surface": "frozen-receipt-schema",
+   "value": "hwpx-mcp.visual-runtime-owner/v1",
+   "classification": "compatibility-preserved"
+  },
+  {
+   "surface": "frozen-parity-receipt-field",
+   "value": "mcpRuntimeMembers",
+   "classification": "compatibility-preserved"
+  },
+  {
+   "surface": "workflow-state-environment",
+   "value": "HWPX_AUTOMATION_WORKFLOW_STORE",
+   "classification": "canonical"
+  },
+  {
+   "surface": "workflow-state-environment",
+   "value": "HWPX_WORKFLOW_STORE",
+   "classification": "compatibility-preserved"
+  },
+  {
+   "surface": "workflow-state-path",
+   "value": "${XDG_STATE_HOME:-~/.local/state}/hwpx-mcp-server/workflows.sqlite3",
+   "classification": "compatibility-preserved"
+  },
+  {
+   "surface": "render-queue-principal",
+   "value": "hwpx-mcp-server",
+   "classification": "compatibility-preserved"
+  },
+  {
+   "surface": "render-integration-environment",
+   "value": "HWPX_RENDER_QUEUE_ROOT",
+   "classification": "integration-preserved"
+  },
+  {
+   "surface": "render-integration-environment",
+   "value": "HWPX_RENDER_QUEUE_URL",
+   "classification": "integration-preserved"
+  },
+  {
+   "surface": "render-integration-environment",
+   "value": "HWPX_RENDER_QUEUE_SECRET",
+   "classification": "integration-preserved"
+  },
+  {
+   "surface": "render-integration-environment",
+   "value": "HWPX_RENDER_TRANSPORT_AUTH",
+   "classification": "integration-preserved"
+  },
+  {
+   "surface": "render-integration-environment",
+   "value": "HWPX_RENDER_CA_FILE",
+   "classification": "integration-preserved"
+  },
+  {
+   "surface": "render-integration-environment",
+   "value": "HWPX_RENDER_CLIENT_CERT_FILE",
+   "classification": "integration-preserved"
+  },
+  {
+   "surface": "render-integration-environment",
+   "value": "HWPX_RENDER_CLIENT_KEY_FILE",
+   "classification": "integration-preserved"
+  },
+  {
+   "surface": "workflow-security-environment",
+   "value": "HWPX_WORKFLOW_ENCRYPTION_KEY",
+   "classification": "capability-preserved"
+  },
+  {
+   "surface": "oracle-capability-environment",
+   "value": "HWPX_ORACLE_STRUCTURAL_ONLY",
+   "classification": "capability-preserved"
+  },
+  {
+   "surface": "oracle-capability-environment",
+   "value": "HWPX_ORACLE_BUDGET_SECONDS",
+   "classification": "capability-preserved"
+  },
+  {
+   "surface": "plugin-integration-environment",
+   "value": "HWPX_SKILL_VERSION",
+   "classification": "integration-preserved"
+  },
+  {
+   "surface": "plugin-integration-environment",
+   "value": "HWPX_PLUGIN_ROOT",
+   "classification": "integration-preserved"
+  }
+ ],
+ "compatibilityPolicy": {
+  "supportedThroughMajor": 6,
+  "removalNotBeforeMajor": 7,
+  "minimumPublicNoticeDays": 90,
+  "requiresObservedUsageWindow": true,
+  "requiresSeparateOwnerApproval": true,
+  "statePathMigrationInMajor6": false
+ },
+ "notes": {
+  "hostConfigKey": "The key is a host-local alias, not the MCP protocol identity.",
+  "environmentPrecedence": "HWPX_AUTOMATION_* wins; HWPX_MCP_* remains a 6.x fallback.",
+  "preservedWireIdentifiers": "The public hwpx.mcp-error/v1 schema, versions.mcp/minMcpVersion/MIN_MCP_VERSION aliases, frozen hwpx-mcp.* architecture receipt IDs, and mcpRuntimeMembers parity-receipt field remain exact in 6.x. They are compatibility identifiers, not statements that MCP owns the automation product.",
+  "preservedIntegrationEnvironment": "Product-neutral HWPX_RENDER_*, HWPX_WORKFLOW_ENCRYPTION_KEY, HWPX_ORACLE_*, HWPX_SKILL_VERSION, and HWPX_PLUGIN_ROOT names do not encode the former MCP product identity. They remain unchanged and are not aliases in the HWPX_AUTOMATION_ transition.",
+  "statePath": "HWPX_AUTOMATION_WORKFLOW_STORE wins over the prior HWPX_WORKFLOW_STORE override; the existing hwpx-mcp-server on-disk default remains in 6.x to avoid silent workflow loss.",
+  "renderQueuePrincipal": "The signed queue principal remains hwpx-mcp-server in 6.x so queued work and worker authorization do not split during the rename."
+ }
+}

python_hwpx_automation-6.3.1/src/hwpx_automation/office/charting/__init__.py

@@ -0,0 +1,162 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Deterministic data → ECMA-376 chartML generator (MVP: bar, line, pie).
+
+The grammar mirrors the render-verified probes in
+specs/055-chart-authoring/evidence/p0 (workspace): a ``c:chartSpace``
+skeleton, per-series ``c:ser`` with string/number caches, and the
+type-specific plot element (``c:barChart`` / ``c:lineChart`` + axis pair /
+``c:pieChart``). Anything outside the verified set is refused with a typed
+error — no silent approximation. Real Hancom draws the output from the
+chartML alone (no OLE fallback, no pre-rendered image).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Sequence
+from xml.sax.saxutils import escape
+
+CHART_TYPES = ("bar", "line", "pie")
+
+_CAT_AX_ID = "111111111"
+_VAL_AX_ID = "222222222"
+
+_HEAD = (
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>'
+    '<c:chartSpace xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"'
+    ' xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main"'
+    ' xmlns:c="http://schemas.openxmlformats.org/drawingml/2006/chart">'
+    '<c:date1904 val="0"/><c:roundedCorners val="0"/><c:chart>'
+)
+
+
+class UnsupportedChartError(ValueError):
+    """Raised for chart types or shapes outside the render-verified MVP set."""
+
+
+@dataclass(frozen=True)
+class ChartSeries:
+    """One data series: a display name and one value per category."""
+
+    name: str
+    values: tuple[float, ...]
+
+
+def _series(index: int, name: str, categories: Sequence[str],
+            values: Sequence[float], extra: str = "") -> str:
+    cats = "".join(
+        f'<c:pt idx="{i}"><c:v>{escape(str(c))}</c:v></c:pt>'
+        for i, c in enumerate(categories)
+    )
+    vals = "".join(
+        f'<c:pt idx="{i}"><c:v>{v:g}</c:v></c:pt>' for i, v in enumerate(values)
+    )
+    column = chr(ord("B") + index)
+    return (
+        f'<c:ser><c:idx val="{index}"/><c:order val="{index}"/>'
+        f"<c:tx><c:strRef><c:f>Sheet1!${column}$1</c:f>"
+        f'<c:strCache><c:ptCount val="1"/><c:pt idx="0"><c:v>{escape(name)}</c:v></c:pt>'
+        f"</c:strCache></c:strRef></c:tx>{extra}"
+        f"<c:cat><c:strRef><c:f>Sheet1!$A$2:$A${len(categories) + 1}</c:f>"
+        f'<c:strCache><c:ptCount val="{len(categories)}"/>{cats}</c:strCache></c:strRef></c:cat>'
+        f"<c:val><c:numRef><c:f>Sheet1!${column}$2:${column}${len(values) + 1}</c:f>"
+        f"<c:numCache><c:formatCode>General</c:formatCode>"
+        f'<c:ptCount val="{len(values)}"/>{vals}</c:numCache></c:numRef></c:val></c:ser>'
+    )
+
+
+def _axes() -> str:
+    return (
+        f'<c:catAx><c:axId val="{_CAT_AX_ID}"/>'
+        '<c:scaling><c:orientation val="minMax"/></c:scaling><c:delete val="0"/>'
+        f'<c:axPos val="b"/><c:crossAx val="{_VAL_AX_ID}"/></c:catAx>'
+        f'<c:valAx><c:axId val="{_VAL_AX_ID}"/>'
+        '<c:scaling><c:orientation val="minMax"/></c:scaling><c:delete val="0"/>'
+        f'<c:axPos val="l"/><c:crossAx val="{_CAT_AX_ID}"/></c:valAx>'
+    )
+
+
+def build_chart_ml(
+    chart_type: str,
+    categories: Sequence[str],
+    series: Sequence[ChartSeries],
+    *,
+    title: str | None = None,
+) -> str:
+    """Build chartML for one of the render-verified MVP chart types.
+
+    Raises:
+        UnsupportedChartError: unknown chart type, empty/mismatched data, or
+            a shape outside the verified set (e.g. multi-series pie).
+    """
+
+    if chart_type not in CHART_TYPES:
+        raise UnsupportedChartError(
+            f"unsupported chart type {chart_type!r}; render-verified types: "
+            + ", ".join(CHART_TYPES)
+        )
+    if not categories:
+        raise UnsupportedChartError("categories must be non-empty")
+    if not series:
+        raise UnsupportedChartError("series must be non-empty")
+    if chart_type == "pie" and len(series) != 1:
+        raise UnsupportedChartError("a pie chart takes exactly one series")
+    if len(series) > 25:
+        raise UnsupportedChartError("at most 25 series are supported")
+    for item in series:
+        if not item.name.strip():
+            raise UnsupportedChartError("every series needs a non-empty name")
+        if len(item.values) != len(categories):
+            raise UnsupportedChartError(
+                f"series {item.name!r} has {len(item.values)} values for "
+                f"{len(categories)} categories"
+            )
+
+    parts: list[str] = [_HEAD]
+    if title is not None and title.strip():
+        parts.append(
+            "<c:title><c:tx><c:rich><a:bodyPr/><a:p><a:r><a:t>"
+            + escape(title)
+            + "</a:t></a:r></a:p></c:rich></c:tx><c:overlay val=\"0\"/></c:title>"
+            '<c:autoTitleDeleted val="0"/>'
+        )
+    parts.append("<c:plotArea><c:layout/>")
+
+    if chart_type == "bar":
+        parts.append('<c:barChart><c:barDir val="col"/><c:grouping val="clustered"/><c:varyColors val="0"/>')
+        for index, item in enumerate(series):
+            parts.append(_series(index, item.name, categories, item.values))
+        parts.append(
+            f'<c:axId val="{_CAT_AX_ID}"/><c:axId val="{_VAL_AX_ID}"/></c:barChart>'
+        )
+        parts.append(_axes())
+    elif chart_type == "line":
+        parts.append('<c:lineChart><c:grouping val="standard"/><c:varyColors val="0"/>')
+        for index, item in enumerate(series):
+            parts.append(
+                _series(
+                    index, item.name, categories, item.values,
+                    '<c:marker><c:symbol val="circle"/><c:size val="5"/></c:marker>',
+                )
+            )
+        parts.append(
+            '<c:marker val="1"/>'
+            f'<c:axId val="{_CAT_AX_ID}"/><c:axId val="{_VAL_AX_ID}"/></c:lineChart>'
+        )
+        parts.append(_axes())
+    else:  # pie
+        parts.append('<c:pieChart><c:varyColors val="1"/>')
+        parts.append(_series(0, series[0].name, categories, series[0].values))
+        parts.append('<c:firstSliceAng val="0"/></c:pieChart>')
+
+    parts.append("</c:plotArea>")
+    parts.append('<c:plotVisOnly val="1"/></c:chart></c:chartSpace>')
+    return "".join(parts)
+
+
+__all__ = [
+    "CHART_TYPES",
+    "ChartSeries",
+    "UnsupportedChartError",
+    "build_chart_ml",
+]