Feat: LiteLlm: Make LiteLLM file attachment failures consistent by raising explicit errors instead of silent fallback

[Lin-Nikaido]

** Please make sure you read the contribution guide and file the issues in the right place. **
Contribution guide.

🔴 Required Information

Please ensure all items in this section are completed to allow for efficient
triaging. Requests without complete information may be rejected / deprioritized.
If an item is not applicable to you - please mark it as N/A

• related: fix: fallback invalid attached file with gemini #5472
• related: google gemini raises a raw API error when invalid attached file type #5473

Is your feature request related to a specific problem?

Yes
While investigating file attachment behavior in ADK/LiteLLM, I noticed that file-processing failures currently behave inconsistently depending on the failure type.

Current behavior:

1. provider/file URI incompatibility

   • Example: .pptx file passed via part.file to an Anthropic-backed LiteLLM model
   • ADK silently strips the file payload and falls back to a text reference here:
     

     adk-python/src/google/adk/models/lite_llm.py

     Lines 1112 to 1126 in fc45fa6

     	if _requires_file_uri_fallback(provider, model, part.file_data.file_uri):
     	logger.debug(
     	"File URI %s not supported for provider %s, using text fallback",
     	_redact_file_uri_for_log(
     	part.file_data.file_uri,
     	display_name=part.file_data.display_name,
     	),
     	provider,
     	)
     	identifier = part.file_data.display_name or part.file_data.file_uri
     	content_objects.append({
     	"type": "text",
     	"text": f'[File reference: "{identifier}"]',
     	})
     	continue

2. unsupported inline_data MIME type

   • LiteLLM raises an explicit ValueError

Both cases result in the model being unable to actually process the file.

However:

• one path silently degrades behavior
• the other path explicitly fails

This inconsistency is confusing for developers because ADK presents a unified abstraction, but attachment failures behave differently depending on internal provider logic.

In my case, I initially misunderstood the .pptx behavior because the request appeared to succeed while the file was actually ignored.

This can be especially dangerous when users ask questions like:

"Summarize this spreadsheet"
"Review this presentation"

The model may hallucinate an answer based only on the filename or surrounding prompt context.

Describe the Solution You'd Like

A clear and concise description of the feature or API change you want.
Be specific about input/outputs if this involves an API change.

I would like LiteLLM attachment handling to behave consistently.

Preferred behavior:

• If a file cannot actually be processed by the provider,
  raise an explicit error instead of silently falling back.

For example:

• unsupported MIME type → error
• unsupported provider file URI handling → error

This makes failure explicit and prevents accidental hallucinated responses.
If fallback behavior is intentionally desired, it should at least be clearly opt-in and documented.

Impact on your work

How does this feature impact your work and what are you trying to achieve?
If this is critical for you, tell us if there is a timeline by when you need
this feature.

I'm building applications on top of ADK where users upload documents for actual processing.
Silent fallback makes debugging difficult because requests appear successful while file inputs are effectively ignored.
This creates reliability risks for production systems that depend on document understanding workflows.

Willingness to contribute

Are you interested in implementing this feature yourself or submitting a PR?
Yes

---

🟡 Recommended Information

Describe Alternatives You've Considered

A clear and concise description of any alternative solutions or workarounds
you've considered and why they didn't work for you.

Proposed API / Implementation

If you have ideas on how this should look in code, please share a
pseudo-code example.

Additional Context

Add any other context or screenshots about the feature request here.

Related discussion:

• Closed PR: fix: fallback invalid attached file with gemini #5472
• Related issue: google gemini raises a raw API error when invalid attached file type #5473

I completely agree with the concern raised in the previous PR that lossy conversion can cause hallucinations.
This issue is specifically about making existing failure behavior consistent and safer.