feat: Source2synth

[CaelumF]

Description

Introduces an implementation of Source2synth based on @zjrwtx 's work.

Also, this introduces an interface for programmatically interacting with agents. The main purpose of this interface is to encourage hardcoded functionality and composed functionality to work well together, because otherwise agents might end up just being a single function call (especially with structured output).

The guarantees encouraged by this interface are going to need to evolve, but I think this is a good start.

Types of changes

What types of changes does your code introduce? Put an x in all the boxes that apply:

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds core functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation (update in the documentation)
• Example (update in the folder of example)

Checklist

Go over all the following points, and put an x in all the boxes that apply.
If you are unsure about any of these, don't hesitate to ask. We are here to help!

• I have read the CONTRIBUTION guide. (required)
• My change requires a change to the documentation.
• I have updated the tests accordingly. (required for a bug fix or a new feature)
• I have updated the documentation accordingly.

[zjrwtx]

@CaelumF thanks! but it seems that some problems happen:

[Wendong-Fan]

i think it's not necessary to define this enum class just for 1 compont, maybe we can pass the variable directly to reduce code complexibility

[CaelumF]

My thinking for this is that with the requirements being an enum, implementors can easily know for example that all possible requirements are being met, since requirements are likely to be shared between different agents (as can the operations that modify agent state with them in consideration). The intention here is to sort of force certainty improving code to be separate from the functional code, which can be really beneficial for keeping things expectable in the future.

Though maybe the possible requirements should be part of a type parameter on the ProgrammableChatAgent implementation (several subclasses with different numbers of type parameters might be necessary until pydantic supports variadic generics), since they should be relevant only to the @programmable_capabilitys.

I wanted to allow specifying the agent state requirements in the @programmable_capability itself, but unfortunately python's decorators are pretty cumbersome to provide parameters when decorating functions.

There might be a nice way of doing that still though, like through providing a wrapping interface to the agent methods that requires explicitly stating the state expectations, and possibly having these return a sort of atomic operation accumulating object like what torch does. Incompatible operation chains then can be easily detected before execution, and the business logic can more easily coerce state into being compatible before starting the operation chain.

I think the direction here is pretty important for programmed composable agents, paging @lightaime for thoughts.

For now though, I think this direction is okay, it means requirements need to be shared between functions inside an agent, and can be easily enough changed to a different method in the future, we should maybe just encourage people to put the state requirements in this enum