41 |
46 | );
47 | }
48 |
49 | export default function HomepageFeatures(): ReactNode {
50 | return (
51 | <>
52 |
42 | {title}
43 |
45 | {description}
44 |
54 |
64 |
55 |
63 |
56 | 
61 |
62 |
61 |
68 |
74 |
69 | {FeatureList.map((props, idx) => (
70 |
73 |
34 |
48 |
49 |
50 |
51 | 52 |
53 | 54 | # Chat with Tyler 55 | 56 | While Tyler can be used as a library, it also has a web-based chat interface that allows you to interact with your agent. The interface is available as a separate repository at [tyler-chat](https://github.com/adamwdraper/tyler-chat). 57 | 58 |  59 | 60 | ### Key features of Chat with Tyler 61 | - Modern, responsive web interface 62 | - Real-time interaction with Tyler agents 63 | - Support for file attachments 64 | - Message history and context preservation 65 | - Easy deployment and customization 66 | 67 | To get started with the chat interface, visit the [Chat with Tyler documentation](./chat-with-tyler.md). 68 | 69 | ## Next Steps 70 | 71 | - [Installation Guide](./installation.md) - Detailed installation instructions 72 | - [Configuration](./configuration.md) - Learn about configuration options 73 | - [Core Concepts](./core-concepts.md) - Understand Tyler's architecture 74 | - [API Reference](./category/api-reference) - Explore the API documentation 75 | - [Examples](./category/examples) - See more usage examples 76 | -------------------------------------------------------------------------------- /examples/explicit_stores.py: -------------------------------------------------------------------------------- 1 | import asyncio 2 | from tyler import Agent, Thread, Message, ThreadStore, FileStore 3 | # Import the individual store classes and registration functions 4 | from tyler.utils.registry import register_thread_store, register_file_store 5 | 6 | async def main(): 7 | """ 8 | Demonstrates explicitly creating and setting stores for an Agent. 9 | """ 10 | # 1. Create default in-memory stores individually. 11 | # Calling .create() without arguments defaults to in-memory. 12 | thread_store = await ThreadStore.create() 13 | file_store = await FileStore.create() 14 | print(f"Created in-memory stores:") 15 | print(f" Thread Store: {type(thread_store)}") 16 | print(f" File Store: {type(file_store)}") 17 | 18 | # 2. Register the stores in the global registry under the name "default". 19 | # This is optional - you can pass stores directly to the Agent constructor. 20 | register_thread_store("default", thread_store) 21 | register_file_store("default", file_store) 22 | print(f"Registered stores with name 'default'") 23 | 24 | # 3. Initialize the agent with explicit stores. 25 | # You can either pass the store instances directly or use store names from the registry. 26 | agent = Agent( 27 | name="StoreAwareAssistant", 28 | purpose="Answer questions concisely using explicitly set stores.", 29 | model_name="gpt-4.1", # Using preferred model 30 | thread_store=thread_store, # Pass store instance directly 31 | file_store=file_store # Pass store instance directly 32 | ) 33 | print(f"Initialized agent: {agent.name}") 34 | print("Agent configured with explicit stores.") 35 | 36 | # 4. Create a new thread. Because the agent is configured with stores, 37 | # operations like saving the thread will use the provided stores. 38 | thread = Thread() 39 | print(f"Created new thread with ID: {thread.id}") 40 | 41 | # 5. Add a user message 42 | user_message = Message(role="user", content="What is the capital of Spain?") 43 | thread.add_message(user_message) 44 | print(f"Added user message: '{user_message.content}'") 45 | 46 | # 6. Run the agent. It will use the configured stores internally. 47 | print("Running agent...") 48 | final_thread, new_messages = await agent.go(thread) 49 | print("Agent finished processing.") 50 | 51 | # 7. Print the assistant's response 52 | if new_messages: 53 | # Filter for the actual assistant response (last non-tool message) 54 | assistant_message = next((msg for msg in reversed(new_messages) if msg.role == 'assistant'), None) 55 | if assistant_message: 56 | print(f"Assistant Response: {assistant_message.content}") 57 | else: 58 | print("No assistant message found in new messages.") 59 | print("All new messages:", new_messages) 60 | else: 61 | print("No new messages were generated.") 62 | 63 | # Note: Since the stores are in-memory, the thread data still only exists 64 | # for the duration of this script run. To persist data, you would provide 65 | # a database URL to ThreadStore.create and a directory path to FileStore.create 66 | 67 | if __name__ == "__main__": 68 | # Added basic error handling for asyncio run 69 | try: 70 | asyncio.run(main()) 71 | except Exception as e: 72 | print(f"An error occurred: {e}") -------------------------------------------------------------------------------- /tyler/utils/files.py: -------------------------------------------------------------------------------- 1 | from typing import Optional, Dict 2 | from pathlib import Path 3 | from platformdirs import user_downloads_dir 4 | from urllib.parse import urlparse, unquote 5 | 6 | def get_unique_filepath(base_path: Path) -> Path: 7 | """ 8 | Get a unique file path by adding a number suffix if the file already exists. 9 | 10 | Args: 11 | base_path (Path): The initial file path to check 12 | 13 | Returns: 14 | Path: A unique file path that doesn't exist 15 | """ 16 | if not base_path.exists(): 17 | return base_path 18 | 19 | directory = base_path.parent 20 | stem = base_path.stem 21 | suffix = base_path.suffix 22 | counter = 1 23 | 24 | while True: 25 | new_path = directory / f"{stem} ({counter}){suffix}" 26 | if not new_path.exists(): 27 | return new_path 28 | counter += 1 29 | 30 | def save_to_downloads(*, content: bytes, filename: str = "", content_disposition: Optional[str] = None, url: Optional[str] = None) -> Dict: 31 | """ 32 | Save content to the user's Downloads directory with proper filename handling. 33 | 34 | Args: 35 | content (bytes): The content to save 36 | filename (str): Optional filename to save as 37 | content_disposition (str, optional): Content-Disposition header value for filename extraction 38 | url (str, optional): Original URL to extract filename from if not provided 39 | 40 | Returns: 41 | Dict: Contains file path and filename information 42 | """ 43 | try: 44 | # Use standard Downloads directory 45 | downloads_dir = Path(user_downloads_dir()) 46 | 47 | # Get filename from different sources in order of priority: 48 | # 1. Explicitly provided filename 49 | # 2. Content-Disposition header 50 | # 3. URL path 51 | # 4. Default fallback 52 | if not filename: 53 | if content_disposition: 54 | import re 55 | if match := re.search(r'filename="?([^"]+)"?', content_disposition): 56 | filename = match.group(1) 57 | elif url: 58 | parsed_url = urlparse(url) 59 | path = unquote(parsed_url.path) 60 | if path and '/' in path: 61 | filename = path.split('/')[-1] 62 | # Remove query parameters if they got included 63 | if '?' in filename: 64 | filename = filename.split('?')[0] 65 | 66 | # Fall back to default if still no filename 67 | if not filename: 68 | filename = 'downloaded_file' 69 | 70 | # Create full file path and ensure it's unique 71 | initial_path = downloads_dir / filename 72 | file_path = get_unique_filepath(initial_path) 73 | 74 | # Write the file 75 | with open(file_path, 'wb') as f: 76 | f.write(content) 77 | 78 | return { 79 | 'success': True, 80 | 'file_path': str(file_path), 81 | 'filename': file_path.name, # Use the potentially modified filename 82 | 'error': None 83 | } 84 | except Exception as e: 85 | return { 86 | 'success': False, 87 | 'file_path': None, 88 | 'filename': None, 89 | 'error': str(e) 90 | } -------------------------------------------------------------------------------- /tyler/tools/__init__.py: -------------------------------------------------------------------------------- 1 | """ 2 | Tools package initialization. 3 | """ 4 | import importlib 5 | import sys 6 | import os 7 | import glob 8 | from typing import Dict, List 9 | from tyler.utils.logging import get_logger 10 | 11 | # Get configured logger 12 | logger = get_logger(__name__) 13 | 14 | # Initialize empty tool lists for each module 15 | WEB_TOOLS = [] 16 | SLACK_TOOLS = [] 17 | COMMAND_LINE_TOOLS = [] 18 | NOTION_TOOLS = [] 19 | IMAGE_TOOLS = [] 20 | AUDIO_TOOLS = [] 21 | FILES_TOOLS = [] 22 | BROWSER_TOOLS = [] 23 | 24 | # Combined tools list 25 | TOOLS = [] 26 | 27 | # Try to import each tool module 28 | try: 29 | from . import web as web_module 30 | from . import slack as slack_module 31 | from . import command_line as command_line_module 32 | from . import notion as notion_module 33 | from . import image as image_module 34 | from . import audio as audio_module 35 | from . import files as files_module 36 | from . import browser as browser_module 37 | except ImportError as e: 38 | print(f"Warning: Some tool modules could not be imported: {e}") 39 | 40 | # Get tool lists from each module and maintain both individual and combined lists 41 | try: 42 | module_tools = getattr(web_module, "TOOLS", []) 43 | WEB_TOOLS.extend(module_tools) 44 | TOOLS.extend(module_tools) 45 | except Exception as e: 46 | print(f"Warning: Could not load web tools: {e}") 47 | 48 | try: 49 | module_tools = getattr(slack_module, "TOOLS", []) 50 | SLACK_TOOLS.extend(module_tools) 51 | TOOLS.extend(module_tools) 52 | except Exception as e: 53 | print(f"Warning: Could not load slack tools: {e}") 54 | 55 | try: 56 | module_tools = getattr(command_line_module, "TOOLS", []) 57 | COMMAND_LINE_TOOLS.extend(module_tools) 58 | TOOLS.extend(module_tools) 59 | except Exception as e: 60 | print(f"Warning: Could not load command line tools: {e}") 61 | 62 | try: 63 | module_tools = getattr(notion_module, "TOOLS", []) 64 | NOTION_TOOLS.extend(module_tools) 65 | TOOLS.extend(module_tools) 66 | except Exception as e: 67 | print(f"Warning: Could not load notion tools: {e}") 68 | 69 | try: 70 | module_tools = getattr(image_module, "TOOLS", []) 71 | IMAGE_TOOLS.extend(module_tools) 72 | TOOLS.extend(module_tools) 73 | except Exception as e: 74 | print(f"Warning: Could not load image tools: {e}") 75 | 76 | try: 77 | module_tools = getattr(audio_module, "TOOLS", []) 78 | AUDIO_TOOLS.extend(module_tools) 79 | TOOLS.extend(module_tools) 80 | except Exception as e: 81 | print(f"Warning: Could not load audio tools: {e}") 82 | 83 | try: 84 | module_tools = getattr(files_module, "TOOLS", []) 85 | FILES_TOOLS.extend(module_tools) 86 | TOOLS.extend(module_tools) 87 | except Exception as e: 88 | print(f"Warning: Could not load files tools: {e}") 89 | 90 | try: 91 | module_tools = getattr(browser_module, "TOOLS", []) 92 | BROWSER_TOOLS.extend(module_tools) 93 | TOOLS.extend(module_tools) 94 | except Exception as e: 95 | print(f"Warning: Could not load browser tools: {e}") 96 | 97 | __all__ = [ 98 | 'TOOLS', 99 | 'WEB_TOOLS', 100 | 'SLACK_TOOLS', 101 | 'COMMAND_LINE_TOOLS', 102 | 'NOTION_TOOLS', 103 | 'IMAGE_TOOLS', 104 | 'AUDIO_TOOLS', 105 | 'FILES_TOOLS', 106 | 'BROWSER_TOOLS' 107 | ] 108 | 109 | # Map of module names to their tools for dynamic loading 110 | TOOL_MODULES: Dict[str, List] = { 111 | 'web': WEB_TOOLS, 112 | 'slack': SLACK_TOOLS, 113 | 'command_line': COMMAND_LINE_TOOLS, 114 | 'notion': NOTION_TOOLS, 115 | 'image': IMAGE_TOOLS, 116 | 'audio': AUDIO_TOOLS, 117 | 'files': FILES_TOOLS, 118 | 'browser': BROWSER_TOOLS 119 | } -------------------------------------------------------------------------------- /examples/reactions_example.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python3 2 | """ 3 | Example demonstrating how to use message reactions in Tyler. 4 | 5 | This example shows how to: 6 | 1. Add reactions to messages 7 | 2. Remove reactions from messages 8 | 3. Get reactions for a message 9 | 4. Save/load threads with reactions to/from the database 10 | """ 11 | 12 | import asyncio 13 | from typing import Dict, List 14 | from tyler import Thread, Message, ThreadStore 15 | 16 | async def main(): 17 | # Create an in-memory ThreadStore for this example 18 | thread_store = await ThreadStore.create() 19 | 20 | # Create a new thread with some messages 21 | thread = Thread(title="Reactions Example") 22 | 23 | # Add some messages to the thread 24 | user_msg = Message(role="user", content="Hello! I have a question about reactions.") 25 | thread.add_message(user_msg) 26 | 27 | assistant_msg = Message(role="assistant", content="Sure, I'd be happy to help with reactions!") 28 | thread.add_message(assistant_msg) 29 | 30 | user_msg2 = Message(role="user", content="How do I add a thumbs up?") 31 | thread.add_message(user_msg2) 32 | 33 | assistant_msg2 = Message(role="assistant", content="It's easy! Just click the emoji button.") 34 | thread.add_message(assistant_msg2) 35 | 36 | # Print the thread messages 37 | print(f"Thread '{thread.title}' has {len(thread.messages)} messages:") 38 | for msg in thread.messages: 39 | print(f" - {msg.role}: {msg.content}") 40 | print() 41 | 42 | # Add reactions to messages 43 | print("Adding reactions...") 44 | 45 | # User 1 adds thumbs up to assistant's first message 46 | thread.add_reaction(assistant_msg.id, ":thumbsup:", "user1") 47 | 48 | # User 2 also adds thumbs up to the same message 49 | thread.add_reaction(assistant_msg.id, ":thumbsup:", "user2") 50 | 51 | # User 1 adds heart to assistant's second message 52 | thread.add_reaction(assistant_msg2.id, ":heart:", "user1") 53 | 54 | # User 3 adds rocket to assistant's second message 55 | thread.add_reaction(assistant_msg2.id, ":rocket:", "user3") 56 | 57 | # Display reactions 58 | print("\nReactions after adding:") 59 | for msg in thread.messages: 60 | if msg.reactions: 61 | print(f"Message '{msg.content}' has reactions:") 62 | for emoji, users in msg.reactions.items(): 63 | print(f" - {emoji}: {', '.join(users)}") 64 | 65 | # Remove a reaction 66 | print("\nRemoving User 1's heart reaction from second message...") 67 | thread.remove_reaction(assistant_msg2.id, ":heart:", "user1") 68 | 69 | # Display reactions after removal 70 | print("\nReactions after removal:") 71 | for msg in thread.messages: 72 | if msg.reactions: 73 | print(f"Message '{msg.content}' has reactions:") 74 | for emoji, users in msg.reactions.items(): 75 | print(f" - {emoji}: {', '.join(users)}") 76 | 77 | # Save thread to database 78 | print("\nSaving thread to database...") 79 | await thread_store.save(thread) 80 | 81 | # Retrieve thread from database 82 | print("Retrieving thread from database...") 83 | retrieved_thread = await thread_store.get(thread.id) 84 | 85 | # Display reactions from retrieved thread 86 | print("\nReactions in retrieved thread:") 87 | for msg in retrieved_thread.messages: 88 | if msg.reactions: 89 | print(f"Message '{msg.content}' has reactions:") 90 | for emoji, users in msg.reactions.items(): 91 | print(f" - {emoji}: {', '.join(users)}") 92 | 93 | print("\nExample completed successfully!") 94 | 95 | 96 | if __name__ == "__main__": 97 | asyncio.run(main()) -------------------------------------------------------------------------------- /examples/agent_delegation.py: -------------------------------------------------------------------------------- 1 | """ 2 | Example script demonstrating agent-to-agent delegation using the parent-child approach. 3 | 4 | This script creates multiple specialized agents and attaches them to 5 | a main coordinator agent which can delegate tasks to them. 6 | """ 7 | import asyncio 8 | import os 9 | from tyler import Agent, Thread, Message 10 | from tyler.utils.agent_runner import agent_runner 11 | from tyler.utils.logging import get_logger 12 | import weave 13 | 14 | # Load environment variables and configure logging first 15 | from dotenv import load_dotenv 16 | load_dotenv() 17 | 18 | logger = get_logger(__name__) 19 | 20 | try: 21 | if os.getenv("WANDB_API_KEY"): 22 | weave.init("tyler") 23 | logger.debug("Weave tracing initialized successfully") 24 | except Exception as e: 25 | logger.warning(f"Failed to initialize weave tracing: {e}. Continuing without weave.") 26 | 27 | async def main(): 28 | # Create specialized agents 29 | research_agent = Agent( 30 | name="Research", # Using simple, unique names 31 | model_name="gpt-4.1", 32 | purpose="To conduct in-depth research on topics and provide comprehensive information.", 33 | tools=["web"] # Give research agent web search tools 34 | ) 35 | 36 | code_agent = Agent( 37 | name="Code", # Using simple, unique names 38 | model_name="gpt-4.1", 39 | purpose="To write, review, and explain code in various programming languages.", 40 | tools=[] # No additional tools needed for coding 41 | ) 42 | 43 | creative_agent = Agent( 44 | name="Creative", # Using simple, unique names 45 | model_name="gpt-4.1", 46 | purpose="To generate creative content such as stories, poems, and marketing copy.", 47 | tools=[] # No additional tools needed for creative writing 48 | ) 49 | 50 | # Create main agent with specialized agents as a list 51 | main_agent = Agent( 52 | name="Coordinator", 53 | model_name="gpt-4.1", 54 | purpose="To coordinate work by delegating tasks to specialized agents when appropriate.", 55 | tools=[], # No additional tools needed since agents will be added as tools 56 | agents=[research_agent, code_agent, creative_agent] # Simple list instead of dictionary 57 | ) 58 | 59 | # Initialize a thread with a complex query that requires delegation 60 | thread = Thread() 61 | 62 | # Add a message that will likely require delegation 63 | thread.add_message(Message( 64 | role="user", 65 | content="""I need help with a few things: 66 | 67 | 1. I need research on the latest advancements in quantum computing 68 | 2. I need a short Python script that can convert CSV to JSON 69 | 3. I need a creative tagline for my tech startup called "QuantumLeap" 70 | 71 | Please help me with these tasks. 72 | """ 73 | )) 74 | 75 | # Print available agents from agent_runner 76 | logger.info(f"Available agents: {agent_runner.list_agents()}") 77 | 78 | # Process with the main agent 79 | result_thread, messages = await main_agent.go(thread) 80 | 81 | # Print the results 82 | print("\n=== FINAL CONVERSATION ===\n") 83 | for message in result_thread.messages: 84 | if message.role == "user": 85 | print(f"\nUser: {message.content}\n") 86 | elif message.role == "assistant": 87 | print(f"\nAssistant: {message.content}\n") 88 | if message.tool_calls: 89 | print(f"[Tool calls: {', '.join([tc['function']['name'] for tc in message.tool_calls])}]") 90 | elif message.role == "tool": 91 | print(f"\nTool ({message.name}): {message.content}\n") 92 | 93 | if __name__ == "__main__": 94 | asyncio.run(main()) -------------------------------------------------------------------------------- /docs/docusaurus.config.js: -------------------------------------------------------------------------------- 1 | // @ts-check 2 | // Note: type annotations allow type checking and IDEs autocompletion 3 | 4 | const {themes} = require('prism-react-renderer'); 5 | 6 | /** @type {import('@docusaurus/types').Config} */ 7 | const config = { 8 | title: 'Tyler Documentation', 9 | tagline: 'A powerful AI Agent powered by LLMs', 10 | favicon: 'img/favicon.ico', 11 | 12 | // Set the production url of your site here 13 | url: 'https://adamwdraper.github.io', 14 | // Set the /
Test Header
20 |Test paragraph
21 |Test div content
22 |
23 |
24 | """
25 |
26 | MOCK_CLEAN_TEXT = """Test Header
27 |
28 | Test paragraph
29 |
30 | Test div content"""
31 |
32 | @pytest.fixture(autouse=True)
33 | def mock_requests():
34 | """Mock all requests to prevent any real API calls"""
35 | with patch('requests.get') as mock_get, patch('requests.head') as mock_head:
36 | mock_response = MagicMock()
37 | mock_response.text = MOCK_HTML_CONTENT
38 | mock_response.headers = {
39 | 'content-type': 'text/html',
40 | 'content-length': '1000'
41 | }
42 | mock_get.return_value = mock_response
43 | mock_head.return_value = mock_response
44 | yield mock_get, mock_head
45 |
46 | @pytest.fixture
47 | def mock_downloads_dir(tmp_path):
48 | """Create a temporary downloads directory"""
49 | downloads = tmp_path / "downloads"
50 | downloads.mkdir()
51 | with patch('tyler.utils.files.user_downloads_dir', return_value=str(downloads)):
52 | yield downloads
53 |
54 | def test_fetch_html_success():
55 | """Test successful HTML fetching"""
56 | html = fetch_html("https://example.com")
57 | assert html == MOCK_HTML_CONTENT
58 |
59 | def test_fetch_html_with_headers():
60 | """Test HTML fetching with custom headers"""
61 | headers = {"User-Agent": "Test Bot"}
62 | with patch('requests.get') as mock_get:
63 | mock_response = MagicMock()
64 | mock_response.text = MOCK_HTML_CONTENT
65 | mock_get.return_value = mock_response
66 |
67 | fetch_html("https://example.com", headers)
68 |
69 | mock_get.assert_called_with(
70 | "https://example.com",
71 | headers=headers,
72 | timeout=30
73 | )
74 |
75 | def test_fetch_html_error():
76 | """Test error handling in fetch_html"""
77 | with patch('requests.get') as mock_get:
78 | mock_get.side_effect = Exception("Connection error")
79 | with pytest.raises(Exception, match="Error fetching URL: Connection error"):
80 | fetch_html("https://example.com")
81 |
82 | def test_extract_text_from_html():
83 | """Test HTML to text extraction"""
84 | text = extract_text_from_html(MOCK_HTML_CONTENT)
85 | assert text == MOCK_CLEAN_TEXT
86 |
87 | def test_fetch_page_text_format():
88 | """Test fetch_page with text format"""
89 | result = fetch_page(url="https://example.com", format="text")
90 | assert result["success"] is True
91 | assert result["status_code"] == 200
92 | assert result["content"] == MOCK_CLEAN_TEXT
93 | assert result["content_type"] == "text"
94 | assert result["error"] is None
95 |
96 | def test_fetch_page_html_format():
97 | """Test fetch_page with HTML format"""
98 | result = fetch_page(url="https://example.com", format="html")
99 | assert result["success"] is True
100 | assert result["status_code"] == 200
101 | assert result["content"] == MOCK_HTML_CONTENT
102 | assert result["content_type"] == "html"
103 | assert result["error"] is None
104 |
105 | def test_fetch_page_error():
106 | """Test fetch_page error handling"""
107 | with patch('requests.get') as mock_get:
108 | mock_get.side_effect = Exception("Test error")
109 | result = fetch_page(url="https://example.com")
110 | assert result["success"] is False
111 | assert result["status_code"] is None
112 | assert result["content"] is None
113 | assert result["content_type"] is None
114 | assert result["error"] == "Error fetching URL: Test error"
115 |
116 | def test_download_file_success(mock_downloads_dir):
117 | """Test successful file download"""
118 | result, files = download_file(url="https://example.com/file.txt")
119 |
120 | assert result["success"] is True
121 | assert result["content_type"] == "text/html"
122 | assert result["file_size"] == 1000
123 | assert result["filename"] == "file.txt"
124 | assert len(files) == 1
125 | assert files[0]["filename"] == "file.txt"
126 | assert files[0]["mime_type"] == "text/html"
127 | assert "content" in files[0]
128 | assert "url" in files[0]["attributes"]
129 |
130 | def test_download_file_with_content_disposition(mock_downloads_dir):
131 | """Test file download with Content-Disposition header"""
132 | with patch('requests.get') as mock_get:
133 | mock_response = MagicMock()
134 | mock_response.headers = {
135 | 'Content-Disposition': 'attachment; filename="server_file.txt"',
136 | 'content-type': 'text/plain',
137 | 'content-length': '1000'
138 | }
139 | mock_response.iter_content.return_value = [b'test content']
140 | mock_get.return_value = mock_response
141 |
142 | result, files = download_file(url="https://example.com/file")
143 |
144 | assert result["success"] is True
145 | assert result["filename"] == "server_file.txt"
146 | assert files[0]["filename"] == "server_file.txt"
147 |
148 | def test_download_file_error():
149 | """Test download_file error handling"""
150 | with patch('requests.get') as mock_get:
151 | mock_get.side_effect = Exception("Download failed")
152 | result, files = download_file(url="https://example.com/file.txt")
153 |
154 | assert result["success"] is False
155 | assert "error" in result
156 | assert result["error"] == "Download failed"
157 | assert len(files) == 0
--------------------------------------------------------------------------------
/docs/static/img/logo.svg:
--------------------------------------------------------------------------------
1 |
--------------------------------------------------------------------------------
/docs/docs/examples/file-storage.md:
--------------------------------------------------------------------------------
1 | # File Storage Example
2 |
3 | This example demonstrates how to use Tyler's file storage capabilities to save and retrieve files.
4 |
5 | ## Configuration
6 |
7 | First, set up the file storage configuration:
8 |
9 | ```python
10 | from tyler.storage import get_file_store, FileStore
11 |
12 | # Get default file store
13 | file_store = get_file_store()
14 |
15 | # Or create with custom configuration
16 | file_store = FileStore(
17 | base_path="/path/to/files",
18 | max_file_size=100 * 1024 * 1024, # 100MB
19 | max_storage_size=10 * 1024 * 1024 * 1024, # 10GB
20 | allowed_mime_types={"application/pdf", "image/jpeg", "text/plain"}
21 | )
22 | ```
23 |
24 | ## Saving Files
25 |
26 | ```python
27 | # Save a file
28 | file_content = b"Hello, World!"
29 | result = await file_store.save("example.txt", file_content)
30 |
31 | print(f"File ID: {result['id']}")
32 | print(f"Storage path: {result['storage_path']}")
33 | print(f"MIME type: {result['mime_type']}")
34 | ```
35 |
36 | ## Retrieving Files
37 |
38 | ```python
39 | # Get file content using ID and storage path
40 | file_id = result['id']
41 | storage_path = result['storage_path']
42 | content = await file_store.get(file_id, storage_path)
43 |
44 | print(f"Content: {content.decode('utf-8')}")
45 | ```
46 |
47 | ## Deleting Files
48 |
49 | ```python
50 | # Delete a file
51 | await file_store.delete(file_id, storage_path)
52 | ```
53 |
54 | ## Working with Attachments
55 |
56 | The FileStore integrates seamlessly with the Attachment model:
57 |
58 | ```python
59 | from tyler import Attachment, Message, Thread, ThreadStore
60 |
61 | # Create an attachment
62 | attachment = Attachment(
63 | filename="document.pdf",
64 | content=pdf_bytes,
65 | mime_type="application/pdf"
66 | )
67 |
68 | # Process and store the attachment directly
69 | await attachment.process_and_store()
70 |
71 | # Check the results
72 | print(f"File ID: {attachment.file_id}")
73 | print(f"Storage path: {attachment.storage_path}")
74 | print(f"Status: {attachment.status}")
75 | print(f"URL: {attachment.attributes.get('url')}")
76 |
77 | # Or use with messages and threads (recommended approach)
78 | message = Message(role="user", content="Here's a document")
79 | message.add_attachment(pdf_bytes, filename="document.pdf")
80 |
81 | thread = Thread()
82 | thread.add_message(message)
83 |
84 | # Create thread store (will initialize automatically when needed)
85 | thread_store = ThreadStore()
86 | await thread_store.save(thread) # Automatically processes and stores attachments
87 |
88 | # Access attachment information
89 | for attachment in message.attachments:
90 | if attachment.status == "stored":
91 | print(f"File ID: {attachment.file_id}")
92 | print(f"Storage path: {attachment.storage_path}")
93 | print(f"URL: {attachment.attributes.get('url')}")
94 |
95 | # Access file-specific attributes
96 | file_type = attachment.attributes.get("type")
97 | if file_type == "document":
98 | print(f"Extracted text: {attachment.attributes.get('text')}")
99 | elif file_type == "image":
100 | print(f"Image description: {attachment.attributes.get('overview')}")
101 | ```
102 |
103 | ## Batch Operations
104 |
105 | ```python
106 | # Save multiple files at once
107 | files = [
108 | (b"File 1 content", "file1.txt", "text/plain"),
109 | (b"File 2 content", "file2.txt", "text/plain")
110 | ]
111 | results = await file_store.batch_save(files)
112 |
113 | # Delete multiple files
114 | file_ids = [result["id"] for result in results]
115 | await file_store.batch_delete(file_ids)
116 | ```
117 |
118 | ## Storage Management
119 |
120 | ```python
121 | # Check storage health
122 | health = await file_store.check_health()
123 | print(f"Status: {health['status']}")
124 | print(f"Storage size: {health['storage_size']} bytes")
125 | print(f"File count: {health['file_count']}")
126 | print(f"Usage: {health['usage_percent']}%")
127 |
128 | # Get storage size
129 | size = await file_store.get_storage_size()
130 | print(f"Total storage size: {size} bytes")
131 |
132 | # Get file count
133 | count = await file_store.get_file_count()
134 | print(f"Total files: {count}")
135 | ```
136 |
137 | ## URL Generation
138 |
139 | ```python
140 | # Generate URL for a file
141 | from tyler.storage import FileStore
142 |
143 | storage_path = "ab/cdef1234.pdf" # Example storage path
144 | url = FileStore.get_file_url(storage_path)
145 | print(f"File URL: {url}")
146 | ```
147 |
148 | ## Error Handling
149 |
150 | ```python
151 | from tyler.storage import (
152 | FileStoreError,
153 | FileNotFoundError,
154 | StorageFullError,
155 | UnsupportedFileTypeError,
156 | FileTooLargeError
157 | )
158 |
159 | try:
160 | # Try to save a file
161 | result = await file_store.save(large_content, "large_file.bin")
162 | except UnsupportedFileTypeError:
163 | print("File type not allowed")
164 | except FileTooLargeError:
165 | print("File too large")
166 | except StorageFullError:
167 | print("Storage full")
168 | except FileStoreError as e:
169 | print(f"General storage error: {e}")
170 | ```
171 |
172 | ## Complete Example
173 |
174 | ```python
175 | import asyncio
176 | from tyler.storage import get_file_store
177 |
178 | async def main():
179 | # Initialize file store
180 | file_store = get_file_store()
181 |
182 | # Save a file
183 | content = b"Hello, World!"
184 | result = await file_store.save(content, "example.txt")
185 | print(f"Saved file: {result['filename']}")
186 | print(f"Storage path: {result['storage_path']}")
187 |
188 | # Retrieve the file
189 | retrieved = await file_store.get(result['id'], result['storage_path'])
190 | print(f"Retrieved content: {retrieved.decode('utf-8')}")
191 |
192 | # Delete the file
193 | await file_store.delete(result['id'], result['storage_path'])
194 | print("File deleted")
195 |
196 | # Check storage health
197 | health = await file_store.check_health()
198 | print(f"Storage health: {health['status']}")
199 | print(f"Storage usage: {health['usage_percent']}%")
200 |
201 | if __name__ == "__main__":
202 | asyncio.run(main())
203 | ```
--------------------------------------------------------------------------------