glaip-sdk 0.8.5
Python SDK and CLI for GL AIP (GDP Labs AI Agent Package) - Build, run, and manage AI agents
License: MIT
Requires Python: <3.13,>=3.11

# GL AIP — GDP Labs AI Agents Package

[![Python 3.11-3.12](https://img.shields.io/badge/python-3.11--3.12-blue.svg)](https://www.python.org/downloads/)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

GL stands for **GDP Labs**—GL AIP is our AI Agents Package for building, running, and operating agents.

> **Python SDK and CLI for GL AIP - Connect, configure, and manage AI agents on the GDP Labs AI Agents Package.**

## 🚀 Quick Start

### Installation

Installing `glaip-sdk` provides both the **Python SDK** and the **`aip` CLI command** in a single package.

```bash
# Using pip (recommended)
pip install --upgrade glaip-sdk

# Using uv (fast alternative)
uv tool install glaip-sdk

# Using pipx (CLI-focused, isolated environment)
pipx install glaip-sdk
```

**Requirements**: Python 3.11 or 3.12

**Updating**: The `aip` CLI automatically detects your installation method and uses the correct update command:

- If installed via `pip`: Uses `pip install --upgrade glaip-sdk`
- If installed via `uv tool install`: Uses `uv tool install --upgrade glaip-sdk`
- You can also update manually using the same command you used to install

## 🐍 Hello World - Python SDK

Perfect for building applications and integrations.

### Step 1: Environment Setup

Create a `.env` file:

```bash
# .env
AIP_API_URL=https://your-gl-aip-instance.com
AIP_API_KEY=your-api-key
```

### Step 2: Basic Python Script

```python
# hello_world.py
from glaip_sdk import Client
import os
from dotenv import load_dotenv

# Load environment variables
load_dotenv()

# Initialize client
client = Client()

# Create a simple agent
agent = client.agents.create(
    name="hello-sdk",
    instruction="You are a helpful assistant who responds clearly and concisely."
)

# Run the agent
result = agent.run("Hello world, what's 2+2?")

print(f"Agent response: {result}")
```

### Step 3: Run Your Script

```bash
python hello_world.py
```

### Step 4: Advanced Example with Streaming

```python
# streaming_example.py
from glaip_sdk import Client
import os
from dotenv import load_dotenv

load_dotenv()
client = Client()

# Create agent with streaming
agent = client.agents.create(
    name="streaming-agent",
    instruction="You are a helpful assistant. Provide detailed responses."
)

# Stream the response
print("Streaming response:")
client.agents.run_agent(
    agent.id,
    "Explain quantum computing in simple terms",
    verbose=True,
)
print("--- Stream complete ---")
```

🎉 **SDK Success!** You're now ready to build AI-powered applications with Python.

______________________________________________________________________

## 💻 Hello World - CLI

Perfect for quick testing and command-line workflows.

### Step 1: Configure Connection

```bash
# Interactive setup (recommended)
aip configure
```

Or set environment variables:

```bash
export AIP_API_URL="https://your-gl-aip-instance.com"
export AIP_API_KEY="your-api-key"
```

### Step 2: Verify Connection

```bash
aip status
```

### Step 3: Create & Run Your First Agent

```bash
# Create a simple agent
aip agents create --name "hello-cli" --instruction "You are a helpful assistant"

# List agents to get the ID
aip agents list

# Run the agent with input
aip agents run <AGENT_ID> --input "Hello world, what's the weather like?"
```

🎉 **CLI Success!** You're now ready to use the CLI for AI agent workflows.

## ✨ Key Features

- **🤖 Agent Management**: Create, run, and orchestrate AI agents with custom instructions and streaming
- **🧠 Language Models**: Choose from multiple AI models per agent with manual PII tag mapping
- **🛠️ Tool Integration**: Extend agents with custom Python tools and script management
- **🔌 MCP Support**: Connect external services through Model Context Protocols with tool discovery
- **🔄 Multi-Agent Patterns**: Hierarchical, parallel, sequential, router, and aggregator patterns
- **🎙️ Audio Interface (beta)**: Local-only LiveKit voice sessions for talking to agents (install with `glaip-sdk[audio]`)
- **💻 Modern CLI**: Rich terminal interface with fuzzy search and multiple output formats

## 🎙️ Local Voice (LiveKit, Beta)

You can run a local voice loop that joins a LiveKit room, transcribes your speech, routes text into an agent, and speaks the reply back.

### Prerequisites

- LiveKit server running (monorepo dev: `make -C python/aip-agents livekit-up`)
- LiveKit Meet open in browser (monorepo dev: `make -C python/aip-agents livekit-meet-open`)
- `OPENAI_API_KEY` set (used by `livekit-plugins-openai` for STT/TTS)

### Monorepo Demo Sequence

```bash
# One-time install
make -C python/aip-agents install-audio

# Terminal 1: LiveKit server
make -C python/aip-agents livekit-up

# Terminal 2: Join with browser (enable mic)
make -C python/aip-agents livekit-meet-open

# Terminal 3: Run agent (recommended: debug logs)
AIP_AUDIO_DEBUG=1 make -C python/aip-agents audio-agent-up

# Optional: validate join/disconnect (no browser, no mic)
make -C python/aip-agents livekit-smoke-join
```

Tip: If STT shows odd fragments, it's often speaker-to-mic echo; use headphones.

Example `.env` values for the repo defaults:

```bash
LIVEKIT_URL=ws://localhost:7880
LIVEKIT_API_KEY=devkey
LIVEKIT_API_SECRET=devsecretdevsecretdevsecretdevsecret
LIVEKIT_ROOM_NAME=aip-audio-demo
OPENAI_API_KEY=...
```

### Install

```bash
pip install "glaip-sdk[audio]"
```

### Run the SDK example

From the repo:

```bash
cd python/glaip-sdk
poetry install --extras "audio"
poetry run python examples/sdk/05_audio_session.py
```

More details:

- `python/glaip-sdk/docs/how-to-guides/audio-interface.md`
- `python/glaip-sdk/examples/sdk/livekit-local-dev.md`

## 🌳 Live Steps Panel

The CLI steps panel now streams a fully hierarchical tree so you can audit complex agent runs without leaving the terminal.

- Renders parent/child relationships with `│├└` connectors, even when events arrive out of order
- Marks running steps with spinners and duration badges sourced from SSE metadata before local fallbacks
- Highlights failures inline (`✗ reason`) and raises warning glyphs on affected delegate branches
- Derives deterministic “💭 Thinking…” spans before/after each delegate or tool action to show scheduling gaps
- Flags parallel work with a dedicated glyph and argument-derived labels so simultaneous tool calls stay readable
- Try it locally: `poetry run python scripts/replay_steps_log.py --transcript tests/fixtures/rendering/transcripts/parallel_research.jsonl --output /tmp/parallel.log`

## 📚 Documentation

📖 **[Complete Documentation](https://gdplabs.gitbook.io/gl-aip/gl-aip-sdk/overview)** - Visit our GitBook for comprehensive guides, tutorials, and API reference.

Quick links:

- **[Quick Start Guide](https://gdplabs.gitbook.io/gl-aip/gl-aip-sdk/get-started/quick-start-guide)**: Get your first agent running in 5 minutes
- **[Agent Management](https://gdplabs.gitbook.io/gl-aip/gl-aip-sdk/guides/agents-guide)**: Complete agent lifecycle management
- **[Custom Tools](https://gdplabs.gitbook.io/gl-aip/gl-aip-sdk/guides/tools-guide)**: Build and integrate custom tools
- **[MCP Integration](https://gdplabs.gitbook.io/gl-aip/gl-aip-sdk/guides/mcps-guide)**: Connect external services
- **[API Reference](https://gdplabs.gitbook.io/gl-aip/gl-aip-sdk/reference/python-sdk-reference)**: Complete SDK reference

## 🧪 Simulate the Update Notifier

Need to verify the in-session upgrade flow without hitting PyPI or actually running `pip install`? Use the bundled helper:

```bash
cd python/glaip-sdk
poetry run python scripts/mock_update_notifier.py
# or customize the mock payload:
# poetry run python scripts/mock_update_notifier.py --version 3.3.3 --marker "[nightly build]"
```

The script:

- Launches a SlashSession with prompt-toolkit disabled (so it runs cleanly in tests/CI).
- Forces the notifier to believe a newer version exists (`--version 9.9.9` by default).
- Appends a visible marker (default `[mock update]`) to the banner so you can prove the branding reload happened; pass `--marker ""` to skip.
- Auto-selects “Update now”, mocks the install step, and runs the real branding refresh logic.
- Resets module metadata afterwards so your environment remains untouched.

You should see the Rich banner re-render with the mocked version (and optional marker) at the end of the run.