Add Prompt type to support updating agent prompts via updateConfiguration

[re1null0]

Fixes a bug where POST /v0/copilots/updateConfiguration returns a 500 error when the configuration.prompt field is provided:

• Add a Prompt model so users can pass configuration.prompt as either a plain string or an explicit Prompt object.
• Exports Prompt from credal, credal.copilots, and credal.copilots.types.
• Updates docstrings and reference.md with examples for both usage styles.

Test Plan:

Screen.Recording.2026-04-09.at.2.20.45.PM.mov

[greptile-apps]

Greptile Summary

This PR introduces a new Prompt model with a required text field and organizationPromptAdditionEnabled (defaulting to False), widens Configuration.prompt to accept Union[str, Prompt], and adds a _serialize_configuration helper so the correct object shape is sent on the wire — fixing the backend 500 that occurred when organizationPromptAdditionEnabled was absent.

• False documentation claim: Comments in client.py and reference.md state "The SDK wraps it into a Prompt object automatically" when a plain string is passed, but _serialize_configuration only calls jsonable_encoder(configuration) — strings are forwarded verbatim. If the backend still requires the object shape for string inputs, those callers will continue to 500.

Confidence Score: 4/5

Safe to merge after correcting the misleading "SDK wraps strings" comment, which contradicts the implementation and could leave string-prompt callers still hitting 500s.

The core model and serialization logic are correct. The P1 finding is a documentation claim that actively contradicts the code: the helper does not wrap plain strings, yet the docstring and reference example tell users it does. Until it is confirmed that the backend handles raw string prompts, or the wrapping logic is actually added, callers who relied on the old string API may still see 500 errors.

src/credal/copilots/client.py (lines 504-505) and reference.md (lines 722-723) — misleading comment about automatic string wrapping.

Vulnerabilities

No security concerns identified.

Important Files Changed

Filename	Overview
src/credal/copilots/types/prompt.py	New Prompt model with text (required) and organizationPromptAdditionEnabled (default False, alias-aliased); follows the existing Fern pattern correctly.
src/credal/copilots/types/configuration.py	prompt field widened to Union[str, Prompt]; change is backward-compatible and the Union is handled correctly by jsonable_encoder.
src/credal/copilots/raw_client.py	Introduces _serialize_configuration helper, but the docstring falsely claims it wraps plain strings into Prompt objects — the implementation just delegates to jsonable_encoder unchanged.
src/credal/copilots/client.py	Doc-comment in the sync/async update_configuration examples incorrectly states "The SDK wraps it into a Prompt object automatically," which is false.
reference.md	Same misleading comment as client.py: claims strings are auto-wrapped into Prompt objects, which does not match the implementation.
tests/custom/test_prompt_serialization.py	Good coverage of Prompt defaults, alias serialization, and Configuration variants; imports private _serialize_configuration which creates a fragile coupling.
src/credal/copilots/init.py	Adds Prompt to the copilots public exports correctly.
src/credal/init.py	Adds Prompt to the top-level SDK exports correctly.
src/credal/copilots/types/init.py	Adds Prompt to the types package; lazy-import machinery is wired correctly.

Prompt To Fix All With AI

This is a comment left during a code review.
Path: src/credal/copilots/client.py
Line: 504-505

Comment:
**Incorrect claim: SDK does not wrap strings into Prompt objects**

The comment says "The SDK wraps it into a Prompt object automatically," but `_serialize_configuration` just calls `jsonable_encoder(configuration)` — no wrapping occurs. A plain string is sent to the backend verbatim as `{"prompt": "..."}`. If the backend still requires an object shape (`{"text": "...", "organizationPromptAdditionEnabled": false}`), string prompts will continue to 500. The same false claim appears in `reference.md`.

```suggestion
        # Simplest usage – pass the prompt as a plain string.
        # The string is forwarded to the backend as-is.
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: reference.md
Line: 722-723

Comment:
**Incorrect documentation: string is not wrapped into a Prompt object**

Same false claim as in `client.py` — the SDK does not wrap plain strings. The `_serialize_configuration` implementation is simply `return jsonable_encoder(configuration)`, which serialises the string as-is. This documentation will mislead users who expect automatic conversion.

```suggestion
# Pass prompt as a plain string (backward-compatible).
# The string is forwarded to the backend as-is.
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: tests/custom/test_prompt_serialization.py
Line: 10

Comment:
**Test couples to a private function**

`_serialize_configuration` is a private API (leading underscore). Tests that reach into private symbols are fragile — any refactor of the function's name or location will break these tests without breaking the public contract. Consider testing the observable behaviour through the public surface (e.g., asserting the body sent in an HTTP request using `httpx.MockTransport` or `unittest.mock.patch`) rather than calling the private helper directly.

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (1): Last reviewed commit: "ship addition of prompt" | Re-trigger Greptile}

[greptile-apps]

Incorrect claim: SDK does not wrap strings into Prompt objects

The comment says "The SDK wraps it into a Prompt object automatically," but _serialize_configuration just calls jsonable_encoder(configuration) — no wrapping occurs. A plain string is sent to the backend verbatim as {"prompt": "..."}. If the backend still requires an object shape ({"text": "...", "organizationPromptAdditionEnabled": false}), string prompts will continue to 500. The same false claim appears in reference.md.

Suggested change

	# Simplest usage – pass the prompt as a plain string (backward-compatible).
	# The SDK wraps it into a Prompt object automatically.
	# Simplest usage – pass the prompt as a plain string.
	# The string is forwarded to the backend as-is.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/credal/copilots/client.py
Line: 504-505

Comment:
**Incorrect claim: SDK does not wrap strings into Prompt objects**

The comment says "The SDK wraps it into a Prompt object automatically," but `_serialize_configuration` just calls `jsonable_encoder(configuration)` — no wrapping occurs. A plain string is sent to the backend verbatim as `{"prompt": "..."}`. If the backend still requires an object shape (`{"text": "...", "organizationPromptAdditionEnabled": false}`), string prompts will continue to 500. The same false claim appears in `reference.md`.

```suggestion
        # Simplest usage – pass the prompt as a plain string.
        # The string is forwarded to the backend as-is.
```

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

Incorrect documentation: string is not wrapped into a Prompt object

Same false claim as in client.py — the SDK does not wrap plain strings. The _serialize_configuration implementation is simply return jsonable_encoder(configuration), which serialises the string as-is. This documentation will mislead users who expect automatic conversion.

Suggested change

	from credal.copilots import AiEndpointConfiguration, Configuration, Prompt
	# Pass prompt as a plain string (backward-compatible).
	# The string is forwarded to the backend as-is.

Prompt To Fix With AI

This is a comment left during a code review.
Path: reference.md
Line: 722-723

Comment:
**Incorrect documentation: string is not wrapped into a Prompt object**

Same false claim as in `client.py` — the SDK does not wrap plain strings. The `_serialize_configuration` implementation is simply `return jsonable_encoder(configuration)`, which serialises the string as-is. This documentation will mislead users who expect automatic conversion.

```suggestion
# Pass prompt as a plain string (backward-compatible).
# The string is forwarded to the backend as-is.
```

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

Test couples to a private function

_serialize_configuration is a private API (leading underscore). Tests that reach into private symbols are fragile — any refactor of the function's name or location will break these tests without breaking the public contract. Consider testing the observable behaviour through the public surface (e.g., asserting the body sent in an HTTP request using httpx.MockTransport or unittest.mock.patch) rather than calling the private helper directly.

Prompt To Fix With AI

This is a comment left during a code review.
Path: tests/custom/test_prompt_serialization.py
Line: 10

Comment:
**Test couples to a private function**

`_serialize_configuration` is a private API (leading underscore). Tests that reach into private symbols are fragile — any refactor of the function's name or location will break these tests without breaking the public contract. Consider testing the observable behaviour through the public surface (e.g., asserting the body sent in an HTTP request using `httpx.MockTransport` or `unittest.mock.patch`) rather than calling the private helper directly.

How can I resolve this? If you propose a fix, please make it concise.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[jackfischer]

Dont edit this generated code directly, instead edit the API definition yaml
https://github.com/Credal-ai/fern-docs/