> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thesis.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK Specifications

> Specifications for the Thesis.io Python SDK

A Python client for interacting with the Thesis.io API, enabling conversations, research, and space management.

## Installation

```bash theme={null}
pip install thesis_py
```

## Quick Start

Initialize the Thesis client with your API key:

```python theme={null}
from thesis_py import Thesis

# Initialize client with API key
thesis = Thesis(api_key="your-api-key")

# Optional: specify custom base URL
thesis = Thesis(api_key="your-api-key", base_url="https://custom-endpoint.com")
```

## Basic Usage

### Conversations

Create and manage Thesis.io DeFi research conversations with different research modes.

#### Create a New Conversation

```python theme={null}
from thesis_py.api_schema import CreateNewConversationIntegrationRequest, ResearchMode

# Create a conversation with deep research mode
response = thesis.create_conversation(
    CreateNewConversationIntegrationRequest(
        initial_user_msg="What's the new DeFi meta recently that I can ape in?",
        research_mode=ResearchMode.DEEP_RESEARCH,
        system_prompt="You are a DeFi gigachad who's always ahead of the new DeFi meta.",
        space_id=123,  # Optional: link to a specific space
        space_section_id=456,  # Optional: link to a specific section
    )
)
print(f"Conversation ID: {response.conversation_id}")
```

#### Research Modes

* `ResearchMode.CHAT` - Interactive chat mode
* `ResearchMode.DEEP_RESEARCH` - Comprehensive research with citations
* `ResearchMode.FOLLOW_UP` - Follow-up research on existing topics

#### Get Conversation Details

```python theme={null}
# Retrieve conversation by ID
conversation = thesis.get_conversation_by_id("conv_abc123def456")
print(f"Status: {conversation.status}")
print(f"Events: {len(conversation.events) if conversation.events else 0}")

# Async version
conversation = await thesis.get_conversation_by_id_async("conv_abc123def456")
```

#### Join Existing Conversation (Streaming)

```python theme={null}
import asyncio
from thesis_py.api_schema import JoinConversationIntegrationRequest

async def join_conversation_example():
    async for event in thesis.join_conversation(
        JoinConversationIntegrationRequest(
            conversation_id="conv_abc123def456",
            user_prompt="Continue the research on recent DeFi trends",
            research_mode=ResearchMode.CHAT,
        )
    ):
        # Process streaming events
        print(f"Event: {event}")

# Run the async function
asyncio.run(join_conversation_example())
```

### Spaces

Manage Thesis.io DeFi research spaces and their sections.

#### List Spaces

```python theme={null}
# Get all spaces with pagination
spaces = thesis.get_spaces(limit=10, offset=0)
print(f"Found {len(spaces.data)} spaces")

for space_item in spaces.data:
    space = space_item.space
    print(f"Space: {space.title} (ID: {space.id})")
```

#### Get Space Details

```python theme={null}
# Get detailed information about a space
space_detail = thesis.get_space_by_id("868")
space = space_detail.data

print(f"Title: {space.title}")
print(f"Description: {space.description}")
print(f"Members: {space.memberCount}")
print(f"Research Count: {space.totalResearch}")
```

#### Get Space Sections

```python theme={null}
# Get all sections within a space
sections = thesis.get_space_sections("868")

for section in sections.data:
    print(f"Section: {section.name}")
    print(f"Description: {section.description}")
    print(f"Output Type: {section.outputType}")
```

## Advanced Usage

### Working with Events

Process Thesis.io DeFi research conversation events and extract structured data:

```python theme={null}
from thesis_py.research.events import from_raw_events_to_pairs
from thesis_py.research.events.utils import get_pairs_from_events

# Get conversation and process events
conversation = thesis.get_conversation_by_id("conv_id")
pairs = from_raw_events_to_pairs(conversation.events[:2])

# For streaming events
async for event in thesis.join_conversation(request):
    pairs = get_pairs_from_events([event])
    print(pairs)
```

### Environment Variables

Set your API key using environment variables:

```bash theme={null}
export THESIS_API_KEY="your-api-key-here"
export THESIS_BASE_URL="https://app-be.thesis.io"  # Optional
```

```python theme={null}
import os
from thesis_py import Thesis

# Will automatically use THESIS_API_KEY from environment
thesis = Thesis(api_key=os.environ["THESIS_API_KEY"])
```

## Examples

Complete examples are available in the `examples/` directory:

* `hello_world.py` - Basic conversation creation
* `get_conversation.py` - Retrieve and process conversation events
* `get_spaces.py` - List and explore spaces
* `join_conversation.py` - Join conversations with streaming

## Error Handling

```python theme={null}
import requests
from thesis_py import Thesis

try:
    thesis = Thesis(api_key="your-api-key")
    response = thesis.create_conversation(request)
except requests.HTTPError as e:
    print(f"HTTP Error: {e.response.status_code}")
    print(f"Response: {e.response.text}")
except ValueError as e:
    print(f"Validation Error: {e}")
```

## Data Models

The SDK uses Pydantic models for type safety and validation. Key models include:

* `ConversationCreateResponse` - Response from conversation creation
* `ConversationDetailResponse` - Detailed conversation information
* `SpaceListResponse` - List of spaces with pagination
* `SpaceDetailResponse` - Detailed space information
* `CreateNewConversationIntegrationRequest` - Request to create conversations
* `JoinConversationIntegrationRequest` - Request to join conversations

## Requirements

* Python 3.8+
* `httpx` for async HTTP requests
* `requests` for synchronous HTTP requests
* `pydantic` for data validation and serialization