[OPIK-5500] [SDK] AgentConfigManager.update_blueprint() fails with TypeError on string values

[yaricom]

Details

Source: Ollie session 4, issue #3

The high-level SDK method update_blueprint(fields_with_values=...) tries to infer the backend type from the Python value. String values like "gpt-4o" cause TypeError: Unsupported type: gpt-4o — it's parsing the value as if it were a type. Even passing explicit field_types={...: str} didn't fix it.

Had to drop down to the raw REST API types (AgentBlueprintWrite, AgentConfigValueWrite) to publish.

Steps to reproduce:

1. config_manager.update_blueprint(fields_with_values={"key": ("old", "new", "desc")}, field_types={"key": str})
2. Get TypeError: Unsupported type: gpt-4o

Severity:

Major

---

Summary

Refactors fields_with_values handling in the Python SDK's agent configuration module by introducing a dedicated FieldValueSpec named tuple (in a new types.py module) to replace anonymous 3-tuples, improving type safety and readability across AgentConfigManager and AgentConfig.

Changes by Component

Python SDK

• Added sdks/python/src/opik/api_objects/agent_config/types.py with the FieldValueSpec(python_type, value, description) named tuple as the single canonical definition.
• Updated config.py to import and use types.FieldValueSpec everywhere raw Tuple[type, Any, Optional[str]] annotations existed; renamed local fields_with_values variable to resolved_fields_with_values for clarity.
• Extracted _build_blueprint_payload from an instance method on AgentConfigManager into a module-level function and updated it to use FieldValueSpec field accessors instead of tuple unpacking.
• Updated base.py to import the types module and use types.FieldValueSpec in _extract_fields_with_values and _matches_blueprint, replacing raw tuple construction and destructuring.
• Exported FieldValueSpec from the agent_config package __init__.py, importing it directly from .types rather than re-exporting from config.
• Updated all unit tests in test_config.py to use types.FieldValueSpec(...) instead of raw tuple literals.

Files Changed

 sdks/python/src/opik/api_objects/agent_config/__init__.py       |   2 +
 sdks/python/src/opik/api_objects/agent_config/base.py           |  24 +++--
 sdks/python/src/opik/api_objects/agent_config/config.py         | 110 +++++++++++----------
 sdks/python/src/opik/api_objects/agent_config/types.py          |  15 +++
 sdks/python/tests/unit/api_objects/agent_config/test_config.py  |  42 +++++---
 5 files changed, 117 insertions(+), 76 deletions(-)

Change checklist

• User facing
• Documentation update

Issues

• Resolves #
• OPIK-5500

AI-WATERMARK

AI-WATERMARK: [yes|no]

• If yes:
  • Tools:
  • Model(s):
  • Scope:
  • Human verification:

Testing

Updated tests

Documentation

Added new explicit field value specification type with related documentation.

[github-actions]

Python SDK Unit Tests Results (Python 3.11)

2 571 tests   2 571 ✅  1m 0s ⏱️
    1 suites      0 💤
    1 files        0 ❌

Results for commit e909c92.

♻️ This comment has been updated with latest results.

[github-actions]

Python SDK Unit Tests Results (Python 3.12)

2 571 tests   2 571 ✅  1m 9s ⏱️
    1 suites      0 💤
    1 files        0 ❌

Results for commit e909c92.

♻️ This comment has been updated with latest results.

[github-actions]

Python SDK Unit Tests Results (Python 3.13)

2 571 tests   2 571 ✅  56s ⏱️
    1 suites      0 💤
    1 files        0 ❌

Results for commit e909c92.

♻️ This comment has been updated with latest results.

[github-actions]

Python SDK Unit Tests Results (Python 3.10)

2 571 tests   2 571 ✅  1m 11s ⏱️
    1 suites      0 💤
    1 files        0 ❌

Results for commit e909c92.

♻️ This comment has been updated with latest results.

[github-actions]

Python SDK Unit Tests Results (Python 3.14)

2 571 tests   2 571 ✅  44s ⏱️
    1 suites      0 💤
    1 files        0 ❌

Results for commit e909c92.

♻️ This comment has been updated with latest results.

[petrotiurin]

Looks good, thanks for making this change!