feat: First-Class Function Calling & Auto-Execution Primitive

[Alistorm]

Context

Following up on #45 (Structured Messages) and referencing #147, the next logical primitive for Celeste is First-Class Function Calling.

Currently, using tools requires:

1. Manually defining JSON schemas (verbose, error-prone, provider-specific).
2. Manually handling the "LLM -> Stop -> Exec -> Result -> LLM" loop in user code.

This proposal aims to solve this by treating Python Callable objects as first-class citizens, leveraging the library's existing Pydantic infrastructure to automate schema generation and execution, without introducing heavy "Agent" abstractions.

Proposed DX

The user should be able to pass standard Python functions (typed) directly to generate().

from typing import Literal

def get_weather(city: str, unit: Literal["c", "f"] = "c") -> str:
    """Get the current weather for a specific city."""
    # ... implementation ...
    return f"25{unit} in {city}"

# 1. Schema generation is automatic (via Pydantic introspection)
# 2. Execution loop is handled internally (if max_steps > 0)
response = await celeste.text.generate(
    "What is the weather in Paris?",
    model="gpt-4o",
    tools=[get_weather],
    max_steps=5  # Enables the recursive execution loop
)

print(response.content) 
# Output: "It is 25c in Paris."

Architectural Design

This requires changes in three layers:

1. Schema Generation (src/celeste/utils/tools.py)

We can leverage pydantic.TypeAdapter (already used in structured_outputs.py) to reflect on function signatures and docstrings to generate standard JSON Schemas automatically. No new dependencies required.

2. Parameter Mapping (src/celeste/parameters.py)

We need a unified ToolsMapper. Since providers diverge significantly here:

• OpenAI: Uses tools array + tool_choice.
• Anthropic: Uses tools (top-level) + tool_choice (different structure).
• Google: Uses tools (wrapped in function_declarations).

The ParameterMapper logic I implemented previously handles this perfectly. We just need concrete implementations (OpenAIToolMapper, AnthropicToolMapper) to normalize the generic JSON schema into the vendor-specific payload.

3. The Execution Loop (src/celeste/client.py)

We update _predict (or wrap it) to handle the recursive case:

• Step 0: Generate schema from tools list.
• Step 1: Call Provider.
• Step 2: Check finish_reason. If TOOL_CALL:
  • Validate arguments against the Python function signature.
  • Execute the function (Sync or Async).
  • Append result message to history.
  • Recurse (decrement max_steps).
• Step 3: Return final TextOutput.

Definition of Done

• function_to_schema utility added.
• ToolMapper added to TextParameters and implemented for OpenAI/Anthropic/Gemini.
• generate() accepts tools: list[Callable] and max_steps: int.
• Integration tests verifying the loop works across providers.

I am happy to take this on as it aligns with the ideas on Message structures. This keeps the library "Primitive-first" while removing the boilerplate of the ReAct loop.

[Kamilbenkirane]

Rescoping: tools as a parameter, not a framework

After stepping back to think about this through celeste's own design principles, the original scope of this issue needs to be split.

The original proposal bundles two fundamentally different concerns:

1. Passing tool definitions to the model — primitive
2. Executing those tools automatically and looping — framework

These don't belong at the same layer.

---

The execution loop is not celeste's job.

Celeste's own README is clear: "No agents, no chains, no magic. Just clean I/O." An auto-execution loop with max_steps and function dispatch is a chain by definition. It belongs in an agent framework built on top of celeste, not inside celeste itself.

This is also where the entire industry draws the line. Both the official Anthropic Python SDK and OpenAI Python SDK return the raw tool call and stop — they do not execute. Auto-execution is what separates a primitive SDK from a framework. OpenAI even ships two separate packages to enforce this boundary: openai (primitive) and openai-agents (framework).

---

What tools actually are in celeste: a parameter.

The right analogy is already in our codebase: output_schema.

• output_schema → tell the model to return structured JSON → get back parsed data
• tools → tell the model what functions exist → get back a tool call

Both are inputs that shape what the model returns. Neither involves execution. The output is just data. What happens next is the caller's responsibility.

# Input — same pattern as output_schema
await client.generate("What's the weather in Paris?", tools=[get_weather_schema])

# Output — normalized across providers
output.tool_calls    # list of ToolCall objects, consistent shape regardless of provider
output.finish_reason # "tool_use" | "stop" | "length" | ...

Celeste's job here is the same as everywhere else: normalize provider differences (Anthropic's tool_use blocks, OpenAI's JSON-string arguments, Google's functionCall with no correlation ID) into one consistent shape.

---

Rescoped deliverables:

• tools parameter on generate() / stream() — maps tool definitions to each provider's native format
• tool_calls on TextOutput — normalized ToolCall objects, consistent across all providers
• finish_reason: "tool_use" surfaced correctly

Out of scope:

• Auto-execution loop, max_steps, function dispatch → belongs in a framework layer above celeste
• function_to_schema decorator → utility for the framework layer
• ToolMapper execution engine → same

Closing #147 as a duplicate — automatic tool execution is explicitly a framework concern.

[Kamilbenkirane]

@XinyueZ @Alistorm @JulesP96 @Seluj78 @Paulhb7 — Can you read the above and give me feedback on the rescoping. Does this make sense to you? Do you understand and agree ?

[XinyueZ]

@Kamilbenkirane @Alistorm I would like to remind you about the possibility of multithreading; simply using "function pointers" might lead to more than two threads using the same function at the same time. My solution is to use "copy tools." When providing tools for the API, it is important not to just "reference" them. This is based on my experience in my own small workshop and is just a reference.

[Alistorm]

@Kamilbenkirane Strongly agree with the rescoping. This is the correct architectural boundary.

1. Framework Agnostic: By returning normalized ToolCall objects instead of executing them, Celeste remains compatible with any execution strategy (ReAct, Plan-and-Solve, or custom event loops). If Celeste handled execution, it would inevitably impose constraints on async contexts, error handling, and dependency injection that belong in the application layer.

2. The output_schema Analogy: The comparison to output_schema is spot on. Both are constraints on the model's output. output_schema forces JSON structure; tools forces semantic intent structure. Neither should imply side-effects within the library itself.

3. Concrete Use Case: I am currently building a geospatial analytics gateway. We need to pass database connections and user session contexts into our tools. If Celeste owned the execution loop, injecting these runtime dependencies would be painful or impossible. By receiving a clean ToolCall object, we can execute the tool within our own DI container and security context.

tl;dr: Keep Celeste pure I/O. Normalizing the definition (input) and the call (output) across providers is the high-value primitive. Execution is our job.

[Kamilbenkirane]

@Kamilbenkirane @Alistorm I would like to remind you about the possibility of multithreading; simply using "function pointers" might lead to more than two threads using the same function at the same time. My solution is to use "copy tools." When providing tools for the API, it is important not to just "reference" them. This is based on my experience in my own small workshop and is just a reference.

@XinyueZ good point on thread safety. I think execution is not celeste's job. otherwise we would become a framework and not primitives. Does it make sense to you ? I propose the specs in #191 does it work with you ?

[Kamilbenkirane]

@Kamilbenkirane Strongly agree with the rescoping. This is the correct architectural boundary.

1. Framework Agnostic: By returning normalized ToolCall objects instead of executing them, Celeste remains compatible with any execution strategy (ReAct, Plan-and-Solve, or custom event loops). If Celeste handled execution, it would inevitably impose constraints on async contexts, error handling, and dependency injection that belong in the application layer.
2. The output_schema Analogy: The comparison to output_schema is spot on. Both are constraints on the model's output. output_schema forces JSON structure; tools forces semantic intent structure. Neither should imply side-effects within the library itself.
3. Concrete Use Case: I am currently building a geospatial analytics gateway. We need to pass database connections and user session contexts into our tools. If Celeste owned the execution loop, injecting these runtime dependencies would be painful or impossible. By receiving a clean ToolCall object, we can execute the tool within our own DI container and security context.

tl;dr: Keep Celeste pure I/O. Normalizing the definition (input) and the call (output) across providers is the high-value primitive. Execution is our job.

Amazing ! Thanks for the feedback. Can you check the #191 and tell me if that would help in your concrete use case or if you see missing things.

[XinyueZ]

@Kamilbenkirane @Alistorm I would like to remind you about the possibility of multithreading; simply using "function pointers" might lead to more than two threads using the same function at the same time. My solution is to use "copy tools." When providing tools for the API, it is important not to just "reference" them. This is based on my experience in my own small workshop and is just a reference.

@XinyueZ good point on thread safety. I think execution is not celeste's job. otherwise we would become a framework and not primitives. Does it make sense to you ? I propose the specs in #191 does it work with you ?

OK, thanks.

I prefer to use only the function method; frameworks like Langchain and some others are too complicated, making the learning curve quite steep. Your work aims for "simplicity," so there's no need to have multiple ways to accomplish one thing.

@celeste_tool()
def get_weather(city: str, unit: Literal["c", "f"] = "c") -> str:
   .....

Done! It's easy, and your branding-based tool decoration can even provide more "context" (if you want it to do that).

---

Because the original concept of a tool call was simply a function or method, but over the years, various frameworks have liked to "wrap" things, inexplicably adding classes to wrap parameters, and even using classes to represent tool calls. I feel that these ideas have strayed from their original intent.

[Kamilbenkirane]

@XinyueZ I think I'm aligned with claude on that one. Thanks for pushing back. Does this make sense to you or do you still have counter arguments ? Thanks so much for challenging

Claude's analysis:

XinyueZ's instinct is right — the dict is verbose. Nobody wants to write this:

{"name": "get_weather", "description": "...", "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}}

But a decorator as the PRIMARY interface has real problems for a primitives SDK:

1. What about tools that aren't Python functions? API endpoints, MCP tools, tools loaded from a database at runtime, tools defined by an OpenAPI spec. None of these have a function to decorate. The dict handles all of them.
2. OpenAI itself separates this. The openai package (primitive) uses dicts. The openai-agents package (framework) has @function_tool. They're in different packages for a reason.
3. Every SDK that offers a decorator also offers a dict/class path as the real primitive. No SDK offers ONLY the decorator. The decorator is always sugar on top.
4. A decorator inverts control — the library processes your function. That's the definition of a framework, not a library.

Recommendation: XinyueZ's example is valid but it's a convenience layer, not a primitive. The dict + Pydantic model approach (already in the spec) IS the primitive. A @celeste_tool() decorator could exist as optional sugar that generates the dict — but it's not the primary API and doesn't need to ship in v1.

[XinyueZ]

@Kamilbenkirane The purpose of using decorators is to bind some context. If you think this framework doesn't need any context, I mean, for example, one celeste and another celeste, or even more bold, a third celeste, using the same tool, but they need to share some information with each other, as well as some "independent" information.

@celeste_tool()
def foo():
   ctx = get_tool_context()
   shared_info = ctx["shared"][....]

sure， this is just something I designed in my small workshop considering my practical application scenarios. Because I want each tool to be thread-safe with respect to each other, each foo has a copy with an independent context, but can extract certain common information when necessary.

Of course, if you decide not to consider the "context," then obviously this decorator is unnecessary.

---

Anyway, the key issue is that if multiple celeste reference the same function, it is bound to be a potential problem. I appreciate the "hermit parameter tool_context" introduced by ADK.

---

[XinyueZ]

@Kamilbenkirane just for reminder #197

[passionworkeer]

Great feature proposal! Have you considered adding a streaming mode for function execution results? This would help with real-time feedback for long-running operations. Also, might be worth looking at the OpenAI Agents SDK's function calling patterns for inspiration - they've solved similar problems with their execution primitives.

[Kamilbenkirane]

Great feature proposal! Have you considered adding a streaming mode for function execution results? This would help with real-time feedback for long-running operations. Also, might be worth looking at the OpenAI Agents SDK's function calling patterns for inspiration - they've solved similar problems with their execution primitives.

Hey @passionworkeer sorry for replying only now didn't receive a notification somehow.
Thanks for the proposal.

tool calling shipped in #199, and streaming works with it :D

What we support:

• Streaming a response that includes tool calls (arguments build up incrementally via deltas)
• Streaming the model's response after you send a ToolResult back (multi-turn)

What we don't do:

• Execute tools. Celeste returns a raw ToolCall and stops. You run the function, you send the result back.

This was the #150 rescoping — celeste is the primitive layer, execution loops belong in frameworks built on top.

Does it make sense ? does it answer your question ? Let me know if I'm missing your point!