literalai

library0.1.300pypypi✓ verified 85d ago

The Literal AI Python SDK provides observability for large language model (LLM) applications. It enables developers to trace, monitor, and debug their LLM interactions and application flows directly from their Python code. As of version 0.1.300, it's an actively developed library with frequent releases in its 0.1.x series, indicating ongoing feature development and potential API refinements.

llm-agents ai-ml observability

pip install literalai

package ↗homepage ↗

INSTALL

IMPORT

SIG · LITERALAI

literalai

llm-agentspythonv0.1.300

Install

16.2s avg

Import

2655ms

Disk

86MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.1.300 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 2.899s · 83MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 16.2s · import 2.412s · 82MB

86MB installed

● package 86MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

LiteralClient

✓ from literalai import LiteralClient

get_literal_context

✓ from literalai import get_literal_context

Used for accessing the current trace context, e.g., to manually add steps or properties.

This quickstart initializes the Literal AI client and demonstrates how to trace a simple function representing an LLM call using the `@client.trace` decorator. It checks for the `LITERAL_API_KEY` environment variable to ensure the example runs correctly.

import os from literalai import LiteralClient # Initialize the client with your API key # Ensure LITERAL_API_KEY environment variable is set or pass it directly client = LiteralClient(api_key=os.environ.get("LITERAL_API_KEY", "")) @client.trace(name="my_simple_llm_call_trace") def my_simple_llm_call(prompt: str): """Simulates an LLM call and returns a response.""" print(f"Processing prompt: {prompt}") response = f"Simulated response to: {prompt}" # In a real scenario, this would involve calling an actual LLM # e.g., OpenAI, Anthropic, etc., and potentially logging its output return {"output": response, "model": "simulated-model-v1"} # Run the traced function if os.environ.get("LITERAL_API_KEY"): result = my_simple_llm_call("Tell me a short story about a brave knight.") print(f"Trace result: {result}") else: print("LITERAL_API_KEY not set. Skipping trace execution. Please set it to run the example.")

Debug

Known issues

gotchaThe `LITERAL_API_KEY` environment variable is required for authentication with the Literal AI platform. While older versions (specifically around `0.1.139`) experimented with `LITERAL_CLIENT_ID` and `LITERAL_CLIENT_SECRET`, the current recommended and supported method for the `0.1.x` series uses a single `LITERAL_API_KEY`.

fix

Ensure `LITERAL_API_KEY` is set in your environment. If you're using an older client, update to the latest version and verify your authentication method.

affects: All versions. Particularly confusing for users migrating from specific previous experimental versions around `0.1.139`.

breakingAs the library is in its `0.1.x` release series, API contracts can change between minor versions (e.g., `0.1.X` to `0.1.Y`) without strict adherence to semantic versioning. Frequent updates may introduce breaking changes to method signatures, class names, or expected parameters.

fix

Regularly check release notes for breaking changes when updating the library. Pin your dependency version if stability is critical, and plan for periodic updates and code adjustments.

affects: All `0.1.x` versions.

gotchaWhen working with asynchronous code (e.g., `async def` functions), ensure you use `await` with Literal AI's async methods (e.g., `await client.atrack()`, `await client.atrace()`). Incorrectly mixing synchronous and asynchronous calls can lead to `RuntimeWarning`s, unhandled exceptions, or unexpected behavior in tracing.

fix

Identify whether you are operating in synchronous or asynchronous contexts and use the appropriate client methods and `await` keyword. For example, use `@client.atrace` decorator for async functions.

affects: All versions with async support.

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'literalai'

The `literalai` library is not installed in your Python environment or the environment where your code is being run.

fix

Install the library using pip: `pip install literalai`

ValueError: Missing API key. Please set the LITERAL_API_KEY environment variable or pass it directly to LiteralClient.

The `LiteralClient` was initialized without a valid API key, which is required for authentication with the Literal AI platform.

fix

Set the `LITERAL_API_KEY` environment variable with your actual API key, or pass it directly when initializing the client: `import os; from literalai import LiteralClient; literalai_client = LiteralClient(api_key=os.getenv('LITERAL_API_KEY'))` or `literalai_client = LiteralClient(api_key='YOUR_API_KEY_HERE')`

Exception: [{'message': 'Unknown type "FeedbackPayloadInput". Did you mean "ThreadPayloadInput", "GenerationPayloadInput", or "ScorePayloadInput"?', 'locations': [{'line': 14, 'column': 22}]}, {'message': 'Unknown argument "feedback" on field "Mutation.ingestStep".', 'locations': [{'line': 31, 'column': 9}]}]

This error typically indicates that the client is sending an outdated or incorrect GraphQL payload to the Literal AI API, often due to an older SDK version or a mismatch in the expected data schema, specifically related to feedback submission within steps.

fix

Upgrade the `literalai` SDK to the latest version: `pip install --upgrade literalai`. If the issue persists, review the Literal AI documentation for any recent API changes related to feedback or step ingestion.

Exception: [{'message': 'Unknown type "ThreadFiltersInput". Did you mean "ThreadsOrderByInput" or "ThreadPayloadInput"?', 'locations': [{'line': 6, 'column': 23}]}]

This GraphQL error indicates an incorrect or deprecated input type used when querying or filtering threads, suggesting a mismatch between the client's request and the Literal AI API's expected schema for thread operations.

fix

Upgrade the `literalai` SDK to the latest version: `pip install --upgrade literalai`. If the error continues, consult the official Literal AI documentation for the correct usage of thread filtering and ordering parameters.

Upgrade

Version history

0.1.300latest on PyPI · released Apr 16, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://pypi.org/project/literalai/ ↗

homepagehttps://literalai.com ↗