Skip to content

common_types

Class info

Classes

Name Children Inherits
BaseCode
llmling_agent.common_types
Base class for syntax-validated code.
ConfigCode
llmling_agent.common_types
Base class for configuration code that validates against a specific type.
    JSONCode
    llmling_agent.common_types
    JSON with syntax validation.
      ModelProtocol
      llmling_agent.common_types
      Protocol for model objects.
        PythonCode
        llmling_agent.common_types
        Python with syntax validation.
          TOMLCode
          llmling_agent.common_types
          TOML with syntax validation.
            YAMLCode
            llmling_agent.common_types
            YAML with syntax validation.

              🛈 DocStrings

              Type definitions.

              QueueStrategy module-attribute 

              QueueStrategy = Literal['concat', 'latest', 'buffer']

              The strategy for handling multiple tool calls when a final result is found.

              • 'early': Stop processing other tool calls once a final result is found
              • 'exhaustive': Process all tool calls even after finding a final result

              BaseCode

              Bases: BaseModel

              Base class for syntax-validated code.

              Source code in src/llmling_agent/common_types.py 
              76
77
78
79
80
81
82
83
84
85
86
87
88
              class BaseCode(BaseModel):
    """Base class for syntax-validated code."""

    code: str
    """The source code."""

    @field_validator("code")
    @classmethod
    def validate_syntax(cls, code: str) -> str:
        """Override in subclasses."""
        return code

    model_config = ConfigDict(use_attribute_docstrings=True)

              code instance-attribute 

              code: str

              The source code.

              validate_syntax classmethod 

              validate_syntax(code: str) -> str

              Override in subclasses.

              Source code in src/llmling_agent/common_types.py 
              82
83
84
85
86
              @field_validator("code")
@classmethod
def validate_syntax(cls, code: str) -> str:
    """Override in subclasses."""
    return code

              ConfigCode

              Bases: BaseCode

              Base class for configuration code that validates against a specific type.

              Generic type T specifies the type to validate against.

              Source code in src/llmling_agent/common_types.py 
              177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
              class ConfigCode[T](BaseCode):
    """Base class for configuration code that validates against a specific type.

    Generic type T specifies the type to validate against.
    """

    validator_type: ClassVar[type]

    @field_validator("code")
    @classmethod
    def validate_syntax(cls, code: str) -> str:
        """Validate both YAML syntax and type constraints."""
        import yamling

        try:
            # First validate YAML syntax
            data = yamling.load(code, mode="yaml")

            # Then validate against target type
            match cls.validator_type:
                case type() as model_cls if issubclass(model_cls, BaseModel):
                    model_cls.model_validate(data)
                case _ if origin := get_origin(cls.validator_type):
                    # Handle generics like dict[str, int]
                    if not isinstance(data, origin):
                        msg = f"Expected {origin.__name__}, got {type(data).__name__}"
                        raise ValueError(msg)  # noqa: TRY004, TRY301
                    # Validate type arguments if present
                    if args := get_args(cls.validator_type):
                        _validate_type_args(data, args)
                case _:
                    msg = f"Unsupported validation type: {cls.validator_type}"
                    raise TypeError(msg)  # noqa: TRY301

        except Exception as e:
            msg = f"Invalid YAML for {cls.validator_type.__name__}: {e}"
            raise ValueError(msg) from e

        return code

    @classmethod
    def for_config[TConfig](
        cls,
        base_type: type[TConfig],
        *,
        name: str | None = None,
        error_msg: str | None = None,
    ) -> type[ConfigCode[TConfig]]:
        """Create a new ConfigCode class for a specific type.

        Args:
            base_type: The type to validate against
            name: Optional name for the new class
            error_msg: Optional custom error message

        Returns:
            New ConfigCode subclass with type-specific validation
        """

        class TypedConfigCode(ConfigCode[TConfig]):
            validator_type = base_type

            @field_validator("code")
            @classmethod
            def validate_syntax(cls, code: str) -> str:
                try:
                    return super().validate_syntax(code)
                except ValueError as e:
                    msg = error_msg or str(e)
                    raise ValueError(msg) from e

        if name:
            TypedConfigCode.__name__ = name

        return TypedConfigCode

              for_config classmethod 

              for_config(
    base_type: type[TConfig], *, name: str | None = None, error_msg: str | None = None
) -> type[ConfigCode[TConfig]]

              Create a new ConfigCode class for a specific type.

              Parameters:

              Name Type Description Default
              base_type type[TConfig]

              The type to validate against

              		 required
              name str | None

              Optional name for the new class

              		 None
              error_msg str | None

              Optional custom error message

              		 None

              Returns:

              Type Description
              type[ConfigCode[TConfig]]

              New ConfigCode subclass with type-specific validation
              Source code in src/llmling_agent/common_types.py 
              217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
              @classmethod
def for_config[TConfig](
    cls,
    base_type: type[TConfig],
    *,
    name: str | None = None,
    error_msg: str | None = None,
) -> type[ConfigCode[TConfig]]:
    """Create a new ConfigCode class for a specific type.

    Args:
        base_type: The type to validate against
        name: Optional name for the new class
        error_msg: Optional custom error message

    Returns:
        New ConfigCode subclass with type-specific validation
    """

    class TypedConfigCode(ConfigCode[TConfig]):
        validator_type = base_type

        @field_validator("code")
        @classmethod
        def validate_syntax(cls, code: str) -> str:
            try:
                return super().validate_syntax(code)
            except ValueError as e:
                msg = error_msg or str(e)
                raise ValueError(msg) from e

    if name:
        TypedConfigCode.__name__ = name

    return TypedConfigCode

              validate_syntax classmethod 

              validate_syntax(code: str) -> str

              Validate both YAML syntax and type constraints.

              Source code in src/llmling_agent/common_types.py 
              185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
              @field_validator("code")
@classmethod
def validate_syntax(cls, code: str) -> str:
    """Validate both YAML syntax and type constraints."""
    import yamling

    try:
        # First validate YAML syntax
        data = yamling.load(code, mode="yaml")

        # Then validate against target type
        match cls.validator_type:
            case type() as model_cls if issubclass(model_cls, BaseModel):
                model_cls.model_validate(data)
            case _ if origin := get_origin(cls.validator_type):
                # Handle generics like dict[str, int]
                if not isinstance(data, origin):
                    msg = f"Expected {origin.__name__}, got {type(data).__name__}"
                    raise ValueError(msg)  # noqa: TRY004, TRY301
                # Validate type arguments if present
                if args := get_args(cls.validator_type):
                    _validate_type_args(data, args)
            case _:
                msg = f"Unsupported validation type: {cls.validator_type}"
                raise TypeError(msg)  # noqa: TRY301

    except Exception as e:
        msg = f"Invalid YAML for {cls.validator_type.__name__}: {e}"
        raise ValueError(msg) from e

    return code

              JSONCode

              Bases: BaseCode

              JSON with syntax validation.

              Source code in src/llmling_agent/common_types.py 
              108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
              class JSONCode(BaseCode):
    """JSON with syntax validation."""

    @field_validator("code")
    @classmethod
    def validate_syntax(cls, code: str) -> str:
        import yamling

        try:
            yamling.load(code, mode="json")
        except yamling.ParsingError as e:
            msg = f"Invalid JSON syntax: {e}"
            raise ValueError(msg) from e
        else:
            return code

              ModelProtocol

              Bases: Protocol

              Protocol for model objects.

              Source code in src/llmling_agent/common_types.py 
              23
24
25
26
27
28
              @runtime_checkable
class ModelProtocol(Protocol):
    """Protocol for model objects."""

    @property
    def model_name(self) -> str: ...

              PythonCode

              Bases: BaseCode

              Python with syntax validation.

              Source code in src/llmling_agent/common_types.py 
              142
143
144
145
146
147
148
149
150
151
152
153
154
              class PythonCode(BaseCode):
    """Python with syntax validation."""

    @field_validator("code")
    @classmethod
    def validate_syntax(cls, code: str) -> str:
        try:
            ast.parse(code)
        except SyntaxError as e:
            msg = f"Invalid Python syntax: {e}"
            raise ValueError(msg) from e
        else:
            return code

              TOMLCode

              Bases: BaseCode

              TOML with syntax validation.

              Source code in src/llmling_agent/common_types.py 
              125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
              class TOMLCode(BaseCode):
    """TOML with syntax validation."""

    @field_validator("code")
    @classmethod
    def validate_syntax(cls, code: str) -> str:
        import yamling

        try:
            yamling.load(code, mode="toml")
        except yamling.ParsingError as e:
            msg = f"Invalid TOML syntax: {e}"
            raise ValueError(msg) from e
        else:
            return code

              YAMLCode

              Bases: BaseCode

              YAML with syntax validation.

              Source code in src/llmling_agent/common_types.py 
               91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
              class YAMLCode(BaseCode):
    """YAML with syntax validation."""

    @field_validator("code")
    @classmethod
    def validate_syntax(cls, code: str) -> str:
        import yamling

        try:
            yamling.load(code, mode="yaml")
        except yamling.ParsingError as e:
            msg = f"Invalid YAML syntax: {e}"
            raise ValueError(msg) from e
        else:
            return code

              _validate_type_args 

              _validate_type_args(data: Any, args: tuple[Any, ...])

              Validate data against type arguments.

              Source code in src/llmling_agent/common_types.py 
              157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
              def _validate_type_args(data: Any, args: tuple[Any, ...]):
    """Validate data against type arguments."""
    match data:
        case dict() if len(args) == 2:  # noqa: PLR2004
            key_type, value_type = args
            for k, v in data.items():
                if not isinstance(k, key_type):
                    msg = f"Invalid key type: {type(k)}, expected {key_type}"
                    raise ValueError(msg)  # noqa: TRY004
                if not isinstance(v, value_type):
                    msg = f"Invalid value type: {type(v)}, expected {value_type}"
                    raise ValueError(msg)  # noqa: TRY004
        case list() if len(args) == 1:
            item_type = args[0]
            for item in data:
                if not isinstance(item, item_type):
                    msg = f"Invalid item type: {type(item)}, expected {item_type}"
                    raise ValueError(msg)  # noqa: TRY004