GLLM Core v0.3 to v0.4

Adding Custom Components

Overview

The Component API now supports an explicit main entrypoint via the @main decorator, with a resolver that determines which method to execute when calling run(). The legacy _run method remains supported as a fallback but is deprecated.

Resolution precedence for the main entrypoint:

1. Most derived method decorated with @main.

2. Method named by the __main_method__ class property.

3. Legacy _run method (deprecated fallback).

The input-parameter model (input_params) is generated from the resolved main method signature for the class.

Defining the main method (new)

1. Decorate an async instance method with @main.

2. Only one @main method per class is allowed.

3. If multiple ancestors define different @main methods, a TypeError is raised unless the subclass explicitly overrides with its own @main.

4. The __main_method__ class property is still supported but has lower precedence than @main. If both are present, a warning is logged and the decorator takes precedence.

5. The main method must be asynchronous.

Example:

import logging
from gllm_core.schema.component import Component, main

class MyComponent(Component):
    _default_log_level = logging.INFO

    @main
    async def execute(self, text: str) -> str:
        return text.upper()

Migrating from the old Component

If your component previously implemented _run, you have two options.

• Option A (minimal change): Keep _run and add a thin @main wrapper

  from gllm_core.schema.component import Component, main
  
  class MyComponent(Component):
      @main
      async def execute(self, **kwargs):
          return await self._run(**kwargs)
  
      async def _run(self, text: str) -> str:
          return text.upper()

• Option B (direct migration): Rename _run to a meaningful name and apply @main

  from gllm_core.schema.component import Component, main
  
  class MyComponent(Component):
      @main
      async def execute(self, text: str) -> str:
          return text.upper()

  Notes:

  • If any code or tests directly called _run, update those calls to use the new method or run().

  • input_params will now reflect the new method signature instead of _run.

Backward compatibility (non-migrated components)

• Components that only implement _run continue to work. The resolver falls back to _run and logs a deprecation warning recommending the @main decorator.

• input_params continues to be generated from _run in this case, so existing pipelines keep working.

• If both @main and __main_method__ are defined, a warning is emitted and the decorator wins.

Multiple inheritance considerations

• If two different ancestors define different @main methods and the subclass does not explicitly override them, a TypeError is raised at resolution time.

• To resolve, explicitly define a @main method in the subclass to choose the desired entrypoint.

Example resolution:

class A(Component):
    @main
    async def a(self): ...

class B(Component):
    @main
    async def b(self): ...

class C(A, B):
    @main
    async def choose(self): ...  # Explicit override resolves the conflict

Troubleshooting

1. TypeError: "Main method '...' must be asynchronous" — ensure the method decorated with @main is async def.

2. TypeError: "Multiple main methods defined in X" — only one @main per class is allowed.

3. TypeError about conflicting main methods across ancestors — add a @main method in the subclass to explicitly resolve.

Notes and best practices

1. Prefer an async instance method for the main entrypoint. Avoid using @staticmethod or @classmethod with @main.

2. Keep the main method signature representative of the inputs you expect; input_params will be generated from it.

3. You do not need to document run_profile or input_params in your component’s docstring; these are derived and consumed by the pipeline.

Disabling Timeout with Retry Config

When defining a RetryConfig object, setting the timeout attribute to 0.0 will previously cause the timeout to be disabled. Now, setting it to 0.0 will raise an error. Instead, set it to None to disable timeout.

Disabling Timeout Example (v0.3) — Will Raise Error in v0.4

from gllm_core.utils import RetryConfig

retry_config = RetryConfig(timeout=0.0)

Disabling Timeout Example (v0.4)

from gllm_core.utils import RetryConfig

retry_config = RetryConfig(timeout=None)

Data Event Type Removal

The data event type is removed from the EventType constant. The special handling of the data event type across event handlers are also removed. This is a result of the simplification of the emitted event schema. For example, if a thinking event was previously formatted as such:

{
    "type": "data",
    "value": '{"data_type": "thinking", "value": "I'm thinking!"}',
    ...
}

Now, it should be simplified as such:

{
    "type": "thinking",
    "value": "I'm thinking!",
    ...
}