PhiData (phidata) Library

2.7.10 · active · verified Fri Apr 17

PhiData (phidata) is a Python library designed for building multi-modal AI Agents with capabilities like memory, knowledge retrieval (RAG), and tool integration. It simplifies the development of complex AI workflows by providing high-level abstractions for agents, assistants, and various components. The current stable version is 2.7.10, and it maintains an active release cadence with frequent updates.

Common errors

```
openai.AuthenticationError: No API key provided.
```
cause The required LLM API key (e.g., OPENAI_API_KEY) environment variable is not set or is incorrect.

fix Set the environment variable for your LLM provider. For OpenAI, `export OPENAI_API_KEY='sk-...'` or add `OPENAI_API_KEY=sk-...` to a `.env` file and use `python-dotenv`.
```
ModuleNotFoundError: No module named 'qdrant_client'
```
cause You are trying to use a feature (e.g., Qdrant vector database) that requires an optional dependency which was not installed.

fix Install phidata with the necessary extra: `pip install "phidata[qdrant]"`. Replace `qdrant` with the appropriate extra for the missing module (e.g., `chroma`, `gradio`).
```
AttributeError: module 'phidata' has no attribute 'workflows'
```
cause Attempting to use a module or class path from phidata v1.x (e.g., `phidata.workflows` or `phi.assistant`) with a phidata v2.x installation. The API was refactored in v2.

fix Update your code to use the phidata v2.x API. For this specific error, `phidata.workflows` was renamed and moved to `phidata.app.PhiApp`. Consult the v2 documentation for correct imports.
```
ValidationError: 'Model' object has no attribute 'field_name' (related to Pydantic)
```
cause This can occur if you have a mix of Pydantic v1 and v2 libraries in your environment, or if you're passing incorrect data types to phidata models expecting Pydantic v2 behavior.

fix Ensure all Pydantic-dependent libraries are compatible with Pydantic v2. Check the data structures you are providing to phidata components against the expected Pydantic models in the documentation.

Warnings

breaking Phidata v2 introduced significant breaking changes compared to v1. Imports, configuration (from YAML to Python classes), and core APIs (e.g., `workflows` module) were completely refactored. Code written for v1 will not work with v2.
Fix: Migrate your codebase to the phidata v2 API. Refer to the official documentation (docs.phidata.dev) for updated import paths, class names, and configuration patterns.
gotcha Phidata requires Pydantic v2. If your project has other dependencies that explicitly pin Pydantic v1, you may encounter dependency conflicts or runtime errors due to incompatible Pydantic models.
Fix: Ensure all dependencies in your project are compatible with Pydantic v2, or use a tool like `pip-tools` or `poetry` for robust dependency resolution. Isolate environments if necessary.
gotcha All LLM integrations (OpenAI, Mistral, Anthropic, etc.) require their respective API keys to be set as environment variables (e.g., `OPENAI_API_KEY`). Failing to set these will result in authentication errors.
Fix: Set the required API key as an environment variable (e.g., `export OPENAI_API_KEY='sk-...'`). For local development, consider using `python-dotenv` to load keys from a `.env` file.
gotcha Many advanced features, tools, and vector database integrations (e.g., Gradio UI, Qdrant, ChromaDB, specific LLMs like Mistral/Anthropic) require installing phidata with optional 'extras'. Without these, you will encounter `ModuleNotFoundError`.
Fix: Install phidata with the necessary extras using `pip install "phidata[extra_name]"`. For example, `pip install "phidata[qdrant]"` for Qdrant support. Consult the phidata documentation for a list of available extras.

Install

pip install phidata Base Installation
pip install "phidata[gradio]" With Gradio UI (optional)
pip install "phidata[qdrant]" With Qdrant VectorDB (optional)
pip install "phidata[chroma]" With Chroma VectorDB (optional)

Imports

Assistant
wrong:
```
from phi.assistant import Assistant
```
correct:
```
from phidata.assistant import Assistant
```
In phidata v1, 'Assistant' was often imported from `phi.assistant`. In v2, the explicit `phidata` path is required.
Agent
wrong:
```
from phi.agent import Agent
```
correct:
```
from phidata.agent import Agent
```
Similar to 'Assistant', 'Agent' moved from `phi.agent` to `phidata.agent` in v2.
OpenAILLM
wrong:
```
from phi.llm.openai import OpenAILLM
```
correct:
```
from phidata.llm.openai import OpenAILLM
```
LLM providers also moved to the explicit `phidata.llm` path in v2.
PhiApp
wrong:
```
from phidata.workflows import PhiWorkflows
```
correct:
```
from phidata.app import PhiApp
```
`PhiWorkflows` was renamed and refactored into `PhiApp` under `phidata.app` in v2.

Quickstart

This quickstart demonstrates how to initialize an OpenAI LLM and create a simple Assistant to handle chat interactions. It highlights the basic setup for agents in phidata. Remember to set your `OPENAI_API_KEY` environment variable.

import os
from phidata.llm.openai import OpenAILLM
from phidata.assistant import Assistant

# Ensure OPENAI_API_KEY is set in your environment variables
# For local development, you might use python-dotenv:
# from dotenv import load_dotenv; load_dotenv()

# Initialize LLM (e.g., OpenAI)
# Replace with os.environ.get('OPENAI_API_KEY', '') for production if not using dotenv
llm = OpenAILLM(model="gpt-4o", api_key=os.environ.get('OPENAI_API_KEY', ''))

# Create an Assistant
assistant = Assistant(llm=llm, name="MyChatAssistant")

# Run a chat interaction
response = assistant.chat("Hello, how are you?")
print(f"Assistant: {response}")

response = assistant.chat("What is the capital of France?")
print(f"Assistant: {response}")

# Example with a tool (requires 'pip install "phidata[wikipedia]"')
# from phidata.tools.wikipedia import WikipediaTool
# assistant_with_tool = Assistant(
#     llm=llm,
#     name="WikiAssistant",
#     tools=[WikipediaTool()]
# )
# response = assistant_with_tool.chat("Who is Marie Curie?")
# print(f"WikiAssistant: {response}")

view raw JSON →