Proposal: get_paragraph_metadata — expose a paragraph's style model (named style + direct overrides)

[Augusto-Zolet]

Proposal: get_paragraph_metadata — expose a paragraph's style model (named style + direct overrides)

I've already implemented and tested this on a branch (UNO regression tests pass, gate clean). If you're happy with the approach, I'll open the PR.

What

A read-only tool, get_paragraph_metadata, returning a paragraph's named style plus, per run, the Char* properties that differ from that
style's default (a heuristic for hand-set overrides):

{ "para_style_name": "Caption",
  "runs": [{ "text": "Figure 1", "char_properties_differing_from_style": { "CharColor": 16711680, "CharPosture": "ITALIC" } }] }

Where

• plugin/writer/content.py — the tool (tier="core", read-only).
• plugin/writer/format.py — shared helper char_overrides_for_portion, extracted from apply_paragraph_style_preserving_direct_char so the write path
  and this read tool share one detection (no duplication).
• tests/writer/test_get_paragraph_metadata_uno.py, docs/llm-styles.md.

Problem it solves

get_document_content flattens to HTML with computed inline styles — it hides the named style and the origin of each property. The agent sees
font-size:10pt; italic but can't tell it's the Caption style, nor whether the italic is hand-set. So it can't replicate formatting faithfully.

Why it fits "the agent should use named styles"

It's what enables that: today the agent is blind to styles (HTML hides them), which pushes it to copy raw direct formatting. This surfaces the style name first (overrides as the residual), so the agent can read "it's Caption" and reapply that style via apply_style. It's the read-side complement to the styles-first approach.

[KeithCu]

Hello! Great to see your new idea! You found a significant problem and I appreciate your suggestion, and it's a good one to talk about.

I thought about it for a bit and think it's cleaner and simpler to return good data to the LLMs, including the styles and stripping out the properties already set by the style. I'd do it by hand if we have to, but I discovered there's a far simpler way, we can get LO to do the work for us! Check out this document, strategy 1.

https://github.com/KeithCu/writeragent/blob/master/docs/html_style_model_plan.md

What do you think about it? If you like it, do you want to implement it and send me the PR?

Regards,

-Keith

[Augusto-Zolet]

I had thought about doing something like this, but I didn't know LibreOffice could give us the style model natively like that.

I explored it a bit with Claude and ran a quick probe with the XHTML Writer File filter to check your premise. It mostly holds: named paragraph styles come out as classes (paragraph-Caption, paragraph-Heading_20_1) and direct char overrides as synthetic classes (.text-T1 { color:#ff0000 }).

One thing I ran into: a paragraph in the default Standard style came out as a synthetic autostyle class paragraph-P1, not paragraph-Standard — so the class name doesn't always carry the real named style. And there's a related subtlety: the same style shows up under different names depending on where you look —

• model / getPropertyValue("ParaStyleName") → Heading 1 — the real UNO name, and exactly what setPropertyValue("ParaStyleName", ...) expects on the write path;
• XHTML class → Heading_20_1 — the space is URL-escaped;
• autostyle → P1 — synthetic, not the real style at all.

For a clean round-trip, data-lo-style has to carry the UNO name (Heading 1), since that's what we feed back to setPropertyValue when applying the style.

So Claude suggested a light hybrid: use the XHTML for the body + overrides, but read the real ParaStyleName per paragraph from the model to emit data-lo-style (walking the body blocks and the model paragraphs in the same order). That turns this:

<p class="paragraph-P1">normal <span class="text-T1">RED</span> end</p>

into this:

<p data-lo-style="Standard">normal <span style="color:#ff0000">RED</span> end</p>

The nice part: reading the name from the model both sidesteps the P1 autostyle and avoids decoding the _20_ escaping (Heading_20_1 → Heading 1) — read and write end up speaking the exact same UNO name. (One thing I'll test: on a localized LibreOffice, ParaStyleName might come back translated; the round-trip stays consistent within the same instance, but worth a check.)

I'll implement it that way and send you the PR (read path + data-lo-style first, then the write path). Sound good?

[KeithCu]

That's a great question, but that solution adds complexity I'm trying to avoid. We should be able to do a simple string cleanup process to fix all that.

I've updated the document. Check out the new version. Let me know if you run into issues or questions with that design!

[Augusto-Zolet]

Hey! I'm a bit stuck here 😅

I implemented it the way you asked: two parts work well (with a couple of workarounds) and one hit a real wall I'd like your call on.

What works

• Read of a normal document: each block gets data-lo-style="Heading1" / "Caption" / "Textbody" (decoded from _20_, then spaces
  stripped), char overrides inlined as style="...", no paragraph-*/text-* leaks.
• Write: apply_document_content resolves the compact token back to the real ParaStyleName and applies it.
  and in get_document_tree.
• Edge cases handled string-side: token collisions (two styles compacting to the same token are omitted on read and fail safe to Standard on write — never silently wrong); <div> treated as a transparent container so a wrapper doesn't desync the positional style application.

The wall: write→read isn't idempotent

Reading a clean doc is fine, but after a write, re-reading usually drops the token. Here's the root cause, from my investigation with Claude:

The HTML (StarWriter) import stamps redundant DIRECT paragraph-level Char* properties (CharBackColor, CharUnderline, CharColor, the *ComplexColor ones — all equal to the style default but flagged DIRECT_VALUE). That's enough for the XHTML exporter to emit the paragraph as a synthetic autostyle:

<p class="paragraph-P1">just a caption</p>
.paragraph-P1{ ...; background-color:transparent; text-decoration:none ! important; }
.paragraph-Standard{ ... }

The paragraph is Caption in the model, but there's no .paragraph-Caption rule in that export to fingerprint against, so the string read can't recover the name and omits the token. The same can happen with paragraphs represented as XHTML autostyles — especially after the StarWriter import, or with paragraph-level direct formatting. (A native doc with a Caption paragraph + a directly-bolded word still exported .paragraph-Caption fine, so character-level overrides alone don't trigger it.)

Important: this dirt is not from the new code — it's LO's pre-existing HTML import (every write path produces it; it just never mattered before, since nothing read style names back). I tried scrubbing it after import (resetting Char* to default at portion and paragraph level) — it did not change the autostyle export; it's structural. So I reverted those attempts and left
apply_paragraph_style_preserving_direct_char untouched.

One possible solution could be to read style names from the flat ODF export instead of XHTML. I checked: .fodt keeps the parent link XHTML flattens away — <style:style style:name="P1" style:family="paragraph" style:parent-style-name="Caption"> / <text:p text:style-name="P1"> — so P1 → Caption is recoverable by pure string parsing.

Can you help me decide what's the best thing to do?

[KeithCu]

That is an interesting problem. I think your solution should work fine! Using two filters isn't ideal, but it's sort of necessary unless we an find a better solution. But in most cases, that will be simple and fast enough. Want to implement that and send the PR?

[Augusto-Zolet]

Done! PR created. I'm going to sleep now. Tomorrow I'll be back with more ideias

[KeithCu]

okay this PR is in, I'll close this discussion.