docs(custom-plugins): retrieve TOKEN USAGE for Image Processing with Custom PictureDescriptionApiModel

[FrigaZzz]

Issues resolved by this Pull Request:
Resolves #2402
Resolves #2271

Description:
This PR adds guidance and a working example for creating custom Docling plugins, helping users understand how to extend Docling’s functionality.

Key changes include:

Documentation additions:

• Step-by-step guide for creating, registering, and integrating custom plugins in Docling.

Example plugin implementation:

• Full example plugin for API-backed picture description.
• Demonstrates token usage tracking (addresses the common use case from Get the total tokens used in the image description #2271).
• Shows proper plugin structure, registration, and integration with Docling pipelines.
• Includes associated data models, utility functions, and pipeline options.

This equips users with a clear reference implementation to extend Docling without modifying the core code.

Checklist:

• Documentation updated.
• Examples added.

[github-actions]

✅ DCO Check Passed

Thanks @FrigaZzz, all your commits are properly signed off. 🎉

[dosubot]

Related Documentation

Checked 2 published document(s). No updates required.

^{You have 5 draft document(s). Publish docs to keep them always up-to-date}

^{How did I do? Any feedback?}  

[mergify]

Merge Protections

Your pull request matches the following merge protections and will not be merged until they are valid.

🟢 Enforce conventional commit

Wonderful, this rule succeeded.

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

• title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert)(?:\(.+\))?(!)?:

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[dolfim-ibm]

@FrigaZzz do you have a specific motivation for adding the token usage as a plugin example and not as an enhancement of the current model runtime?
Was the idea to use #2271 as an example for show casing #2402?

While having a first look, my thinking is

1. the token count could indeed be an interesting feature to support (not only as plugin example)
2. the plugin itself seems to have lots of replicated code from the current picture description. I think it could be simplified a lot deriving from the current version.

[FrigaZzz]

@FrigaZzz do you have a specific motivation for adding the token usage as a plugin example and not as an enhancement of the current model runtime? Was the idea to use #2271 as an example for show casing #2402?

While having a first look, my thinking is

1. the token count could indeed be an interesting feature to support (not only as plugin example)
2. the plugin itself seems to have lots of replicated code from the current picture description. I think it could be simplified a lot deriving from the current version.

Yes, exactly! I mainly wanted to showcase how to build these custom plugins, since we had some trouble configuring them last week for telemetry.

I purposely decided to extend the base classes while still keeping the same instance members, that’s on me.

I can definitely work out another PR extending the current PictureDescriptionApiOptions-related workflow. I’ll include the feature there and update the docs with an example on how to use it.
Does that sound like a good idea? I’ll open another PR if that works for you.

[FrigaZzz]

@FrigaZzz do you have a specific motivation for adding the token usage as a plugin example and not as an enhancement of the current model runtime? Was the idea to use #2271 as an example for show casing #2402?

While having a first look, my thinking is

1. the token count could indeed be an interesting feature to support (not only as plugin example)
2. the plugin itself seems to have lots of replicated code from the current picture description. I think it could be simplified a lot deriving from the current version.

I've simplified it to derive from the current picture description runtime so we only override what's necessary:

• Reuse the existing options via a thin subclass that adds a unique kind
• Reuse the existing concurrency/threshold behavior
• Override only the API call path to parse and propagate usage

This keeps the plugin minimal and focused on demonstrating the feature rather than re‑implementing the runtime.

Core integration (#2445)

I also prepared #2445 to integrate usage directly into the framework. The challenge: Description annotations live in docling_core, so the cleanest path is:

1. docling_core: Add optional usage field to DescriptionAnnotation (backward compatible)
2. docling: Parse and propagate usage when available; leave as None when not

#2445 uses a temporary PictureDescriptionDataWithUsage class defined directly in docling to validate the approach. Once we agree on the data model, I'll add the usage field directly to docling_core.

Current status:

• This PR: Minimal plugin deriving from current runtime
• feat(models): add API usage to picture descriptions; unify response type #2445: Framework integration ready, pending docling_core update

How can we proceed?