This page describes the details of the Solidity interface to the oracle, and how to use it in your contract. We assume you are familiar with the high-level architecture of Galadriel.

​
Oracle interface

The oracle is exposed as a contract that you can call from your own contract. It exposes two types of functionality: calling LLMs and calling external tools.

Any time you make a call to the oracle, you need to do at least two things:

  1. Call a method on the oracle contract to create a new call (to a model or a tool).
  2. Implement a callback method on your contract that the oracle will call once the response is available.

In each page of this reference you’ll see the method you need to call and the corresponding callback method you need to implement.

See source code for all the methods in the ChatOracle contract.

See the Usage examples below on how to integrate depending on your use case.

​
Usage examples

​
Calling an LLM

For calling an LLM, one option is to use the basic createLlmCall method, which has a simple interface but little configurability. The other option is to use the more complex but more powerful createOpenAiLlmCall method — to make a call to OpenAI-provided LLMs — or the createGroqLlmCall method — to make a call to Groq-provided LLMs.

Using the createLlmCall example: to call an LLM you need to:

1

Call the createLlmCall method on the oracle contract. This will create a new LLM call.

2

Implement two methods into your contract that the oracle will call to get the message history necessary for the LLM, including the system prompt: getMessageHistoryContents and getMessageHistoryRoles.

3

Implement the onOracleLlmResponse method into your contract. This method will be called when the LLM result is available (in a separate transaction potentially tens of seconds later).

Using the other two methods is analogous, but you need to use the corresponding callback method:

  • createLlmCall -> implement callback onOracleLlmResponse - see Basic LLM usage
  • createOpenAiLlmCall -> implement callback onOracleOpenAiLlmResponse - see OpenAI
  • createGroqLlmCall -> implement callback onOracleGroqLlmResponse - see Groq

​
Calling an external tool

If you are calling an external tool, you need to:

1

Call the createFunctionCall method on the oracle contract. This will create a new tool call.

2

Implement the onOracleFunctionResponse method into your contract. This method will be called when the tool result is available (in a separate transaction potentially tens of seconds later).

Since method calls do not reference a message history, you don’t need to implement any history getter methods.

​
Examples

Please refer to the example contracts, corresponding to the outlined use cases, for complete usage examples.

AgentsBasic