Metadata-Version: 2.4
Name: slide-tyler
Version: 6.4.0
Summary: Tyler: A development kit for manifesting AI agents with a complete lack of conventional limitations
Project-URL: Homepage, https://github.com/adamwdraper/slide
Project-URL: Documentation, https://github.com/adamwdraper/slide#readme
Project-URL: Repository, https://github.com/adamwdraper/slide
Project-URL: Bug Tracker, https://github.com/adamwdraper/slide/issues
Author: adamwdraper
License: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: a2a-sdk>=0.3.0
Requires-Dist: aiohappyeyeballs>=2.4.4
Requires-Dist: aiohttp>=3.11.11
Requires-Dist: aiosignal>=1.3.2
Requires-Dist: aiosqlite>=0.21.0
Requires-Dist: alembic>=1.14.1
Requires-Dist: annotated-types>=0.7.0
Requires-Dist: anyio>=4.7.0
Requires-Dist: apscheduler>=3.11.0
Requires-Dist: asyncpg>=0.30.0
Requires-Dist: attrs>=24.3.0
Requires-Dist: backoff>=2.2.1
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: blinker>=1.9.0
Requires-Dist: browser-use>=0.1.40
Requires-Dist: cachetools>=5.5.0
Requires-Dist: click>=8.1.8
Requires-Dist: distro>=1.9.0
Requires-Dist: docker-pycreds>=0.4.0
Requires-Dist: email-validator>=2.2.0
Requires-Dist: emoji>=2.14.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: filelock>=3.16.1
Requires-Dist: filetype>=1.2.0
Requires-Dist: flask>=3.1.0
Requires-Dist: frozenlist>=1.5.0
Requires-Dist: fsspec>=2024.12.0
Requires-Dist: gitdb>=4.0.11
Requires-Dist: gitpython>=3.1.43
Requires-Dist: gql>=3.5.0
Requires-Dist: graphql-core>=3.2.5
Requires-Dist: greenlet>=3.1.1
Requires-Dist: h11>=0.14.0
Requires-Dist: httpcore>=1.0.7
Requires-Dist: httpx>=0.27.2
Requires-Dist: huggingface-hub>=0.27.0
Requires-Dist: imap-tools>=1.9.0
Requires-Dist: importlib-metadata>=8.5.0
Requires-Dist: iniconfig>=2.0.0
Requires-Dist: itsdangerous>=2.2.0
Requires-Dist: jinja2>=3.1.5
Requires-Dist: jiter>=0.8.2
Requires-Dist: jsonschema-specifications>=2024.10.1
Requires-Dist: jsonschema>=4.23.0
Requires-Dist: litellm>=1.81.0
Requires-Dist: mako>=1.3.9
Requires-Dist: markdown-it-py>=3.0.0
Requires-Dist: markupsafe>=3.0.2
Requires-Dist: mcp>=1.25.0
Requires-Dist: mdurl>=0.1.2
Requires-Dist: multidict>=6.1.0
Requires-Dist: narwhals>=1.19.1
Requires-Dist: numpy>=2.2.1
Requires-Dist: openai>=2.15.0
Requires-Dist: packaging>=24.2
Requires-Dist: pandas>=2.2.3
Requires-Dist: pdf2image>=1.17.0
Requires-Dist: pillow>=11.0.0
Requires-Dist: platformdirs>=4.3.6
Requires-Dist: propcache>=0.2.1
Requires-Dist: protobuf>=5.29.2
Requires-Dist: psutil>=6.1.1
Requires-Dist: pyarrow>=18.1.0
Requires-Dist: pydantic-core>=2.27.2
Requires-Dist: pydantic>=2.10.4
Requires-Dist: pygments>=2.18.0
Requires-Dist: pypdf>=5.3.0
Requires-Dist: python-dateutil>=2.9.0.post0
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: pytz>=2024.2
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: referencing>=0.35.1
Requires-Dist: regex>=2024.11.6
Requires-Dist: requests-toolbelt>=1.0.0
Requires-Dist: requests>=2.32.3
Requires-Dist: rich>=13.9.4
Requires-Dist: rpds-py>=0.22.3
Requires-Dist: sentry-sdk>=2.19.2
Requires-Dist: setproctitle>=1.3.4
Requires-Dist: six>=1.17.0
Requires-Dist: slack-sdk>=3.34.0
Requires-Dist: slide-lye>=6.4.0
Requires-Dist: slide-narrator>=6.4.0
Requires-Dist: smmap>=5.0.1
Requires-Dist: sniffio>=1.3.1
Requires-Dist: soupsieve>=2.6
Requires-Dist: sqlalchemy>=2.0.36
Requires-Dist: starlette>=0.41.3
Requires-Dist: tenacity>=9.0.0
Requires-Dist: tiktoken>=0.8.0
Requires-Dist: tokenizers>=0.21.0
Requires-Dist: toml>=0.10.2
Requires-Dist: tornado>=6.4.2
Requires-Dist: tqdm>=4.67.1
Requires-Dist: typing-extensions>=4.12.2
Requires-Dist: tzdata>=2024.2
Requires-Dist: urllib3>=2.3.0
Requires-Dist: uuid-utils>=0.10.0
Requires-Dist: uvicorn>=0.34.0
Requires-Dist: wandb>=0.19.1
Requires-Dist: weave>=0.52.42
Requires-Dist: werkzeug>=3.1.3
Requires-Dist: yarl>=1.18.3
Requires-Dist: zipp>=3.21.0
Provides-Extra: dev
Requires-Dist: coverage>=7.6.10; extra == 'dev'
Requires-Dist: pip-tools>=7.4.1; extra == 'dev'
Requires-Dist: pipdeptree>=2.25.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.25.2; extra == 'dev'
Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
Requires-Dist: pytest>=8.3.4; extra == 'dev'
Description-Content-Type: text/markdown

# Tyler

<div align="center">
    <img src="docs/static/img/tyler-soap.png" alt="Tyler Logo" width="200" style="border-radius: 8px;"/>
</div>

### A development kit for manifesting AI agents with a complete lack of conventional limitations

Tyler is the core agent framework in the Slide ecosystem. It makes it easy to build effective AI agents in just a few lines of code, providing all the essential components needed for production-ready AI agents that can understand context, manage conversations, and effectively use tools.

### Key Features

- **Multimodal support**: Process and understand images, audio, PDFs, and more out of the box
- **Ready-to-use tools**: Comprehensive set of built-in tools via the Lye package, with easy integration of custom tools
- **MCP compatibility**: Seamless integration with [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) compatible servers and tools
- **Real-time streaming**: Build interactive applications with streaming responses from both the assistant and tools
- **Structured data model**: Built-in support for threads, messages, and attachments to maintain conversation context
- **Persistent storage**: Powered by Narrator - choose between in-memory, SQLite, or PostgreSQL storage
- **Advanced debugging**: Integration with [W&B Weave](https://weave-docs.wandb.ai/) for powerful tracing and debugging capabilities
- **Flexible model support**: Use any LLM provider supported by LiteLLM (100+ providers including OpenAI, Anthropic, etc.)

![Tyler Chat UI Demo](docs/static/img/tyler_chat_UI_demo_short.gif)

---

<div style="display: flex; align-items: center; gap: 20px;">
    <span style="font-size: 1em;">Sponsored by</span>
    <a href="https://weave-docs.wandb.ai/"><img src="docs/static/img/weave_logo.png" alt="Weights & Biases Logo" height="40"/></a>
</div>

---

### For detailed documentation and guides, visit our [Docs](https://adamwdraper.github.io/tyler/).

While Tyler can be used as a library, it comes with two interactive interfaces:
1. A web-based chat interface available as a separate repository at [tyler-chat](https://github.com/adamwdraper/tyler-chat)
2. A built-in command-line interface (CLI) accessible via the `tyler-chat` command after installation. See the [Tyler chat CLI](https://adamwdraper.github.io/tyler/apps/tyler-chat-cli) documentation for details.

**Example configurations** for the Tyler CLI are available in this directory:
- `tyler-chat-config.yaml` - Basic configuration template
- `tyler-chat-config-wandb.yaml` - Configuration for W&B Inference with DeepSeek models


&nbsp;

![Workflow Status](https://github.com/adamwdraper/tyler/actions/workflows/pytest.yml/badge.svg)
[![PyPI version](https://img.shields.io/pypi/v/tyler-agent.svg?style=social)](https://pypi.org/project/tyler-agent/)

---

📚 **[Complete Documentation](https://slide.mintlify.app/)** | 🚀 **[Quickstart Guide](https://slide.mintlify.app/quickstart)** | 🎓 **[Your First Agent](https://slide.mintlify.app/guides/your-first-agent)**

---

## Overview

### Core Components

### Agent

The central component that:
- Manages conversations through threads
- Processes messages using LLMs (GPT-4.1 by default)
- Executes tools when needed
- Maintains conversation state
- Supports streaming responses
- Handles file attachments and processing
- Integrates with Weave for monitoring

### Thread

Manages conversations and maintains:
- Message history with proper sequencing
- System prompts
- Conversation metadata and analytics
- Source tracking (e.g., Slack, web)
- Token usage statistics
- Performance metrics

### Message

Basic units of conversation containing:
- Content (text or multimodal)
- Role (user, assistant, system, tool)
- Sequence number for ordering
- Attachments (files with automatic processing)
- Metrics (token usage, timing, model info)
- Source information
- Custom attributes

### Attachment

Handles files in conversations:
- Support for binary and base64 encoded content
- Automatic storage management
- Content processing and extraction
- Status tracking (pending, stored, failed)
- URL generation for stored files
- Secure backend storage integration

### Tools

Tyler's tools are provided by the `slide-lye` package. Extend agent capabilities with:
- Web browsing and downloads (WEB_TOOLS)
- Slack integration (SLACK_TOOLS)
- Notion integration (NOTION_TOOLS)
- Image processing (IMAGE_TOOLS)
- Audio processing (AUDIO_TOOLS)
- File operations (FILES_TOOLS)
- Shell commands (COMMAND_LINE_TOOLS)
- Browser automation (BROWSER_TOOLS)

### MCP

Integrates with the Model Context Protocol for:
- Seamless connection to MCP-compatible servers
- Automatic tool discovery from MCP servers
- Support for multiple transport protocols (WebSocket, SSE, STDIO)
- Server lifecycle management
- Dynamic tool invocation
- Integration with any MCP-compatible tool ecosystem

### Skills

Progressive skill disclosure following the [Agent Skills](https://agentskills.io/specification) open format:
- Skills are directories containing a `SKILL.md` file with YAML frontmatter (name, description) and markdown instructions
- Only skill metadata (name + description) appears in the system prompt — keeping context small
- Full instructions are loaded on-demand via the `activate_skill` tool when the agent decides it needs them
- Survives `connect_mcp()` prompt regeneration

```python
agent = Agent(
    model_name="gpt-4.1",
    purpose="A helpful assistant",
    skills=["./skills/code-review", "./skills/testing"],
)
```

Each skill directory contains a `SKILL.md`:
```markdown
---
name: code-review
description: Guidelines for performing thorough code reviews
---
# Code Review Skill

Review code for correctness, readability, and performance...
```

See `examples/108_skills.py` for a complete example.

### AGENTS.md

Project-level instructions following the [AGENTS.md](https://agents.md) open standard:
- Eagerly loaded into the system prompt at init time (unlike skills which are progressively disclosed)
- Auto-discovery walks upward from a base directory, collecting all `AGENTS.md` files (root-first ordering)
- Supports explicit paths, lists of paths, or boolean auto-discovery
- Content appears in a `<project_instructions>` block in the system prompt

```python
# Explicit path
agent = Agent(model_name="gpt-4.1", agents_md="./AGENTS.md")

# Auto-discover from CWD upward
agent = Agent(model_name="gpt-4.1", agents_md=True)

# Multiple files
agent = Agent(model_name="gpt-4.1", agents_md=["./AGENTS.md", "./docs/AGENTS.md"])
```

See `examples/109_agents_md.py` and `examples/sample-project/AGENTS.md` for a complete example.

### Storage

Storage is handled by the Narrator package, providing:
- Thread Storage:
  - Memory Store: Fast, in-memory storage for development
  - Database Store: PostgreSQL/SQLite for production
- File Storage:
  - Local filesystem with sharded organization
  - Automatic content processing and extraction
  - Configurable size limits and validation

## User Guide

### Prerequisites

- Python 3.13+
- uv (modern Python package manager) - recommended
- System dependencies for PDF and image processing

### Installation

```bash
# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install required libraries for PDF image processing
# macOS:
brew install poppler

# Ubuntu/Debian:
sudo apt-get install poppler-utils

# Using uv (recommended)
uv add slide-tyler

# Using pip (fallback)
pip install slide-tyler
```

# For development installation:
```bash
uv add slide-tyler --dev
```

When you install Tyler, all required runtime dependencies will be installed automatically, including:
- LLM support (LiteLLM, OpenAI)
- Storage components (Narrator)
- Tools package (Lye)
- Monitoring and metrics (Weave, Wandb)
- File processing (PDF, images)
- All core utilities

### Basic Setup

Create a `.env` file in your project directory with the following configuration:
```bash
# Database Configuration (used by Narrator)
# For local development with Docker: cd packages/narrator && docker-compose up -d
# Then use: NARRATOR_DATABASE_URL=postgresql+asyncpg://narrator:narrator_dev@localhost:5432/narrator
NARRATOR_DATABASE_URL=postgresql+asyncpg://user:password@localhost/dbname
# Or for SQLite:
# NARRATOR_DATABASE_URL=sqlite+aiosqlite:///path/to/database.db

# Optional Database Settings
NARRATOR_DB_ECHO=false
NARRATOR_DB_POOL_SIZE=5
NARRATOR_DB_MAX_OVERFLOW=10
NARRATOR_DB_POOL_TIMEOUT=30
NARRATOR_DB_POOL_RECYCLE=300

# OpenAI Configuration
OPENAI_API_KEY=your-openai-api-key

# Logging Configuration
WANDB_API_KEY=your-wandb-api-key
WANDB_PROJECT=your-weave-project-name

# Optional Integrations (for Lye tools)
NOTION_TOKEN=your-notion-token
SLACK_BOT_TOKEN=your-slack-bot-token
SLACK_SIGNING_SECRET=your-slack-signing-secret

# File storage configuration
NARRATOR_FILE_STORAGE_PATH=/path/to/files  # Optional, defaults to ~/.narrator/files
NARRATOR_MAX_FILE_SIZE=52428800  # 50MB default
NARRATOR_MAX_STORAGE_SIZE=5368709120  # 5GB default

# Other settings
LOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR, CRITICAL
```

Only the `OPENAI_API_KEY` (or whatever LLM provider you're using) is required for core functionality. Other environment variables are required only when using specific features:
- For Weave monitoring: set `WANDB_API_KEY` and call `weave.init(...)`, or set `WANDB_PROJECT` in examples that initialize Weave automatically. Tyler emits standard `weave.op` traces and Weave Agents session/turn/LLM/tool spans when the installed Weave version supports them. See the [Weave docs](https://weave-docs.wandb.ai/).
- For Slack integration: `SLACK_BOT_TOKEN` is required  
- For Notion integration: `NOTION_TOKEN` is required
- For database storage:
  - By default uses in-memory storage (perfect for scripts and testing)
  - For PostgreSQL or SQLite: Set `NARRATOR_DATABASE_URL` with appropriate connection string
- For file storage: Defaults will be used if not specified

For more details about each setting, see the [Environment Variables](#environment-variables) section.

### LLM Provider Support

Tyler uses LiteLLM under the hood, which means you can use any of the 100+ supported LLM providers by simply configuring the appropriate environment variables. Some popular options include:

```bash
# OpenAI
OPENAI_API_KEY=your-openai-api-key

# Anthropic
ANTHROPIC_API_KEY=your-anthropic-api-key

# Azure OpenAI
AZURE_API_KEY=your-azure-api-key
AZURE_API_BASE=your-azure-endpoint
AZURE_API_VERSION=2023-07-01-preview

# Google VertexAI
VERTEX_PROJECT=your-project-id
VERTEX_LOCATION=your-location

# AWS Bedrock
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_REGION_NAME=your-region
```

When initializing an Agent, you can specify any supported model using the standard model identifier:

```python
# OpenAI
agent = Agent(model_name="gpt-4")

# Anthropic
agent = Agent(model_name="claude-2")

# Azure OpenAI
agent = Agent(model_name="azure/your-deployment-name")

# Google VertexAI
agent = Agent(model_name="chat-bison")

# AWS Bedrock
agent = Agent(model_name="anthropic.claude-v2")
```

For a complete list of supported providers and models, see the [LiteLLM documentation](https://docs.litellm.ai/).

### Quick Start

This example uses in-memory storage which is perfect for scripts and testing. 

```python
from dotenv import load_dotenv
from tyler import Agent, Thread, Message, EventType
import asyncio

# Load environment variables from .env file
load_dotenv()

# Initialize the agent (uses in-memory storage by default)
agent = Agent(
    model_name="gpt-4.1",
    purpose="To help with general questions"
)

async def main():
    # Create a new thread
    thread = Thread()

    # Add a user message
    message = Message(
        role="user",
        content="What can you help me with?"
    )
    thread.add_message(message)

    # Stream the response as it is generated
    async for event in agent.stream(thread):
        if event.type == EventType.LLM_STREAM_CHUNK:
            print(event.data["content_chunk"], end="", flush=True)
        elif event.type == EventType.TOOL_SELECTED:
            print(f"\nUsing tool: {event.data['tool_name']}")
        elif event.type == EventType.TOOL_RESULT:
            print(f"\nTool result: {event.data['result']}")
        elif event.type == EventType.EXECUTION_COMPLETE:
            print(f"\nDone in {event.data['duration_ms']}ms")
            print(f"Tokens used: {event.data['total_tokens']}")

if __name__ == "__main__":
    asyncio.run(main())
```

`stream(...)` is the primary API for agent applications because it gives users immediate feedback while tools and LLM calls run. Use `run(...)` when you want to wait for completion and inspect the final `AgentResult`. `agent.go(thread)` remains available as a backwards-compatible alias for `agent.run(thread)`.

### Execution Observability

When you use non-streaming execution, every `AgentResult` includes an `execution` summary:

```python
result = await agent.run(thread)

print(result.success)
print(result.execution.duration_ms)
print(result.execution.total_tokens)

for tool_call in result.execution.tool_calls:
    print(tool_call.tool_name)
    print(tool_call.arguments)
    print(tool_call.result or tool_call.error)

for event in result.execution.events:
    print(event.type, event.timestamp)
```

Streaming uses the same event model in real time:

```python
async for event in agent.stream(thread):
    if event.type == EventType.LLM_STREAM_CHUNK:
        print(event.data["content_chunk"], end="", flush=True)
    elif event.type == EventType.TOOL_RESULT:
        print(event.data["result"])
```

### Using Config Files

Tyler supports creating agents from YAML configuration files, enabling you to share the same configuration between the CLI and Python code:

```python
from tyler import Agent, load_config
import asyncio

# Simple: Create agent from config file
agent = Agent.from_config("my-config.yaml")

# With overrides
agent = Agent.from_config(
    "my-config.yaml",
    temperature=0.9,
    model_name="gpt-4o"
)

# Auto-discovery (searches ./tyler-chat-config.yaml, ~/.tyler/chat-config.yaml, etc.)
agent = Agent.from_config()

# Advanced: Load and modify config before creating agent
config = load_config("my-config.yaml")
config["temperature"] = 0.9
agent = Agent(**config)
```

Example `tyler-chat-config.yaml`:
```yaml
name: "MyAgent"
model_name: "gpt-4.1"
temperature: 0.7
purpose: "A helpful AI assistant"
tools:
  - "web"
  - "slack"
skills:
  - "./skills/code-review"
  - "./skills/testing"
agents_md: true  # or "./AGENTS.md" or ["./AGENTS.md", "./docs/AGENTS.md"]
mcp:
  servers:
    - name: "docs"
      transport: "streamablehttp"
      url: "https://slide.mintlify.app/mcp"
```

See `examples/003_agent_from_config.py` for complete examples and `tyler-chat-config.yaml` for a full configuration template.

## Running Examples and Tests

Tyler comes with a variety of examples in the `examples/` directory that demonstrate different features and capabilities. These examples can also be run as integration tests to ensure everything is working correctly.

### Running Examples as Tests

The examples are integrated into the test suite with special markers to allow running them separately from unit tests:

```bash
# Run only the example tests
pytest -m examples

# Run only unit tests (excluding examples)
pytest -k "not examples"

# Run all tests (unit tests and examples)
pytest
```

This separation is particularly useful during development, allowing you to run the faster unit tests while making changes, and run the full test suite including examples before committing.

### Example Categories

The examples directory includes demonstrations of:

- Basic agent conversations
- Using built-in and custom tools
- Agent Skills with progressive disclosure (`108_skills.py`)
- AGENTS.md project instructions (`109_agents_md.py`)
- Working with file attachments
- Image and audio processing
- Streaming responses
- MCP (Model Context Protocol) integration

Each example is a standalone Python script that can be run directly or as part of the test suite.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
