docspecbridge 0.2.0b1__tar.gz

docspecbridge-0.2.0b1/.github/workflows/publish-pypi.yml

@@ -0,0 +1,85 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build and validate distributions
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Install Python 3.14
+        run: uv python install 3.14
+
+      - name: Check tag matches package version
+        shell: bash
+        run: |
+          VERSION=$(uv run --python 3.14 --no-project python -c 'import tomllib; print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          echo "pyproject.toml version: $VERSION"
+          echo "Git tag version:        $TAG_VERSION"
+          test "$VERSION" = "$TAG_VERSION"
+
+      - name: Build distributions
+        run: uv build --no-sources
+
+      - name: Validate distributions
+        run: uvx twine check dist/*
+
+      - name: Smoke test built wheel
+        shell: bash
+        run: |
+          WHEEL=$(find dist -maxdepth 1 -type f -name '*.whl' -print -quit)
+          test -n "$WHEEL"
+          echo "Testing wheel: $WHEEL"
+          uv run --python 3.14 --isolated --no-project --with "$WHEEL" docspecbridge doctor
+
+      - name: Upload validated distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: pypi-dist
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+
+  publish:
+    name: Publish validated distributions to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+
+    steps:
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: false
+
+      - name: Download validated distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: pypi-dist
+          path: dist/
+
+      - name: Publish to PyPI
+        run: uvx twine upload dist/*
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}

docspecbridge-0.2.0b1/.gitignore

@@ -0,0 +1,47 @@
+# Python virtual environments
+.venv/
+venv/
+env/
+
+# Python caches / tooling
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+# Build / packaging artifacts
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Local DocSpecBridge configuration / secrets
+docspecbridge.yaml
+docspecbridge.yml
+.env
+.env.*
+!.env.example
+
+# Local source documents and generated corpus
+# Keep only the harmless placeholder README in input/ if present.
+input/*
+!input/README.txt
+output/
+
+# Logs / temporary files
+*.log
+*.tmp
+*.bak
+~$*
+
+# IDE / OS noise
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+Desktop.ini

docspecbridge-0.2.0b1/.python-version

@@ -0,0 +1 @@
+3.14

docspecbridge-0.2.0b1/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.5
+Name: docspecbridge
+Version: 0.2.0b1
+Summary: Document ETL bridge: Office/PDF -> Markdown + images -> Confluence/RAG-ready packages
+Author: DocSpecBridge contributors
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: markdown-to-confluence==0.6.3
+Requires-Dist: pillow<13,>=11.3
+Requires-Dist: pymupdf<2,>=1.26
+Requires-Dist: python-pptx<2,>=1.0.2
+Requires-Dist: pyyaml<7,>=6.0.2
+Requires-Dist: rich<15,>=14
+Requires-Dist: typer<1,>=0.16
+Requires-Dist: xberg==1.0.14
+Description-Content-Type: text/markdown
+
+# DocSpecBridge 0.2.0b1 (Beta)
+
+DocSpecBridge is a Python document ETL bridge:
+
+```text
+DOCX / PDF / PPTX
+        |
+        v
+      Xberg
+        |
+        +--> normalized source assets + source geometry
+        |
+        +--> publication Markdown --> md2conf --> Confluence Cloud
+        |
+        +--> RAG Markdown + chunks.jsonl
+```
+
+The 0.2.0b1 release separates **publication fidelity** from **RAG efficiency**. Layout metadata is never injected into RAG text; it is stored in JSON and used to build publication-specific image variants.
+
+## 1. Installation with uv
+
+Python 3.14.7 is recommended for the current POC.
+
+```powershell
+cd C:\DEV\docspecbridge
+uv venv --python 3.14.7
+.\.venv\Scripts\Activate.ps1
+uv sync
+uv run docspecbridge doctor
+```
+
+`uv.lock` should be committed once generated. `.venv/` must stay in `.gitignore`.
+
+## 2. First extraction
+
+Interactive:
+
+```powershell
+uv run docspecbridge
+```
+
+CLI:
+
+```powershell
+uv run docspecbridge extract `
+  --source "C:\MD\input" `
+  --dest "C:\MD\output"
+```
+
+A package is created per source and the extension is part of the package name to avoid collisions:
+
+```text
+output/
+├── specification__docx/
+│   ├── specification.docx
+│   ├── specification.md
+│   ├── specification.rag.md
+│   ├── specification.raw.md
+│   ├── images/
+│   ├── publication_images/
+│   ├── manifest.json
+│   ├── document.json
+│   ├── rag.json
+│   └── chunks.jsonl
+└── specification__pdf/
+    └── ...
+```
+
+### Files
+
+- `*.md`: publication/human Markdown. Images can point to display-sized raster derivatives.
+- `*.rag.md`: lean Markdown for RAG. No x/y/width/height metadata is written in the text.
+- `*.raw.md`: raw Xberg Markdown for diagnostics/comparison.
+- `images/`: canonical extracted images, kept at the extraction quality for RAG/multimodal use.
+- `publication_images/`: display-size derivatives used by publication Markdown when source geometry is known.
+- `manifest.json`: provenance, assets, geometry, fidelity warnings, output paths.
+- `document.json`: structured technical metadata without binary payloads.
+- `chunks.jsonl`: heading-aware RAG chunks.
+- `rag.json`: portable descriptor for a future vector/RAG publisher.
+
+## 3. Image size and geometry
+
+DocSpecBridge 0.2.0b1 treats image display geometry as a cross-format concern:
+
+- **PPTX**: picture shape `left/top/width/height` through `python-pptx`.
+- **DOCX**: DrawingML/VML image extents from OOXML, including headers/footers where available.
+- **PDF**: image rectangles through PyMuPDF.
+
+The source geometry is stored in JSON, not in RAG Markdown.
+
+For publication, DocSpecBridge can create a raster derivative close to the source display size. This prevents small PowerPoint icons from becoming giant images in Markdown/Confluence while keeping the original high-resolution image in `images/` for RAG.
+
+This is still **best effort**. The same binary image can be reused at different sizes in a source; DocSpecBridge maps successive Markdown occurrences to successive source display occurrences where possible.
+
+## 4. Vector content
+
+DOCX/PPTX OOXML connectors, grouped shapes, charts, SmartArt/diagram markers and VML shapes are detected and reported in `manifest.json`.
+
+PDF vector drawing operations are counted through PyMuPDF.
+
+0.2.0b1 does **not** yet rasterize arbitrary vector groups automatically. When vector graphics are detected, the fidelity status is marked `partial` and a warning is emitted. This is the next fallback to implement after qualification on real documents.
+
+## 5. Publication profile vs RAG profile
+
+`docspecbridge.yaml` contains two independent profiles.
+
+```yaml
+profiles:
+  publication:
+    enabled: true
+    preserve_image_display_size: true
+
+  rag:
+    enabled: true
+    keep_image_references: true
+    include_header_images: false
+    include_footer_images: false
+    chunking:
+      enabled: true
+      max_characters: 1600
+      overlap: 150
+```
+
+The RAG profile is intentionally conservative: no rewriting/paraphrasing and no aggressive token reduction. Headings, lists, tables, constraints and image references are kept. Repetitive presentation artifacts can be excluded while the original information remains available in the source, raw Markdown and JSON metadata.
+
+## 6. YAML configuration menu
+
+0.1.x could **read** a YAML file but had no editor. 0.2.0b1 adds one.
+
+```powershell
+uv run docspecbridge config
+```
+
+or in the main menu:
+
+```text
+[5] Configuration YAML
+```
+
+The menu can edit:
+
+- source/destination/extensions;
+- recursive extraction;
+- publication and RAG profile switches;
+- chunk sizes;
+- multiple Confluence Cloud instances;
+- the default Confluence instance.
+
+No PAT/token value is stored in YAML; only the environment variable name is stored.
+
+## 7. Multiple Confluence Cloud instances
+
+0.2.0b1 targets **Confluence Cloud only** and uses REST API v2.
+
+Example:
+
+```yaml
+confluence:
+  default_instance: "production"
+  instances:
+    production:
+      domain: "company.atlassian.net"
+      user_name: "user@example.com"
+      token_env: "ATLASSIAN_API_TOKEN"
+      default_space: "DOC"
+      root_page: ""
+
+    sandbox:
+      domain: "company-sandbox.atlassian.net"
+      user_name: "user@example.com"
+      token_env: "ATLASSIAN_SANDBOX_API_TOKEN"
+      default_space: "TEST"
+      root_page: ""
+```
+
+Then:
+
+```powershell
+$env:ATLASSIAN_API_TOKEN="..."
+$env:ATLASSIAN_SANDBOX_API_TOKEN="..."
+
+uv run docspecbridge spaces --instance production
+uv run docspecbridge spaces --instance sandbox
+```
+
+Publication:
+
+```powershell
+uv run docspecbridge publish `
+  --instance production `
+  --source ".\output\specification__docx" `
+  --space DOC `
+  --parent 123456789
+```
+
+The interactive publication menu first asks for the configured instance, then loads the spaces visible with that instance/token.
+
+DocSpecBridge publishes the **publication Markdown**, never the RAG Markdown. Local publication images are uploaded by `markdown-to-confluence` as Confluence page attachments and displayed inline.
+
+## 8. Configuration file
+
+Copy the example:
+
+```powershell
+Copy-Item config.example.yaml docspecbridge.yaml
+```
+
+`docspecbridge.yaml` is intentionally ignored by Git because it contains local paths and account identifiers. `config.example.yaml` belongs in Git.
+
+Legacy 0.1.x YAML with a single `confluence:` endpoint and a top-level `rag:` section is migrated in memory when loaded.
+
+## 9. Useful commands
+
+```powershell
+uv run docspecbridge doctor
+uv run docspecbridge config
+uv run docspecbridge extract --source .\input --dest .\output
+uv run docspecbridge spaces --instance production
+uv run docspecbridge publish --instance production --source .\output\mydoc__docx --space DOC
+```
+
+## 10. Mermaid
+
+The configuration keeps a `render_mermaid` switch because `markdown-to-confluence` already has Mermaid support. DocSpecBridge 0.2.0b1 does not yet attempt to transform legacy diagrams/images into Mermaid. That remains an enrichment stage for a later version.

docspecbridge-0.2.0b1/README.md

@@ -0,0 +1,224 @@
+# DocSpecBridge 0.2.0b1 (Beta)
+
+DocSpecBridge is a Python document ETL bridge:
+
+```text
+DOCX / PDF / PPTX
+        |
+        v
+      Xberg
+        |
+        +--> normalized source assets + source geometry
+        |
+        +--> publication Markdown --> md2conf --> Confluence Cloud
+        |
+        +--> RAG Markdown + chunks.jsonl
+```
+
+The 0.2.0b1 release separates **publication fidelity** from **RAG efficiency**. Layout metadata is never injected into RAG text; it is stored in JSON and used to build publication-specific image variants.
+
+## 1. Installation with uv
+
+Python 3.14.7 is recommended for the current POC.
+
+```powershell
+cd C:\DEV\docspecbridge
+uv venv --python 3.14.7
+.\.venv\Scripts\Activate.ps1
+uv sync
+uv run docspecbridge doctor
+```
+
+`uv.lock` should be committed once generated. `.venv/` must stay in `.gitignore`.
+
+## 2. First extraction
+
+Interactive:
+
+```powershell
+uv run docspecbridge
+```
+
+CLI:
+
+```powershell
+uv run docspecbridge extract `
+  --source "C:\MD\input" `
+  --dest "C:\MD\output"
+```
+
+A package is created per source and the extension is part of the package name to avoid collisions:
+
+```text
+output/
+├── specification__docx/
+│   ├── specification.docx
+│   ├── specification.md
+│   ├── specification.rag.md
+│   ├── specification.raw.md
+│   ├── images/
+│   ├── publication_images/
+│   ├── manifest.json
+│   ├── document.json
+│   ├── rag.json
+│   └── chunks.jsonl
+└── specification__pdf/
+    └── ...
+```
+
+### Files
+
+- `*.md`: publication/human Markdown. Images can point to display-sized raster derivatives.
+- `*.rag.md`: lean Markdown for RAG. No x/y/width/height metadata is written in the text.
+- `*.raw.md`: raw Xberg Markdown for diagnostics/comparison.
+- `images/`: canonical extracted images, kept at the extraction quality for RAG/multimodal use.
+- `publication_images/`: display-size derivatives used by publication Markdown when source geometry is known.
+- `manifest.json`: provenance, assets, geometry, fidelity warnings, output paths.
+- `document.json`: structured technical metadata without binary payloads.
+- `chunks.jsonl`: heading-aware RAG chunks.
+- `rag.json`: portable descriptor for a future vector/RAG publisher.
+
+## 3. Image size and geometry
+
+DocSpecBridge 0.2.0b1 treats image display geometry as a cross-format concern:
+
+- **PPTX**: picture shape `left/top/width/height` through `python-pptx`.
+- **DOCX**: DrawingML/VML image extents from OOXML, including headers/footers where available.
+- **PDF**: image rectangles through PyMuPDF.
+
+The source geometry is stored in JSON, not in RAG Markdown.
+
+For publication, DocSpecBridge can create a raster derivative close to the source display size. This prevents small PowerPoint icons from becoming giant images in Markdown/Confluence while keeping the original high-resolution image in `images/` for RAG.
+
+This is still **best effort**. The same binary image can be reused at different sizes in a source; DocSpecBridge maps successive Markdown occurrences to successive source display occurrences where possible.
+
+## 4. Vector content
+
+DOCX/PPTX OOXML connectors, grouped shapes, charts, SmartArt/diagram markers and VML shapes are detected and reported in `manifest.json`.
+
+PDF vector drawing operations are counted through PyMuPDF.
+
+0.2.0b1 does **not** yet rasterize arbitrary vector groups automatically. When vector graphics are detected, the fidelity status is marked `partial` and a warning is emitted. This is the next fallback to implement after qualification on real documents.
+
+## 5. Publication profile vs RAG profile
+
+`docspecbridge.yaml` contains two independent profiles.
+
+```yaml
+profiles:
+  publication:
+    enabled: true
+    preserve_image_display_size: true
+
+  rag:
+    enabled: true
+    keep_image_references: true
+    include_header_images: false
+    include_footer_images: false
+    chunking:
+      enabled: true
+      max_characters: 1600
+      overlap: 150
+```
+
+The RAG profile is intentionally conservative: no rewriting/paraphrasing and no aggressive token reduction. Headings, lists, tables, constraints and image references are kept. Repetitive presentation artifacts can be excluded while the original information remains available in the source, raw Markdown and JSON metadata.
+
+## 6. YAML configuration menu
+
+0.1.x could **read** a YAML file but had no editor. 0.2.0b1 adds one.
+
+```powershell
+uv run docspecbridge config
+```
+
+or in the main menu:
+
+```text
+[5] Configuration YAML
+```
+
+The menu can edit:
+
+- source/destination/extensions;
+- recursive extraction;
+- publication and RAG profile switches;
+- chunk sizes;
+- multiple Confluence Cloud instances;
+- the default Confluence instance.
+
+No PAT/token value is stored in YAML; only the environment variable name is stored.
+
+## 7. Multiple Confluence Cloud instances
+
+0.2.0b1 targets **Confluence Cloud only** and uses REST API v2.
+
+Example:
+
+```yaml
+confluence:
+  default_instance: "production"
+  instances:
+    production:
+      domain: "company.atlassian.net"
+      user_name: "user@example.com"
+      token_env: "ATLASSIAN_API_TOKEN"
+      default_space: "DOC"
+      root_page: ""
+
+    sandbox:
+      domain: "company-sandbox.atlassian.net"
+      user_name: "user@example.com"
+      token_env: "ATLASSIAN_SANDBOX_API_TOKEN"
+      default_space: "TEST"
+      root_page: ""
+```
+
+Then:
+
+```powershell
+$env:ATLASSIAN_API_TOKEN="..."
+$env:ATLASSIAN_SANDBOX_API_TOKEN="..."
+
+uv run docspecbridge spaces --instance production
+uv run docspecbridge spaces --instance sandbox
+```
+
+Publication:
+
+```powershell
+uv run docspecbridge publish `
+  --instance production `
+  --source ".\output\specification__docx" `
+  --space DOC `
+  --parent 123456789
+```
+
+The interactive publication menu first asks for the configured instance, then loads the spaces visible with that instance/token.
+
+DocSpecBridge publishes the **publication Markdown**, never the RAG Markdown. Local publication images are uploaded by `markdown-to-confluence` as Confluence page attachments and displayed inline.
+
+## 8. Configuration file
+
+Copy the example:
+
+```powershell
+Copy-Item config.example.yaml docspecbridge.yaml
+```
+
+`docspecbridge.yaml` is intentionally ignored by Git because it contains local paths and account identifiers. `config.example.yaml` belongs in Git.
+
+Legacy 0.1.x YAML with a single `confluence:` endpoint and a top-level `rag:` section is migrated in memory when loaded.
+
+## 9. Useful commands
+
+```powershell
+uv run docspecbridge doctor
+uv run docspecbridge config
+uv run docspecbridge extract --source .\input --dest .\output
+uv run docspecbridge spaces --instance production
+uv run docspecbridge publish --instance production --source .\output\mydoc__docx --space DOC
+```
+
+## 10. Mermaid
+
+The configuration keeps a `render_mermaid` switch because `markdown-to-confluence` already has Mermaid support. DocSpecBridge 0.2.0b1 does not yet attempt to transform legacy diagrams/images into Mermaid. That remains an enrichment stage for a later version.