​

Semantics

Literal AI approaches LLM logging at three levels:

1. Generation: Log of a single LLM call. (Generations are Steps.)
2. Step: Log of a regular function execution, which is usually an intermediate step in an LLM system. Possible types are: tool, embedding, retrieval, rerank, undefined, etc. Steps can be considered as Spans.
3. Run: Trace of an Agent/Chain run, including its intermediate steps. Can contain one or multiple generations.
4. Thread: A collection of Runs that are part of a single conversation.

You can log a generation only (typically for extraction use cases), or log a run only (typically for task automation), or combine them in threads (typically for chatbots).

​

Log an LLM Generation

Generations are logged by integrations with LLM providers. They capture the prompt, completion, settings, and token latency.

Here is an example with OpenAI:

literalai_client.instrument_openai()

# Run a regular OpenAI chat completion
from openai import OpenAI

oai = OpenAI()

def call_openai(user_input: str):
    oai.chat.completions.create(
        model="gpt-4o",
        messages=[{ "role": "user", "content": user_input }]
    )

call_openai("Hello world")

Check out the TypeScript client to learn more about the wrap function.

​

Multimodal LLM

You can leverage multimodal capabilities on Literal AI in two ways:

• Simple logging on API calls to Multimodal LLM APIs, like gpt-4o
• Save multimodal files as Attachments. Image, videos, audio and other files are shown as Attachment in the Literal AI platform, which can be accessed and downloaded via a Step.

​

Log a Run

A Run represents a trace of an Agent or Chain execution, capturing all intermediate steps and actions.

Runs can be logged manually using decorators or through framework integrations such as Llama Index or LangChain.

​

Log a Run with Intermediate Steps

Here’s how you can log a Run with intermediate steps using Python and TypeScript:

@literalai_client.step(type="tool")
def get_temperature(city: str):
    return "10C"

@literalai_client.run
def my_agent(user_input: str):
    # Reusing the OpenAI call from the previous example
    call_openai(user_input)
    # Naive tool example
    get_temperature("paris")
    return "Success"
    
my_agent("Hello world")

# Wait for all steps to be sent. This is NOT needed in production code.
literalai_client.flush()

​

Add Metadata and Tags to Steps

Tags and Metadata can be added to both Runs and Steps to provide additional context and facilitate filtering and categorization.

@literalai_client.run
def my_step(input):
    current_step = literalai_client.get_current_step()
    # some code, llm call, tool call, etc.
    current_step.metadata = {"region": "europe"}
    current_step.tags = ["to_review"]
    return "answer"

​

Add Attachments to Steps

You can attach files to a Run or any of its intermediate steps, which is particularly useful for multimodal use cases.

@literalai_client.step(type="tool")
def load_document():
    with open ("./some.pdf", "rb") as file:
        literalai_client.api.create_attachment(
          name="pdf_document",
          content=file.read()
          )
    return "doc loaded"

​

Learn More

The intermediate steps and the agent itself are logged using the Step class. You can learn more about the Step API in the following references:

​

Log a Thread

You can interact with an example Thread in the platform here.

It is up to the application to keep track of the thread ID and pass it to the Literal AI client. Every run logged with the same thread ID will be part of the same conversation.

Here is an example:

import uuid

def process_message(thread_id: str, user_input: str):
    with literalai_client.thread(thread_id=thread_id) as thread:
        # Reusing the Agent from the previous example
        my_agent(user_input)

thread_id = str(uuid.uuid4())
# Calling the agent a first time
process_message(thread_id=thread_id, user_input="foo")
# Calling the agent a second time with the same thread ID
process_message(thread_id=thread_id, user_input="bar")

# Wait for all steps to be sent. This is NOT needed in production code.
literalai_client.flush()

You can learn more about the Thread API in the following references:

​

Bind a Thread to a User

You can bind a Thread to a User to track their activity: quite handy for chatbots and conversational AIs!

Simply provide a unique User identifier, such as an email.

# If the user `john.doe@example.com` does not exist, it's automatically created.
def process_message(thread_id: str, user_input: str):
    with literalai_client.thread(thread_id=thread_id, 
                                 participant_id="john.doe@example.com") as thread:
        # Reusing the Agent from the previous example
        my_agent(user_input)

​

Log to a Specific Environment

Literal AI supports logging to different environments, which allows you to separate your development, staging, and production data: dev, staging, prod. This is particularly useful for managing your LLM application lifecycle. To specify an environment when initializing the LiteralClient, you can use the environment parameter:

literalai_client = LiteralClient(environment="dev")

​

Log with a Release

Literal AI supports pairing your logs to a release, a release is a version of your deployed code to help you identify new issues and regressions.

This is particularly useful for managing your LLM application once in production. The value can be arbitrary, but we recommend Semantic Versioning, Calendar Versioning, or the Git commit SHA.

To specify a release when initializing the LiteralClient, you can use the release parameter:

literalai_client = LiteralClient(release="81bec25")

Your logs will have a new key release in the metadata.

​

Log a Distributed Trace

​

Add a Score

Scores can be human generated (human feedback, like a thump up or down), or AI generated (hallucination evaluation for instance).

They can be visualized on the dashboard charts and used as filters.

​

Add a User Feedback

def add_user_feedback(run_id: str, value: int, comment: str):
    literalai_client.api.create_score(
        step_id=run_id,
        name="user-feedback",
        type="HUMAN",
        value=value,
        comment=comment,
    )

​

Add a Product-Related Metric

Correlate your LLM system to a product metric, such as conversion, churn, upsell, etc. This can be done by:

• Adding a specific product-related score on Literal AI.
• Sending the logged run id to your analytics system, such as PostHog or Amplitude.

​

Add an AI Evaluation Result

Refer to Online Evals

​

Fetch Existing Logs

You can fetch existing logs using the SDKs. Here is an example to fetch the last 5 threads where a user participated:

from literalai import LiteralClient

literalai_client = LiteralClient()

user_id = 'uuid'

threads = literalai_client.api.list_threads(
    first=5,
    filters=[{"operator": "eq", "field": "participantId", "value": user_id}]
)

for d in threads.data:
    print(d.to_dict())

literalai_client.flush_and_stop()

More generally, you can fetch any Literal AI object. Check out the SDKs and API reference to learn how.

​

On Literal AI

​

Filter logs

Leverage the powerful filters on Literal AI. Use these same filters to export your data using the SDKs.

​

Debug logged LLM generations

​

Add Tags and Scores from the UI

You can add tags and scores directly from the user interface.

​

Conclusion

Logging with Literal AI is composable and unopinionated. It can be done at different levels depending on your use case.