Installation & Setup

Installation & Setup

This guide covers installing the Klira AI SDK across different environments and setting up your first integration.

Quick Installation

For most users, the simplest installation method is using pip:

pip install klira

Installation Options

Standard Installation

The standard installation includes the core SDK with basic functionality:

# Standard installation
pip install klira

# With specific version
pip install klira==0.1.0

# Upgrade to latest version
pip install --upgrade klira

Framework-Specific Installations

Install with optional dependencies for specific frameworks:

# For LangChain integration
pip install klira[langchain]

# For CrewAI integration
pip install klira[crewai]

# For LlamaIndex integration
pip install klira[llama-index]

# For all framework integrations
pip install klira[all]

Development Installation

For contributors or advanced users who want the latest features:

# Clone the repository
git clone https://github.com/klira-ai/klira-sdk.git
cd klira-sdk

# Install in development mode
pip install -e .

# Install with development dependencies
pip install -e .[dev]

System Requirements

Python Version

• Python 3.10 or higher (tested on 3.10, 3.11, 3.12, 3.13)
• Operating Systems: Windows, macOS, Linux

Core Dependencies

The SDK automatically installs these core dependencies:

• traceloop-sdk - OpenTelemetry integration
• opentelemetry-* - Observability instrumentation
• pydantic - Data validation and serialization
• colorama - Cross-platform colored terminal output
• pyyaml - YAML configuration file support

Optional Dependencies

Framework-specific dependencies (installed with extras):

# LangChain ecosystem
pip install klira[langchain] # Installs: langchain, langchain-openai, langchain-community

# CrewAI ecosystem
pip install klira[crewai] # Installs: crewai, crewai-tools

# LlamaIndex ecosystem
pip install klira[llama-index] # Installs: llama-index, llama-index-core

# OpenAI integration
pip install klira[openai] # Installs: openai>=1.0.0

# Anthropic integration
pip install klira[anthropic] # Installs: anthropic

# All integrations
pip install klira[all] # Installs all optional dependencies

Environment Setup

1. API Key Configuration

Klira AI requires an API key for operation. Set it using one of these methods:

Environment Variable (Recommended):

# Windows PowerShell
$env:KLIRA_API_KEY="your-api-key-here"

# Windows Command Prompt
set KLIRA_API_KEY=your-api-key-here

# Linux/macOS
export KLIRA_API_KEY="your-api-key-here"

Configuration File: Create a .env file in your project root:

KLIRA_API_KEY=your-api-key-here
KLIRA_APP_NAME=my-application
KLIRA_ENABLED=true

Programmatic Configuration:

import os
from klira.sdk import Klira

klira = Klira.init(
    app_name="MyApp",
    api_key=os.getenv("KLIRA_API_KEY"), # Recommended: use environment variable
    enabled=True
)

2. OpenTelemetry Configuration (Optional)

Configure custom OpenTelemetry endpoints if needed:

# Custom OTLP endpoint
export KLIRA_OPENTELEMETRY_ENDPOINT="https://your-otlp-endpoint.com"

# Disable telemetry entirely
export KLIRA_TRACING_ENABLED=false

3. Policy Configuration (Optional)

Set custom policy directories:

# Custom policies directory
export KLIRA_POLICIES_PATH="/path/to/your/policies"

# Disable policy enforcement
export KLIRA_POLICY_ENFORCEMENT=false

Installation Verification

Verify your installation with this simple test:

test_installation.py

import os
from klira.sdk import Klira
from klira.sdk.decorators import workflow
from klira.sdk.utils.context import set_hierarchy_context

# Initialize SDK
klira = Klira.init(
    app_name="InstallationTest",
    api_key=os.getenv("KLIRA_API_KEY"),
    enabled=True
)

# Set user context
set_hierarchy_context(user_id="test_user")

# Test decorator
@workflow(name="test_workflow", organization_id="test", project_id="test")
def test_function():
    return "Klira AI SDK is working!"

# Run test
result = test_function()
print(f" Installation successful: {result}")

Run the test:

python test_installation.py

Expected output:

 Installation successful: Klira AI SDK is working!

Framework-Specific Setup

OpenAI Agents SDK

# Install Klira AI with OpenAI support
pip install klira[openai]

# Set OpenAI API key (if using OpenAI LLMs)
export OPENAI_API_KEY="your-openai-api-key"

import os
from klira.sdk import Klira
from klira.sdk.decorators import tool, workflow
from klira.sdk.utils.context import set_hierarchy_context
from agents import Agent, Runner

# Initialize Klira AI
klira = Klira.init(
    app_name="OpenAI-Agents-App",
    api_key=os.getenv("KLIRA_API_KEY"),
    enabled=True
)

# Set user context
set_hierarchy_context(user_id="user_123")

@tool(name="calculator")
def calculate(expression: str) -> str:
    return str(eval(expression))

agent = Agent(
    name="MathBot",
    instructions="You are a helpful math assistant",
    tools=[calculate]
)

@workflow(name="math_workflow")
async def run_agent(query: str):
    result = await Runner.run(agent, query)
    return result.final_output

LangChain

# Install Klira AI with LangChain support
pip install klira[langchain]

import os
from klira.sdk import Klira
from klira.sdk.decorators import workflow, tool
from klira.sdk.utils.context import set_hierarchy_context
from langchain.agents import AgentExecutor, create_openai_tools_agent
from langchain_openai import ChatOpenAI

# Initialize Klira AI
klira = Klira.init(
    app_name="LangChain-App",
    api_key=os.getenv("KLIRA_API_KEY"),
    enabled=True
)

# Set user context
set_hierarchy_context(user_id="user_123")

@tool(name="weather_tool")
def get_weather(city: str) -> str:
    return f"Weather in {city}: Sunny, 75°F"

llm = ChatOpenAI()
tools = [get_weather]
agent = create_openai_tools_agent(llm, tools, "You are a weather assistant")
agent_executor = AgentExecutor(agent=agent, tools=tools)

@workflow(name="weather_workflow")
def run_weather_agent(query: str):
    return agent_executor.invoke({"input": query})["output"]

CrewAI

# Install Klira AI with CrewAI support
pip install klira[crewai]

import os
from klira.sdk import Klira
from klira.sdk.decorators import crew, task, agent
from klira.sdk.utils.context import set_hierarchy_context
from crewai import Agent, Task, Crew, Process

# Initialize Klira AI
klira = Klira.init(
    app_name="CrewAI-App",
    api_key=os.getenv("KLIRA_API_KEY"),
    enabled=True
)

# Set user context
set_hierarchy_context(user_id="user_123")

@agent(name="researcher")
def create_researcher():
    return Agent(
    role="Researcher",
    goal="Research topics thoroughly",
    backstory="You are an expert researcher",
    verbose=True
    )

@task(name="research_task")
def create_research_task(agent, topic):
    return Task(
    description=f"Research {topic} comprehensively",
    agent=agent,
    expected_output="A detailed research report"
    )

@crew(name="research_crew")
def create_crew():
    researcher = create_researcher()
    task = create_research_task(researcher, "AI trends")

    return Crew(
    agents=[researcher],
    tasks=[task],
    process=Process.sequential,
    verbose=True
    )

Virtual Environment Setup

For production deployments, use virtual environments:

Using venv (Python standard library)

# Create virtual environment
python -m venv klira-env

# Activate (Windows)
klira-env\Scripts\activate

# Activate (Linux/macOS)
source klira-env/bin/activate

# Install Klira AI
pip install klira

# Deactivate when done
deactivate

Using conda

# Create conda environment
conda create -n klira-env python=3.11

# Activate environment
conda activate klira-env

# Install Klira AI
pip install klira

# Deactivate when done
conda deactivate

Using Poetry (Recommended for Development)

# Initialize Poetry project
poetry init

# Add Klira AI dependency
poetry add klira

# Install dependencies
poetry install

# Run in Poetry environment
poetry run python your_script.py

Example pyproject.toml:

[tool.poetry]
name = "my-klira-app"
version = "0.1.0"
description = "My application using Klira AI SDK"

[tool.poetry.dependencies]
python = "^3.10"
klira = "^0.1.0"
langchain = { version = "^0.1.0", optional = true }
crewai = { version = "^0.1.0", optional = true }

[tool.poetry.extras]
langchain = ["langchain"]
crewai = ["crewai"]
all = ["langchain", "crewai"]

Docker Setup

For containerized deployments:

Basic Dockerfile

# Dockerfile
FROM python:3.11-slim

WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \
 gcc \
 && rm -rf /var/lib/apt/lists/*

# Copy requirements
COPY requirements.txt .

# Install Python dependencies
RUN pip install --no-cache-dir -r requirements.txt

# Copy application code
COPY . .

# Set environment variables
ENV KLIRA_API_KEY=""
ENV KLIRA_APP_NAME="dockerized-app"

# Run application
CMD ["python", "main.py"]

requirements.txt

klira==0.1.0
# Add other dependencies as needed
langchain>=0.1.0
openai>=1.0.0

Docker Compose

docker-compose.yml

version: '3.8'

services:
 klira-app:
 build: .
 environment:
 - KLIRA_API_KEY=${KLIRA_API_KEY}
 - KLIRA_APP_NAME=my-dockerized-app
 - KLIRA_TRACING_ENABLED=true
 ports:
 - "8000:8000"
 volumes:
 - ./policies:/app/policies:ro # Mount custom policies

Common Installation Issues

Issue 1: Python Version Compatibility

Error: ERROR: Package 'klira' requires a different Python

Solution: Ensure you’re using Python 3.10 or higher:

python --version # Should be 3.10+
pip --version # Should use the correct Python version

Issue 2: Dependency Conflicts

Error: ERROR: pip's dependency resolver does not currently have a backtracking strategy

Solutions:

# Option 1: Upgrade pip
pip install --upgrade pip

# Option 2: Use --force-reinstall
pip install --force-reinstall klira

# Option 3: Create fresh virtual environment
python -m venv fresh-env
fresh-env\Scripts\activate # Windows
pip install klira

Issue 3: Network/Proxy Issues

Error: ERROR: Could not fetch URL

Solutions:

# Configure proxy (if needed)
pip install --proxy http://proxy.company.com:8080 klira

# Use trusted hosts (if SSL issues)
pip install --trusted-host pypi.org --trusted-host pypi.python.org klira

# Upgrade certificates
pip install --upgrade certifi

Issue 4: Permission Issues

Error: ERROR: Could not install packages due to an EnvironmentError: [Errno 13] Permission denied

Solutions:

# Option 1: Install for user only
pip install --user klira

# Option 2: Use virtual environment (recommended)
python -m venv klira-env
klira-env\Scripts\activate
pip install klira

Next Steps

After installation, proceed to:

1. Quick Start Guide - Get up and running in 5 minutes
2. First Example - Complete walkthrough with working code
3. Configuration - Detailed configuration options

Getting Help

If you encounter issues:

1. Check the Troubleshooting Guide
2. Search GitHub Issues

3. Contact Support

---

Supported Python Versions: 3.10, 3.11, 3.12