diff --git a/agents-api/agents_api/activities/utils.py b/agents-api/agents_api/activities/utils.py index a6746bbe5..5923ec3cb 100644 --- a/agents-api/agents_api/activities/utils.py +++ b/agents-api/agents_api/activities/utils.py @@ -305,7 +305,6 @@ def get_handler(system: SystemDef) -> Callable: from ..models.docs.list_docs import list_docs as list_docs_query from ..models.entry.get_history import get_history as get_history_query from ..models.session.create_session import create_session as create_session_query - from ..models.session.delete_session import delete_session as delete_session_query from ..models.session.get_session import get_session as get_session_query from ..models.session.list_sessions import list_sessions as list_sessions_query from ..models.session.update_session import update_session as update_session_query diff --git a/agents-api/agents_api/metrics/counters.py b/agents-api/agents_api/metrics/counters.py index c5455248b..d9707ea56 100644 --- a/agents-api/agents_api/metrics/counters.py +++ b/agents-api/agents_api/metrics/counters.py @@ -34,17 +34,17 @@ INF, ) counter = Counter( - f"db_query_counter", - f"Number of db calls", + "db_query_counter", + "Number of db calls", labelnames=labelnames, ) summary = Summary( - f"db_query_latency_summary", + "db_query_latency_summary", "Database query latency summary", labelnames=labelnames, ) hist = Histogram( - f"db_query_latency_hist", + "db_query_latency_hist", "Database query latency histogram", labelnames=labelnames, buckets=buckets, diff --git a/agents-api/agents_api/routers/healthz/check_health.py b/agents-api/agents_api/routers/healthz/check_health.py index 74e9f5c6c..5a466ba39 100644 --- a/agents-api/agents_api/routers/healthz/check_health.py +++ b/agents-api/agents_api/routers/healthz/check_health.py @@ -1,7 +1,6 @@ import logging from uuid import UUID -from ...autogen.openapi_model import Agent, ListResponse from ...models.agent.list_agents import list_agents as list_agents_query from .router import router @@ -10,7 +9,7 @@ async def check_health() -> dict: try: # Check if the database is reachable - agents = list_agents_query( + list_agents_query( developer_id=UUID("00000000-0000-0000-0000-000000000000"), ) except Exception as e: diff --git a/documentation/README.md b/documentation/README.md new file mode 100644 index 000000000..fa97a7aa3 --- /dev/null +++ b/documentation/README.md @@ -0,0 +1,20 @@ +# Julep Mintlify Documentation + +## Development + +Install the [Mintlify CLI](https://www.npmjs.com/package/mintlify) to preview the documentation changes locally. To install, use the following command + +``` +npm i -g mintlify +``` + +Run the following command at the root of your documentation (where mint.json is) + +``` +mintlify dev +``` + +### Troubleshooting + +- Mintlify dev isn't running - Run `mintlify install` it'll re-install dependencies. +- Page loads as a 404 - Make sure you are running in a folder with `mint.json` diff --git a/documentation/api-reference/introduction.mdx b/documentation/api-reference/introduction.mdx new file mode 100644 index 000000000..377e76f17 --- /dev/null +++ b/documentation/api-reference/introduction.mdx @@ -0,0 +1,51 @@ +--- +title: Introduction +description: 'Introduction to the Julep REST API' +--- + + + + Create, update, and manage AI agents + + + Create and execute AI tasks and workflows + + + Manage conversation sessions and state + + + Register and manage agent tools + + + +## Authentication + + + Authentication is done via API keys. + + +API keys are used to authenticate requests to the Julep API. They can be created in the [Julep dashboard](https://dashboard.julep.ai). + +To create an API key, go to the Julep dashboard and navigate to the "API Keys" section. + +To use an API key, include it in the `Authorization` header of your request. + +``` +Authorization: Bearer YOUR_API_KEY +``` diff --git a/documentation/building-blocks/agents/agent-memory.mdx b/documentation/building-blocks/agents/agent-memory.mdx new file mode 100644 index 000000000..d40e71d38 --- /dev/null +++ b/documentation/building-blocks/agents/agent-memory.mdx @@ -0,0 +1,195 @@ +--- +title: 'Agent Memory' +description: 'Understanding how agents maintain state and context across interactions' +--- + +## Overview + +Agent memory in Julep allows AI agents to maintain state and context across multiple interactions. This enables more coherent and contextually aware conversations and task executions. + +## Types of Memory + +Julep provides several types of memory for agents: + +### 1. Session Memory + +Session memory persists throughout a single conversation session: + +```python Python +# Create a session with memory +session = client.sessions.create( + agent_id=agent.id, + user_id=user.id, + context_overflow="adaptive" # Memory management strategy +) +``` + +### 2. Long-term Memory + +Long-term memory persists across sessions and is stored in the agent's document store: + +```python Python +# Store information in long-term memory +document = client.agents.docs.create( + agent_id=agent.id, + title="User Preferences", + content="User prefers dark mode and concise responses", + metadata={"type": "preferences"} +) +``` + +### 3. Working Memory + +Working memory is available during task execution: + +```yaml +main: + - evaluate: + remembered_value: "some_value" + + - prompt: + - role: user + content: "Use the remembered value: {{_.remembered_value}}" +``` + +## Memory Management + +### Context Window Management + +Julep offers different strategies for managing context windows: + +1. **Fixed**: Maintains a fixed number of messages +2. **Adaptive**: Dynamically adjusts based on token usage +3. **Summary**: Periodically summarizes older context + +```python Python +session = client.sessions.create( + agent_id=agent.id, + context_overflow="adaptive", + max_messages=50 # Optional: limit number of messages +) +``` + +### Document Store + +The document store serves as long-term memory: + +```python Python +# Store a document +doc = client.agents.docs.create( + agent_id=agent.id, + title="Meeting Notes", + content="Important points from the meeting...", + metadata={"date": "2024-03-24"} +) + +# Search stored documents +results = client.agents.docs.search( + agent_id=agent.id, + text="meeting points", + metadata_filter={"date": "2024-03-24"} +) +``` + +## Memory Access in Tasks + +Tasks can access different types of memory: + +```yaml +main: + # Access session context + - prompt: + - role: system + content: "Previous context: {{session.context}}" + + # Search long-term memory + - tool: search_documents + arguments: + query: "user preferences" + + # Use working memory + - evaluate: + stored_value: "important_data" + - prompt: + - role: user + content: "Use the stored value: {{_.stored_value}}" +``` + +## Best Practices + +1. **Memory Organization** + - Use clear document titles and metadata + - Organize documents by type and purpose + - Regularly clean up outdated information + +2. **Context Management** + - Choose appropriate context overflow strategies + - Monitor token usage in sessions + - Use summaries for long conversations + +3. **Memory Usage** + - Store important information in long-term memory + - Use working memory for temporary data + - Leverage session memory for conversation context + +## Example: Complex Memory Usage + +Here's an example combining different types of memory: + +```python Python +# Create a session with memory management +session = client.sessions.create( + agent_id=agent.id, + user_id=user.id, + context_overflow="adaptive", + metadata={ + "preferences": { + "language": "en", + "style": "formal" + } + } +) + +# Store long-term information +client.agents.docs.create( + agent_id=agent.id, + title="User Profile", + content="Detailed user preferences and history...", + metadata={ + "type": "profile", + "last_updated": "2024-03-24" + } +) + +# Create a task that uses multiple memory types +task = client.tasks.create( + agent_id=agent.id, + yaml=""" + main: + # Access session context + - prompt: + - role: system + content: "Session context: {{session.context}}" + + # Search long-term memory + - tool: search_documents + arguments: + query: "user profile" + + # Store in working memory + - evaluate: + profile_data: _.documents[0].content + + # Use the combined information + - prompt: + - role: user + content: "Use profile data: {{_.profile_data}}" + """ +) +``` + +## Next Steps + +1. [Learn about agent tools](/building-blocks/agents/agent-tools) +2. [Understand task basics](/building-blocks/tasks/task-basics) +3. [Explore session management](/building-blocks/sessions/session-management) \ No newline at end of file diff --git a/documentation/building-blocks/agents/agent-tools.mdx b/documentation/building-blocks/agents/agent-tools.mdx new file mode 100644 index 000000000..98459b1e6 --- /dev/null +++ b/documentation/building-blocks/agents/agent-tools.mdx @@ -0,0 +1,291 @@ +--- +title: 'Agent Tools' +description: 'Adding and managing tools for Julep agents' +--- + +## Overview + +Tools in Julep extend an agent's capabilities by allowing them to interact with external services, perform computations, and access various APIs. This guide covers how to add and manage tools for your agents. + +## Tool Types + +Julep supports four types of tools: + +### 1. User-defined Functions + +Custom functions that you implement and handle on the client side: + +```python Python +# Define a tool +tool = client.agents.tools.create( + agent_id=agent.id, + name="calculate_total", + description="Calculate the total of a list of numbers", + function={ + "parameters": { + "type": "object", + "properties": { + "numbers": { + "type": "array", + "items": {"type": "number"} + } + } + } + } +) +``` + +### 2. System Tools + +Built-in tools for interacting with Julep's core functionality: + +```python Python +# Add a system tool +tool = client.agents.tools.create( + agent_id=agent.id, + name="list_documents", + description="List all documents for this agent", + system={ + "resource": "agent", + "subresource": "doc", + "operation": "list" + } +) +``` + +### 3. Integrations + +Pre-built integrations with third-party services: + +```python Python +# Add an integration +tool = client.agents.tools.create( + agent_id=agent.id, + name="search_web", + description="Search the web using Brave Search", + integration={ + "provider": "brave", + "method": "search", + "setup": { + "api_key": "your_brave_api_key" + } + } +) +``` + +### 4. API Calls + +Direct API calls to external services: + +```python Python +# Add an API call tool +tool = client.agents.tools.create( + agent_id=agent.id, + name="weather_api", + description="Get weather information", + api_call={ + "method": "GET", + "url": "https://api.weather.com/v1/current", + "headers": { + "Authorization": "Bearer {{agent.metadata.weather_api_key}}" + } + } +) +``` + +## Using Tools in Tasks + +Tools can be used in task workflows: + +```yaml +tools: + - name: web_search + integration: + provider: brave + method: search + + - name: summarize + function: + parameters: + type: object + properties: + text: + type: string + +main: + # Use the web search tool + - tool: web_search + arguments: + query: "Latest AI developments" + + # Use the results in a function + - tool: summarize + arguments: + text: _.search_results +``` + +## Available Integrations + +Julep provides several built-in integrations: + +1. **Web Search** + - Brave Search + - Wikipedia + +2. **Document Processing** + - Llama Parse + - BrowserBase + +3. **Media Processing** + - Cloudinary + - FFmpeg + +4. **Research** + - Arxiv + - Academic databases + +5. **Communication** + - Email + - Discord + +## Tool Management + +### Adding Tools + +```python Python +# Add a single tool +tool = client.agents.tools.create( + agent_id=agent.id, + name="tool_name", + description="Tool description", + integration={ + "provider": "provider_name", + "method": "method_name" + } +) + +# Add multiple tools +tools = client.agents.tools.create_many( + agent_id=agent.id, + tools=[ + { + "name": "tool1", + "description": "First tool", + "integration": {...} + }, + { + "name": "tool2", + "description": "Second tool", + "function": {...} + } + ] +) +``` + +### Listing Tools + +```python Python +# List all tools for an agent +tools = client.agents.tools.list(agent_id=agent.id) + +# Get a specific tool +tool = client.agents.tools.get( + agent_id=agent.id, + tool_id="tool_id" +) +``` + +### Updating Tools + +```python Python +# Update a tool +tool = client.agents.tools.update( + agent_id=agent.id, + tool_id="tool_id", + description="Updated description" +) +``` + +### Removing Tools + +```python Python +# Remove a tool +client.agents.tools.delete( + agent_id=agent.id, + tool_id="tool_id" +) +``` + +## Best Practices + +1. **Tool Design** + - Keep tool functions focused and single-purpose + - Provide clear descriptions of tool functionality + - Use appropriate parameter types and validation + +2. **Security** + - Store API keys in metadata or environment variables + - Implement proper error handling + - Validate tool inputs and outputs + +3. **Performance** + - Use appropriate timeouts for API calls + - Cache results when possible + - Handle rate limits properly + +## Example: Complex Tool Setup + +Here's an example setting up multiple tools for a research assistant agent: + +```python Python +# Create the agent +agent = client.agents.create( + name="Research Assistant", + model="claude-3.5-sonnet", + about="An AI assistant for academic research", + metadata={ + "arxiv_max_results": 10, + "brave_api_key": "your_brave_api_key" + } +) + +# Add research tools +tools = client.agents.tools.create_many( + agent_id=agent.id, + tools=[ + { + "name": "search_papers", + "description": "Search academic papers on arXiv", + "integration": { + "provider": "arxiv", + "method": "search" + } + }, + { + "name": "web_search", + "description": "Search the web for additional information", + "integration": { + "provider": "brave", + "method": "search", + "setup": { + "api_key": "{{agent.metadata.brave_api_key}}" + } + } + }, + { + "name": "parse_pdf", + "description": "Parse PDF documents", + "integration": { + "provider": "llama_parse", + "method": "parse" + } + } + ] +) +``` + +## Next Steps + +1. [Understand task basics](/building-blocks/tasks/task-basics) +2. [Learn about workflow steps](/building-blocks/tasks/workflow-steps) +3. [Explore available integrations](/tools/available-integrations) \ No newline at end of file diff --git a/documentation/building-blocks/agents/creating-agents.mdx b/documentation/building-blocks/agents/creating-agents.mdx new file mode 100644 index 000000000..311bf16f1 --- /dev/null +++ b/documentation/building-blocks/agents/creating-agents.mdx @@ -0,0 +1,127 @@ +--- +title: 'Creating Agents' +description: 'Guide to creating and configuring AI agents in Julep' +--- + +## Overview + +Agents in Julep are AI-powered entities that can execute tasks and interact with users. This guide will walk you through the process of creating and configuring agents. + +## Creating an Agent + +You can create an agent using either the Python or Node.js SDK: + +```python Python +from julep import Julep + +client = Julep(api_key="your_api_key") + +agent = client.agents.create( + name="My Agent", + model="claude-3.5-sonnet", + about="A helpful AI assistant that specializes in data analysis" +) +``` + +```javascript JavaScript +import { Julep } from '@julep/sdk'; + +const client = new Julep({ apiKey: 'your_api_key' }); + +const agent = await client.agents.create({ + name: "My Agent", + model: "claude-3.5-sonnet", + about: "A helpful AI assistant that specializes in data analysis" +}); +``` + +## Agent Configuration Options + +When creating an agent, you can specify several configuration options: + +| Option | Type | Description | +|--------|------|-------------| +| `name` | string | The name of your agent | +| `model` | string | The language model to use (e.g., "claude-3.5-sonnet", "gpt-4") | +| `about` | string | A description of your agent's purpose and capabilities | +| `metadata` | object | Additional metadata for your agent | +| `tools` | array | List of tools the agent can use | + +## Supported Models + +Julep supports various language models: + +- Anthropic Models + - claude-3.5-sonnet + - claude-3.5-opus + - claude-2.1 + - claude-2.0 + +- OpenAI Models + - gpt-4 + - gpt-4-turbo + - gpt-3.5-turbo + +## Best Practices + +1. **Clear Purpose**: Give your agent a clear, specific purpose through the `about` field +2. **Appropriate Model**: Choose a model that matches your needs in terms of capability and cost +3. **Descriptive Name**: Use a name that reflects the agent's purpose +4. **Metadata**: Use metadata to store configuration that might need to change + +## Example: Creating a Specialized Agent + +Here's an example of creating a more specialized agent with metadata and tools: + +```python Python +agent = client.agents.create( + name="Research Assistant", + model="claude-3.5-sonnet", + about="An AI assistant specialized in academic research and paper analysis", + metadata={ + "expertise": ["academic research", "paper analysis"], + "language": "en", + "max_papers_per_session": 5 + } +) + +# Add tools to the agent +client.agents.tools.create( + agent_id=agent.id, + name="arxiv_search", + description="Search for academic papers on arXiv", + integration={ + "provider": "arxiv", + "method": "search" + } +) +``` + +## Managing Agents + +Once created, you can manage your agents: + +```python Python +# List all agents +agents = client.agents.list() + +# Get a specific agent +agent = client.agents.get(agent_id="agent_id") + +# Update an agent +agent = client.agents.update( + agent_id="agent_id", + metadata={"new_config": "value"} +) + +# Delete an agent +client.agents.delete(agent_id="agent_id") +``` + +## Next Steps + +After creating your agent, you might want to: + +1. [Add tools to your agent](/building-blocks/agents/agent-tools) +2. [Configure agent memory](/building-blocks/agents/agent-memory) +3. [Create tasks for your agent](/building-blocks/tasks/task-basics) \ No newline at end of file diff --git a/documentation/building-blocks/doc-store/document-integration.mdx b/documentation/building-blocks/doc-store/document-integration.mdx new file mode 100644 index 000000000..bd8770b28 --- /dev/null +++ b/documentation/building-blocks/doc-store/document-integration.mdx @@ -0,0 +1,438 @@ +--- +title: 'Document Integration' +description: 'Using documents within tasks and agent workflows in Julep' +--- + +## Overview + +Document integration in Julep allows you to seamlessly incorporate document store capabilities into your tasks and agent workflows. This guide covers how to effectively use documents in your applications. + +## Using Documents in Tasks + +### Document Access + +Access documents within task workflows: + +```yaml +tools: + - name: search_docs + system: + resource: agent + subresource: doc + operation: search + +main: + # Search for relevant documents + - tool: search_docs + arguments: + text: "{{inputs.query}}" + metadata_filter: + type: "documentation" + + # Use search results in prompt + - prompt: + - role: system + content: "Use these documents to answer: {{_.documents}}" + - role: user + content: "{{inputs.query}}" +``` + +### Document Creation + +Create documents from task results: + +```yaml +tools: + - name: create_doc + system: + resource: agent + subresource: doc + operation: create + +main: + # Generate content + - prompt: + - role: user + content: "Generate documentation for {{inputs.topic}}" + + # Save as document + - tool: create_doc + arguments: + title: "Documentation: {{inputs.topic}}" + content: _ + metadata: + type: "documentation" + topic: "{{inputs.topic}}" + generated_at: "datetime.now().isoformat()" +``` + +## Document Processing Workflows + +### Content Generation + +Generate and store documentation: + +```python Python +# Create a documentation generator task +task = client.tasks.create( + agent_id=agent.id, + yaml=""" + name: Documentation Generator + description: Generate and store documentation + + tools: + - name: create_doc + system: + resource: agent + subresource: doc + operation: create + + - name: search_docs + system: + resource: agent + subresource: doc + operation: search + + main: + # Check existing documentation + - tool: search_docs + arguments: + text: "{{inputs.topic}}" + metadata_filter: + type: "documentation" + + # Generate if not exists + - if: "len(_.documents) == 0" + then: + - prompt: + - role: system + content: "Generate comprehensive documentation for {{inputs.topic}}" + + - tool: create_doc + arguments: + title: "{{inputs.topic}} Documentation" + content: _ + metadata: + type: "documentation" + topic: "{{inputs.topic}}" + status: "draft" + else: + - return: + message: "Documentation already exists" + documents: _.documents + """ +) +``` + +### Document Updates + +Update documents based on new information: + +```python Python +# Create a document updater task +task = client.tasks.create( + agent_id=agent.id, + yaml=""" + name: Document Updater + description: Update existing documentation + + tools: + - name: search_docs + system: + resource: agent + subresource: doc + operation: search + + - name: update_doc + system: + resource: agent + subresource: doc + operation: update + + main: + # Find document to update + - tool: search_docs + arguments: + text: "{{inputs.topic}}" + metadata_filter: + type: "documentation" + status: "published" + + # Update content + - if: "len(_.documents) > 0" + then: + - prompt: + - role: system + content: > + Update this documentation with new information: + {{_.documents[0].content}} + - role: user + content: "{{inputs.updates}}" + + - tool: update_doc + arguments: + document_id: "{{_.documents[0].id}}" + content: _ + metadata: + last_updated: "datetime.now().isoformat()" + update_type: "{{inputs.update_type}}" + else: + - error: "Document not found" + """ +) +``` + +## Integration Patterns + +### Document-Based Responses + +Use documents to enhance responses: + +```yaml +main: + # Search relevant documents + - tool: search_docs + arguments: + text: "{{inputs.query}}" + metadata_filter: + status: "published" + + # Generate response + - prompt: + - role: system + content: > + You are a helpful assistant with access to the following documents: + {{_.documents}} + + Use this information to provide accurate answers. + - role: user + content: "{{inputs.query}}" + + # Save response + - tool: create_doc + arguments: + title: "Response: {{inputs.query}}" + content: _ + metadata: + type: "response" + query: "{{inputs.query}}" + sources: "{{[doc.id for doc in _.documents]}}" +``` + +### Document Chains + +Chain document operations: + +```yaml +main: + # Initial search + - tool: search_docs + arguments: + text: "{{inputs.topic}}" + + # Process each document + - foreach: + in: _.documents + do: + # Analyze document + - prompt: + - role: system + content: "Analyze this document: {{_}}" + + # Create analysis document + - tool: create_doc + arguments: + title: "Analysis: {{_.title}}" + content: _ + metadata: + type: "analysis" + source_doc: "{{_.id}}" + + # Summarize analyses + - tool: search_docs + arguments: + metadata_filter: + type: "analysis" + source_doc: {"$in": "{{[doc.id for doc in _.documents]}}"} + + # Create summary document + - prompt: + - role: system + content: "Summarize these analyses: {{_.documents}}" + + - tool: create_doc + arguments: + title: "Summary: {{inputs.topic}}" + content: _ + metadata: + type: "summary" + topic: "{{inputs.topic}}" +``` + +## Best Practices + +1. **Document Integration** + - Use appropriate document types + - Maintain document relationships + - Track document sources + +2. **Workflow Design** + - Chain operations efficiently + - Handle missing documents + - Validate document content + +3. **Performance** + - Cache frequently used documents + - Use batch operations + - Implement proper error handling + +## Example: Complex Document Integration + +Here's an example of a comprehensive document integration: + +```python Python +class DocumentWorkflow: + def __init__(self, client, agent_id): + self.client = client + self.agent_id = agent_id + + async def process_topic(self, topic): + # Create processing task + task = await self.client.tasks.create( + agent_id=self.agent_id, + yaml=""" + name: Document Processor + description: Process and analyze topic documents + + tools: + - name: search_docs + system: + resource: agent + subresource: doc + operation: search + + - name: create_doc + system: + resource: agent + subresource: doc + operation: create + + - name: update_doc + system: + resource: agent + subresource: doc + operation: update + + main: + # Initial research + - parallel: + - tool: search_docs + arguments: + text: "{{inputs.topic}}" + metadata_filter: + type: "primary" + + - tool: search_docs + arguments: + text: "{{inputs.topic}} analysis" + metadata_filter: + type: "analysis" + + # Process results + - evaluate: + primary_docs: _[0] + analysis_docs: _[1] + + # Generate new content if needed + - if: "len(_.primary_docs) == 0" + then: + - prompt: + - role: system + content: "Generate primary content for {{inputs.topic}}" + + - tool: create_doc + arguments: + title: "{{inputs.topic}}" + content: _ + metadata: + type: "primary" + topic: "{{inputs.topic}}" + status: "draft" + + - evaluate: + primary_docs: [_] + + # Analyze documents + - foreach: + in: _.primary_docs + do: + - prompt: + - role: system + content: "Analyze this document: {{_}}" + + - tool: create_doc + arguments: + title: "Analysis: {{_.title}}" + content: _ + metadata: + type: "analysis" + source_doc: "{{_.id}}" + topic: "{{inputs.topic}}" + + # Generate summary + - tool: search_docs + arguments: + metadata_filter: + type: "analysis" + topic: "{{inputs.topic}}" + + - prompt: + - role: system + content: "Create a summary from these analyses: {{_.documents}}" + + - tool: create_doc + arguments: + title: "Summary: {{inputs.topic}}" + content: _ + metadata: + type: "summary" + topic: "{{inputs.topic}}" + source_analyses: "{{[doc.id for doc in _.documents]}}" + + # Return results + - return: + primary_docs: "{{_.primary_docs}}" + analyses: "{{_.documents}}" + summary: _ + """ + ) + + # Execute task + execution = await self.client.executions.create( + task_id=task.id, + input={"topic": topic} + ) + + # Monitor execution + while True: + result = await self.client.executions.get(execution.id) + if result.status == "succeeded": + return result.output + elif result.status == "failed": + raise Exception(f"Task failed: {result.error}") + await asyncio.sleep(1) + +# Use the workflow +workflow = DocumentWorkflow(client, agent.id) +result = await workflow.process_topic("AI Security") + +print("Primary Documents:", result["primary_docs"]) +print("Analyses:", result["analyses"]) +print("Summary:", result["summary"]) +``` + +## Next Steps + +1. [Learn about document management](/building-blocks/doc-store/document-management) +2. [Explore vector search](/building-blocks/doc-store/vector-search) +3. [Understand task basics](/building-blocks/tasks/task-basics) \ No newline at end of file diff --git a/documentation/building-blocks/doc-store/document-management.mdx b/documentation/building-blocks/doc-store/document-management.mdx new file mode 100644 index 000000000..66317d89e --- /dev/null +++ b/documentation/building-blocks/doc-store/document-management.mdx @@ -0,0 +1,338 @@ +--- +title: 'Document Management' +description: 'Adding, updating, and managing documents in Julep' +--- + +## Overview + +The Julep Document Store allows you to store, manage, and retrieve documents that can be used by agents and tasks. This guide covers how to effectively manage documents in your Julep applications. + +## Creating Documents + +Add documents to the store using the SDK: + +```python Python +# Create a simple document +document = client.agents.docs.create( + agent_id=agent.id, + title="Product Manual", + content="Detailed product instructions...", + metadata={ + "type": "manual", + "version": "1.0" + } +) + +# Create document with chunks +document = client.agents.docs.create( + agent_id=agent.id, + title="Research Paper", + content="Research paper content...", + chunks=True, # Automatically split into chunks + metadata={ + "type": "research", + "author": "John Doe", + "date": "2024-03-24" + } +) +``` + +```javascript JavaScript +// Create a simple document +const document = await client.agents.docs.create({ + agentId: agent.id, + title: "Product Manual", + content: "Detailed product instructions...", + metadata: { + type: "manual", + version: "1.0" + } +}); + +// Create document with chunks +const document = await client.agents.docs.create({ + agentId: agent.id, + title: "Research Paper", + content: "Research paper content...", + chunks: true, // Automatically split into chunks + metadata: { + type: "research", + author: "John Doe", + date: "2024-03-24" + } +}); +``` + +## Document Types + +Julep supports various document types: + +1. **Text Documents** + - Plain text + - Markdown + - HTML + +2. **Structured Documents** + - JSON + - YAML + - XML + +3. **Binary Documents** + - PDF (with automatic text extraction) + - Word documents + - Images (with OCR capabilities) + +## Document Management + +### Listing Documents + +```python Python +# List all documents +documents = client.agents.docs.list(agent_id=agent.id) + +# List with filters +documents = client.agents.docs.list( + agent_id=agent.id, + metadata_filter={ + "type": "manual", + "version": "1.0" + } +) +``` + +### Updating Documents + +```python Python +# Update document content +document = client.agents.docs.update( + agent_id=agent.id, + document_id=document.id, + content="Updated content..." +) + +# Update metadata +document = client.agents.docs.update( + agent_id=agent.id, + document_id=document.id, + metadata={ + "version": "1.1", + "last_updated": "2024-03-24" + } +) +``` + +### Deleting Documents + +```python Python +# Delete a single document +client.agents.docs.delete( + agent_id=agent.id, + document_id=document.id +) + +# Delete multiple documents +client.agents.docs.delete_many( + agent_id=agent.id, + document_ids=[doc1.id, doc2.id] +) +``` + +## Document Processing + +### Chunking + +Control how documents are split into chunks: + +```python Python +# Custom chunking configuration +document = client.agents.docs.create( + agent_id=agent.id, + title="Long Document", + content="Very long content...", + chunks=True, + chunk_config={ + "size": 1000, # Characters per chunk + "overlap": 100, # Overlap between chunks + "split_method": "sentence" # Split at sentence boundaries + } +) +``` + +### Metadata Management + +Add and update document metadata: + +```python Python +# Add rich metadata +document = client.agents.docs.create( + agent_id=agent.id, + title="Technical Specification", + content="Technical details...", + metadata={ + "type": "specification", + "project": "Project X", + "version": "2.0", + "tags": ["technical", "specification"], + "authors": ["John Doe", "Jane Smith"], + "created_at": "2024-03-24T12:00:00Z", + "status": "draft" + } +) + +# Update specific metadata fields +document = client.agents.docs.update_metadata( + agent_id=agent.id, + document_id=document.id, + metadata={ + "status": "published", + "published_at": "2024-03-24T15:00:00Z" + } +) +``` + +## Document Access Control + +### Scoping Documents + +Control document access: + +```python Python +# Create agent-specific document +document = client.agents.docs.create( + agent_id=agent.id, + title="Agent Guidelines", + content="Guidelines content...", + scope="agent" +) + +# Create user-specific document +document = client.users.docs.create( + user_id=user.id, + title="User Preferences", + content="User preferences...", + scope="user" +) +``` + +### Access Patterns + +Configure document access patterns: + +```python Python +# Create document with access patterns +document = client.agents.docs.create( + agent_id=agent.id, + title="Shared Document", + content="Shared content...", + access_patterns={ + "read": ["agent:*", "user:*"], + "write": ["agent:owner"], + "delete": ["agent:owner"] + } +) +``` + +## Best Practices + +1. **Document Organization** + - Use clear, descriptive titles + - Add comprehensive metadata + - Organize documents by type and purpose + +2. **Content Management** + - Keep documents focused and single-purpose + - Update content atomically + - Maintain version history in metadata + +3. **Performance** + - Use appropriate chunk sizes + - Index important metadata fields + - Clean up unused documents + +## Example: Complex Document Management + +Here's an example of advanced document management: + +```python Python +# Create a document processor +def process_document(title, content, doc_type, metadata=None): + base_metadata = { + "type": doc_type, + "created_at": datetime.now().isoformat(), + "status": "processing" + } + + if metadata: + base_metadata.update(metadata) + + # Create initial document + document = client.agents.docs.create( + agent_id=agent.id, + title=title, + content=content, + chunks=True, + chunk_config={ + "size": 1000, + "overlap": 100, + "split_method": "sentence" + }, + metadata=base_metadata + ) + + try: + # Process document content + processed_content = process_content(content) + + # Extract additional metadata + extracted_metadata = extract_metadata(processed_content) + + # Update document with processed content and metadata + document = client.agents.docs.update( + agent_id=agent.id, + document_id=document.id, + content=processed_content, + metadata={ + **base_metadata, + **extracted_metadata, + "status": "processed", + "processed_at": datetime.now().isoformat() + } + ) + + return document + + except Exception as e: + # Update document status on error + client.agents.docs.update_metadata( + agent_id=agent.id, + document_id=document.id, + metadata={ + "status": "error", + "error": str(e) + } + ) + raise + +# Use the document processor +try: + document = process_document( + title="Technical Report", + content="Technical report content...", + doc_type="report", + metadata={ + "project": "Project Y", + "author": "John Doe" + } + ) + + print(f"Document processed: {document.id}") + +except Exception as e: + print(f"Error processing document: {e}") +``` + +## Next Steps + +1. [Learn about vector search](/building-blocks/doc-store/vector-search) +2. [Explore document integration](/building-blocks/doc-store/document-integration) +3. [Understand agent memory](/building-blocks/agents/agent-memory) \ No newline at end of file diff --git a/documentation/building-blocks/doc-store/vector-search.mdx b/documentation/building-blocks/doc-store/vector-search.mdx new file mode 100644 index 000000000..3454aac19 --- /dev/null +++ b/documentation/building-blocks/doc-store/vector-search.mdx @@ -0,0 +1,390 @@ +--- +title: 'Vector Search' +description: 'How to perform semantic search across documents in Julep' +--- + +## Overview + +Vector search in Julep enables semantic search capabilities across your document store. This allows you to find relevant documents based on meaning rather than just keyword matches. This guide covers how to effectively use vector search in your applications. + +## Basic Search + +Perform simple semantic searches: + +```python Python +# Basic semantic search +results = client.agents.docs.search( + agent_id=agent.id, + text="How to configure SSL certificates" +) + +# Search with limit +results = client.agents.docs.search( + agent_id=agent.id, + text="deployment best practices", + limit=5 +) +``` + +```javascript JavaScript +// Basic semantic search +const results = await client.agents.docs.search({ + agentId: agent.id, + text: "How to configure SSL certificates" +}); + +// Search with limit +const results = await client.agents.docs.search({ + agentId: agent.id, + text: "deployment best practices", + limit: 5 +}); +``` + +## Advanced Search Options + +### Metadata Filtering + +Combine semantic search with metadata filters: + +```python Python +# Search with metadata filters +results = client.agents.docs.search( + agent_id=agent.id, + text="error handling", + metadata_filter={ + "type": "documentation", + "version": "2.0", + "status": "published" + } +) + +# Complex metadata filters +results = client.agents.docs.search( + agent_id=agent.id, + text="security configuration", + metadata_filter={ + "type": {"$in": ["guide", "tutorial"]}, + "tags": {"$contains": "security"}, + "published_at": {"$gt": "2024-01-01"} + } +) +``` + +### Search Configuration + +Customize search behavior: + +```python Python +# Configure search parameters +results = client.agents.docs.search( + agent_id=agent.id, + text="API authentication", + config={ + "similarity_threshold": 0.8, # Minimum similarity score + "rerank": True, # Enable reranking + "model": "multilingual", # Use multilingual model + "chunk_level": True # Search at chunk level + } +) +``` + +## Hybrid Search + +Combine semantic and keyword search: + +```python Python +# Hybrid search +results = client.agents.docs.hybrid_search( + agent_id=agent.id, + text="python error handling", + keywords=["try", "except", "finally"], + weights={ + "semantic": 0.7, + "keyword": 0.3 + } +) +``` + +## Search Contexts + +### Scoped Search + +Search within specific contexts: + +```python Python +# Search agent documents +agent_results = client.agents.docs.search( + agent_id=agent.id, + text="configuration options" +) + +# Search user documents +user_results = client.users.docs.search( + user_id=user.id, + text="preferences" +) + +# Search shared documents +shared_results = client.docs.search( + text="common guidelines", + scope="shared" +) +``` + +### Cross-Context Search + +Search across multiple contexts: + +```python Python +# Search across contexts +results = client.docs.search( + text="security protocols", + contexts=[ + {"type": "agent", "id": agent.id}, + {"type": "user", "id": user.id}, + {"type": "shared"} + ] +) +``` + +## Search Processing + +### Result Processing + +Process and format search results: + +```python Python +# Get search results with content +results = client.agents.docs.search( + agent_id=agent.id, + text="deployment steps", + include_content=True +) + +# Process results +for result in results: + print(f"Document: {result.title}") + print(f"Similarity: {result.similarity}") + print(f"Content: {result.content}") + print(f"Metadata: {result.metadata}") +``` + +### Result Aggregation + +Aggregate results from multiple searches: + +```python Python +# Perform multiple searches +def multi_search(query, contexts): + all_results = [] + + for context in contexts: + results = client.docs.search( + text=query, + context=context, + include_content=True + ) + all_results.extend(results) + + # Sort by similarity + all_results.sort(key=lambda x: x.similarity, reverse=True) + + return all_results[:10] # Return top 10 results +``` + +## Vector Operations + +### Document Embedding + +Work with document embeddings: + +```python Python +# Get document embedding +embedding = client.agents.docs.get_embedding( + agent_id=agent.id, + document_id=document.id +) + +# Create document with custom embedding +document = client.agents.docs.create( + agent_id=agent.id, + title="Custom Embedded Document", + content="Document content...", + embedding=custom_embedding +) +``` + +### Embedding Management + +Manage document embeddings: + +```python Python +# Update document embedding +client.agents.docs.update_embedding( + agent_id=agent.id, + document_id=document.id, + embedding=new_embedding +) + +# Recompute embeddings +client.agents.docs.recompute_embeddings( + agent_id=agent.id, + filter={ + "type": "documentation", + "updated_at": {"$gt": "2024-01-01"} + } +) +``` + +## Best Practices + +1. **Search Optimization** + - Use appropriate similarity thresholds + - Balance semantic and keyword search + - Optimize metadata filters + +2. **Performance** + - Cache frequent search results + - Use chunk-level search for large documents + - Implement pagination for large result sets + +3. **Result Quality** + - Validate search results + - Implement feedback mechanisms + - Monitor search performance + +## Example: Advanced Search Implementation + +Here's an example of a comprehensive search implementation: + +```python Python +class DocumentSearcher: + def __init__(self, client, agent_id): + self.client = client + self.agent_id = agent_id + + def search(self, query, **options): + # Default search configuration + config = { + "similarity_threshold": 0.7, + "rerank": True, + "chunk_level": True, + "limit": 10 + } + + # Update with user options + config.update(options.get("config", {})) + + # Perform semantic search + semantic_results = self.client.agents.docs.search( + agent_id=self.agent_id, + text=query, + config=config, + metadata_filter=options.get("metadata_filter"), + include_content=True + ) + + # Perform keyword search if specified + if options.get("keywords"): + keyword_results = self.client.agents.docs.keyword_search( + agent_id=self.agent_id, + keywords=options["keywords"], + metadata_filter=options.get("metadata_filter") + ) + + # Combine results + results = self._combine_results( + semantic_results, + keyword_results, + weights=options.get("weights", {"semantic": 0.7, "keyword": 0.3}) + ) + else: + results = semantic_results + + # Process results + processed_results = self._process_results(results) + + return processed_results + + def _combine_results(self, semantic_results, keyword_results, weights): + # Combine and score results + combined = {} + + for result in semantic_results: + combined[result.id] = { + "score": result.similarity * weights["semantic"], + "data": result + } + + for result in keyword_results: + if result.id in combined: + combined[result.id]["score"] += result.score * weights["keyword"] + else: + combined[result.id] = { + "score": result.score * weights["keyword"], + "data": result + } + + # Sort by combined score + sorted_results = sorted( + combined.values(), + key=lambda x: x["score"], + reverse=True + ) + + return [item["data"] for item in sorted_results] + + def _process_results(self, results): + # Process and format results + processed = [] + + for result in results: + processed.append({ + "id": result.id, + "title": result.title, + "content": result.content, + "similarity": result.similarity, + "metadata": result.metadata, + "highlights": self._get_highlights(result) + }) + + return processed + + def _get_highlights(self, result): + # Extract relevant highlights from content + # Implementation depends on your highlighting needs + pass + +# Use the searcher +searcher = DocumentSearcher(client, agent.id) + +results = searcher.search( + "security best practices", + config={ + "similarity_threshold": 0.8, + "limit": 5 + }, + metadata_filter={ + "type": "documentation", + "status": "published" + }, + keywords=["security", "authentication", "encryption"], + weights={ + "semantic": 0.6, + "keyword": 0.4 + } +) + +for result in results: + print(f"Title: {result['title']}") + print(f"Similarity: {result['similarity']}") + print(f"Highlights: {result['highlights']}") + print("---") +``` + +## Next Steps + +1. [Explore document integration](/building-blocks/doc-store/document-integration) +2. [Learn about document management](/building-blocks/doc-store/document-management) +3. [Understand agent memory](/building-blocks/agents/agent-memory) \ No newline at end of file diff --git a/documentation/building-blocks/sessions/context-and-state.mdx b/documentation/building-blocks/sessions/context-and-state.mdx new file mode 100644 index 000000000..e94a48d8f --- /dev/null +++ b/documentation/building-blocks/sessions/context-and-state.mdx @@ -0,0 +1,404 @@ +--- +title: 'Context & State' +description: 'Managing conversation context and state in Julep sessions' +--- + +## Overview + +Context and state management in Julep sessions allows agents to maintain coherent conversations and remember important information across interactions. This guide covers how to effectively manage context and state in your sessions. + +## Understanding Context + +### Context Types + +Julep manages several types of context: + +1. **Conversation Context** + - Recent message history + - System prompts and instructions + - User preferences and settings + +2. **Session State** + - Session metadata + - User information + - Conversation flow state + +3. **Agent Context** + - Agent configuration + - Available tools + - Long-term memory + +## Context Management Strategies + +### Fixed Context Window + +Maintain a fixed number of messages: + +```python Python +# Create session with fixed context +session = client.sessions.create( + agent_id=agent.id, + context_overflow="fixed", + max_messages=20, + metadata={ + "context_strategy": "fixed", + "context_size": 20 + } +) +``` + +### Adaptive Context + +Dynamically adjust context based on token usage: + +```python Python +# Create session with adaptive context +session = client.sessions.create( + agent_id=agent.id, + context_overflow="adaptive", + max_tokens=4000, + metadata={ + "context_strategy": "adaptive", + "max_tokens": 4000, + "min_messages": 5 + } +) +``` + +### Summary-based Context + +Periodically summarize older messages: + +```python Python +# Create session with summary-based context +session = client.sessions.create( + agent_id=agent.id, + context_overflow="summary", + summary_interval=10, + metadata={ + "context_strategy": "summary", + "summary_interval": 10, + "summary_method": "recursive" + } +) +``` + +## State Management + +### Session State + +Manage session-specific state: + +```python Python +# Initialize session state +session = client.sessions.create( + agent_id=agent.id, + metadata={ + "state": { + "current_step": "initial", + "user_preferences": {}, + "conversation_flow": "greeting" + } + } +) + +# Update session state +session = client.sessions.update( + session_id=session.id, + metadata={ + "state": { + "current_step": "information_gathering", + "user_preferences": { + "language": "en", + "style": "formal" + }, + "conversation_flow": "questions" + } + } +) +``` + +### State Transitions + +Handle state transitions in tasks: + +```yaml +main: + # Check current state + - evaluate: + current_state: session.metadata.state.current_step + + # State transition logic + - switch: + - case: _.current_state == "initial" + then: + - prompt: "Welcome! How can I help?" + - tool: update_session + arguments: + metadata: + state: + current_step: "greeting" + + - case: _.current_state == "greeting" + then: + - prompt: "What specific information do you need?" + - tool: update_session + arguments: + metadata: + state: + current_step: "information_gathering" +``` + +## Context Access + +### In Tasks + +Access context in task workflows: + +```yaml +main: + # Access conversation context + - prompt: + - role: system + content: "Previous context: {{session.context}}" + + # Access session state + - evaluate: + current_step: session.metadata.state.current_step + user_prefs: session.metadata.state.user_preferences + + # Access agent context + - prompt: + - role: system + content: "Agent configuration: {{agent.metadata}}" +``` + +### In Tool Calls + +Use context in tool calls: + +```yaml +tools: + - name: personalized_search + integration: + provider: search + method: query + +main: + - tool: personalized_search + arguments: + query: inputs.query + language: session.metadata.state.user_preferences.language + style: session.metadata.state.user_preferences.style +``` + +## State Persistence + +### Long-term State + +Store important information for future sessions: + +```python Python +# Store user preferences in agent's document store +client.agents.docs.create( + agent_id=agent.id, + title=f"User Preferences - {user.id}", + content=json.dumps(user_preferences), + metadata={ + "type": "preferences", + "user_id": user.id + } +) + +# Retrieve stored preferences +preferences = client.agents.docs.search( + agent_id=agent.id, + metadata_filter={ + "type": "preferences", + "user_id": user.id + } +) +``` + +### State Recovery + +Recover state from previous sessions: + +```python Python +# Find previous sessions +previous_sessions = client.sessions.list( + user_id=user.id, + agent_id=agent.id, + status="completed" +) + +# Create new session with recovered state +if previous_sessions: + last_session = previous_sessions[0] + session = client.sessions.create( + agent_id=agent.id, + user_id=user.id, + metadata={ + "state": last_session.metadata.state, + "recovered_from": last_session.id + } + ) +``` + +## Best Practices + +1. **Context Management** + - Choose appropriate context strategy + - Monitor token usage + - Use summaries for long conversations + +2. **State Management** + - Keep state structure consistent + - Update state atomically + - Handle state transitions explicitly + +3. **Performance** + - Cache frequently accessed state + - Use appropriate context window sizes + - Clean up old state data + +## Example: Complex Context and State Management + +Here's an example combining various context and state management features: + +```python Python +# Create a session with comprehensive context and state management +session = client.sessions.create( + agent_id=agent.id, + user_id=user.id, + context_overflow="adaptive", + max_tokens=8000, + metadata={ + "state": { + "conversation_flow": "initial", + "user_preferences": {}, + "interaction_history": [], + "current_task": None + }, + "context_management": { + "strategy": "adaptive", + "max_tokens": 8000, + "summary_threshold": 50 + } + } +) + +# Create a task that manages context and state +task = client.tasks.create( + agent_id=agent.id, + yaml=""" + name: Context-Aware Assistant + description: Handle user interactions with context awareness + + tools: + - name: update_session + system: + resource: session + operation: update + + - name: search_history + integration: + provider: document_store + method: search + + main: + # Load context and state + - evaluate: + current_flow: session.metadata.state.conversation_flow + preferences: session.metadata.state.user_preferences + + # Search user history + - tool: search_history + arguments: + user_id: session.user_id + type: "interaction_history" + + # Update context with historical information + - evaluate: + context_update: + history: _.search_results + last_interaction: "datetime.now().isoformat()" + + # Generate contextual response + - prompt: + - role: system + content: > + Current flow: {{_.current_flow}} + User preferences: {{_.preferences}} + Historical context: {{_.context_update.history}} + - role: user + content: "{{inputs.message}}" + + # Update state based on response + - tool: update_session + arguments: + metadata: + state: + conversation_flow: "in_progress" + last_response: _ + interaction_history: "session.metadata.state.interaction_history + [{'timestamp': datetime.now().isoformat(), 'message': inputs.message, 'response': _}]" + + # Summarize if needed + - if: "len(session.metadata.state.interaction_history) > session.metadata.context_management.summary_threshold" + then: + - prompt: + - role: system + content: "Summarize this conversation history: {{session.metadata.state.interaction_history}}" + - tool: update_session + arguments: + metadata: + state: + interaction_history: [{"summary": _}] + """ +) + +# Execute the task +execution = client.executions.create( + task_id=task.id, + session_id=session.id, + input={ + "message": "Tell me about my previous interactions" + } +) + +# Monitor and handle state changes +while True: + result = client.executions.get(execution.id) + if result.status == "succeeded": + # Update long-term state + client.agents.docs.create( + agent_id=agent.id, + title=f"Interaction Summary - {session.id}", + content=json.dumps(result.output), + metadata={ + "type": "interaction_summary", + "session_id": session.id, + "user_id": session.user_id + } + ) + break + elif result.status == "failed": + # Handle failure and restore state + client.sessions.update( + session_id=session.id, + metadata={ + "state": { + "conversation_flow": "error_recovery", + "last_error": result.error + } + } + ) + break + time.sleep(1) +``` + +## Next Steps + +1. [Learn about session management](/building-blocks/sessions/session-management) +2. [Understand agent memory](/building-blocks/agents/agent-memory) +3. [Explore task basics](/building-blocks/tasks/task-basics) \ No newline at end of file diff --git a/documentation/building-blocks/sessions/session-management.mdx b/documentation/building-blocks/sessions/session-management.mdx new file mode 100644 index 000000000..a9c429437 --- /dev/null +++ b/documentation/building-blocks/sessions/session-management.mdx @@ -0,0 +1,366 @@ +--- +title: 'Session Management' +description: 'Creating and managing user sessions in Julep' +--- + +## Overview + +Sessions in Julep enable persistent interactions between users and agents. They maintain conversation history, context, and state across multiple exchanges. This guide covers how to create, manage, and utilize sessions effectively. + +## Creating Sessions + +Create sessions using the SDK: + +```python Python +# Create a basic session +session = client.sessions.create( + agent_id=agent.id, + user_id=user.id +) + +# Create a session with configuration +session = client.sessions.create( + agent_id=agent.id, + user_id=user.id, + context_overflow="adaptive", + max_messages=50, + metadata={ + "language": "en", + "timezone": "UTC" + } +) +``` + +```javascript JavaScript +// Create a basic session +const session = await client.sessions.create({ + agentId: agent.id, + userId: user.id +}); + +// Create a session with configuration +const session = await client.sessions.create({ + agentId: agent.id, + userId: user.id, + contextOverflow: "adaptive", + maxMessages: 50, + metadata: { + language: "en", + timezone: "UTC" + } +}); +``` + +## Session Configuration + +### Context Management + +Control how conversation context is managed: + +```python Python +# Fixed context window +session = client.sessions.create( + agent_id=agent.id, + context_overflow="fixed", + max_messages=20 +) + +# Adaptive context +session = client.sessions.create( + agent_id=agent.id, + context_overflow="adaptive", + max_tokens=4000 +) + +# Summary-based context +session = client.sessions.create( + agent_id=agent.id, + context_overflow="summary", + summary_interval=10 # Summarize every 10 messages +) +``` + +### Metadata Management + +Store session-specific information: + +```python Python +# Set metadata during creation +session = client.sessions.create( + agent_id=agent.id, + metadata={ + "user_preferences": { + "language": "en", + "style": "formal" + }, + "session_type": "support" + } +) + +# Update metadata +session = client.sessions.update( + session_id=session.id, + metadata={ + "last_interaction": "2024-03-24T12:00:00Z" + } +) +``` + +## Interacting with Sessions + +### Chat Messages + +Send and receive messages: + +```python Python +# Send a message +response = client.sessions.chat( + session_id=session.id, + messages=[ + { + "role": "user", + "content": "Hello, how can you help me today?" + } + ] +) + +# Send multiple messages +response = client.sessions.chat( + session_id=session.id, + messages=[ + { + "role": "system", + "content": "You are a helpful assistant" + }, + { + "role": "user", + "content": "What can you do?" + } + ] +) +``` + +### Chat History + +Retrieve conversation history: + +```python Python +# Get all messages +history = client.sessions.history( + session_id=session.id +) + +# Get recent messages +history = client.sessions.history( + session_id=session.id, + limit=10 +) + +# Get messages with metadata +history = client.sessions.history( + session_id=session.id, + include_metadata=True +) +``` + +## Session Management + +### Listing Sessions + +```python Python +# List all sessions +sessions = client.sessions.list() + +# List sessions with filters +sessions = client.sessions.list( + agent_id=agent.id, + user_id=user.id, + status="active" +) +``` + +### Updating Sessions + +```python Python +# Update session configuration +session = client.sessions.update( + session_id=session.id, + context_overflow="adaptive", + max_messages=100 +) + +# Update metadata +session = client.sessions.update( + session_id=session.id, + metadata={ + "last_active": "2024-03-24T12:00:00Z", + "interaction_count": 42 + } +) +``` + +### Ending Sessions + +```python Python +# End a session +client.sessions.delete(session_id=session.id) + +# End all user sessions +client.sessions.delete_many(user_id=user.id) +``` + +## Session Context in Tasks + +Access session context in task workflows: + +```yaml +main: + # Access session metadata + - evaluate: + language: session.metadata.language + + # Use session context + - prompt: + - role: system + content: "Previous context: {{session.context}}" + + # Update session metadata + - tool: update_session + arguments: + metadata: + last_task: "data_analysis" +``` + +## Best Practices + +1. **Session Management** + - Use appropriate context overflow strategies + - Clean up inactive sessions + - Store relevant metadata + +2. **Context Handling** + - Choose appropriate context window sizes + - Use summaries for long conversations + - Clear context when switching topics + +3. **Performance** + - Monitor token usage + - Use appropriate timeouts + - Cache frequently accessed data + +## Example: Complex Session Usage + +Here's an example of advanced session management: + +```python Python +# Create a session with custom configuration +session = client.sessions.create( + agent_id=agent.id, + user_id=user.id, + context_overflow="adaptive", + max_tokens=8000, + metadata={ + "preferences": { + "language": "en", + "style": "formal", + "expertise_level": "advanced" + }, + "session_type": "technical_support", + "started_at": datetime.now().isoformat() + } +) + +# Create a task that uses session context +task = client.tasks.create( + agent_id=agent.id, + yaml=""" + name: Technical Support + description: Handle technical support requests + + tools: + - name: search_docs + integration: + provider: document_store + method: search + + - name: update_session + system: + resource: session + operation: update + + main: + # Check session context + - evaluate: + language: session.metadata.preferences.language + expertise: session.metadata.preferences.expertise_level + + # Customize response based on user preferences + - prompt: + - role: system + content: > + You are a technical support agent. + User language: {{_.language}} + Expertise level: {{_.expertise}} + Previous context: {{session.context}} + - role: user + content: "{{inputs.query}}" + + # Search documentation + - tool: search_docs + arguments: + query: inputs.query + language: _.language + + # Generate response + - prompt: + - role: system + content: "Generate a response using these docs: {{_.search_results}}" + - role: user + content: "{{inputs.query}}" + + # Update session metadata + - tool: update_session + arguments: + metadata: + last_query: inputs.query + last_response_time: "datetime.now().isoformat()" + interaction_count: "session.metadata.interaction_count + 1" + """ +) + +# Execute the task in the session +execution = client.executions.create( + task_id=task.id, + session_id=session.id, + input={ + "query": "How do I configure SSL certificates?" + } +) + +# Monitor the execution +while True: + result = client.executions.get(execution.id) + if result.status in ["succeeded", "failed"]: + break + time.sleep(1) + +# Get updated session history +history = client.sessions.history( + session_id=session.id, + include_metadata=True +) + +# Clean up if needed +if history.total_messages > 100: + # Summarize and archive old messages + client.sessions.update( + session_id=session.id, + context_overflow="summary" + ) +``` + +## Next Steps + +1. [Learn about context and state](/building-blocks/sessions/context-and-state) +2. [Explore task basics](/building-blocks/tasks/task-basics) +3. [Understand agent memory](/building-blocks/agents/agent-memory) \ No newline at end of file diff --git a/documentation/building-blocks/tasks/control-flow.mdx b/documentation/building-blocks/tasks/control-flow.mdx new file mode 100644 index 000000000..bf20de765 --- /dev/null +++ b/documentation/building-blocks/tasks/control-flow.mdx @@ -0,0 +1,413 @@ +--- +title: 'Control Flow' +description: 'Managing task flow with conditions, loops, and parallel execution in Julep' +--- + +## Overview + +Control flow in Julep allows you to create sophisticated task workflows by managing the sequence of execution, handling conditions, implementing loops, and running steps in parallel. This guide covers all aspects of control flow management in Julep tasks. + +## Conditional Execution + +### If-Else Statements + +Control execution based on conditions: + +```yaml +# Basic if statement +- if: _.score > 0.8 + then: + - log: "High score achieved" + +# If-else statement +- if: _.temperature > 30 + then: + - log: "It's hot today" + else: + - log: "Temperature is normal" + +# Nested conditions +- if: _.user_type == "premium" + then: + - if: _.usage > 1000 + then: + - log: "High usage premium user" + else: + - log: "Normal usage premium user" + else: + - log: "Regular user" +``` + +### Switch Statements + +Handle multiple conditions: + +```yaml +# Basic switch +- switch: + - case: _.status == "pending" + then: + - log: "Task is pending" + - case: _.status == "running" + then: + - log: "Task is running" + - case: _ # Default case + then: + - log: "Unknown status" + +# Switch with complex logic +- switch: + - case: _.score > 90 + then: + - evaluate: + grade: "'A'" + - case: _.score > 80 + then: + - evaluate: + grade: "'B'" + - case: _.score > 70 + then: + - evaluate: + grade: "'C'" + - case: _ + then: + - evaluate: + grade: "'F'" +``` + +## Loops and Iteration + +### Foreach Loop + +Iterate over collections: + +```yaml +# Simple foreach +- foreach: + in: _.items + do: + - log: "Processing {{_}}" + +# Foreach with complex processing +- foreach: + in: _.documents + do: + - tool: analyze + arguments: + text: _.content + - if: _.analysis.score > 0.8 + then: + - tool: save_result + arguments: + data: _.analysis +``` + +### Map-Reduce + +Process collections in parallel: + +```yaml +# Basic map-reduce +- map_reduce: + over: _.urls + map: + - tool: fetch_content + arguments: + url: _ + reduce: results + [_] + +# Map-reduce with custom reduction +- map_reduce: + over: _.numbers + map: + - evaluate: + squared: "_ ** 2" + reduce: "max(results + [_])" + initial: 0 +``` + +## Parallel Execution + +### Parallel Steps + +Execute multiple steps concurrently: + +```yaml +# Basic parallel execution +- parallel: + - tool: task1 + arguments: + param: "value1" + - tool: task2 + arguments: + param: "value2" + +# Parallel with result handling +- parallel: + - tool: web_search + arguments: + query: "AI news" + - tool: arxiv_search + arguments: + query: "AI research" +- evaluate: + web_results: _[0] + academic_results: _[1] +``` + +### Parallel Map-Reduce + +Process collections with controlled parallelism: + +```yaml +# Parallel processing with limit +- map_reduce: + over: _.queries + map: + - tool: web_search + arguments: + query: _ + parallelism: 5 + +# Complex parallel processing +- map_reduce: + over: _.documents + map: + - parallel: + - tool: analyze_sentiment + arguments: + text: _.content + - tool: extract_keywords + arguments: + text: _.content + parallelism: 3 +``` + +## Flow Control + +### Sleep and Delays + +Introduce delays in workflow: + +```yaml +# Simple delay +- sleep: + seconds: 30 + +# Conditional delay +- if: _.retry_count > 0 + then: + - sleep: + seconds: "_.retry_count * 10" +``` + +### Early Returns + +Exit workflow early: + +```yaml +# Early return on condition +- if: _.error_count > 3 + then: + - return: + status: "error" + message: "Too many errors" + +# Return with processed data +- if: _.data_valid + then: + - return: + result: _.processed_data + metadata: + processing_time: _.duration +``` + +### Error Handling + +Handle errors in workflow: + +```yaml +# Try-catch pattern +- if: "try_function(_)" + then: + - log: "Operation successful" + else: + - log: "Operation failed" + - return: + error: _.error_message + +# Retry pattern +- evaluate: + retry_count: 0 +- while: _.retry_count < 3 + do: + - if: "try_operation(_)" + then: + - return: _.result + else: + - evaluate: + retry_count: "_.retry_count + 1" + - sleep: + seconds: "2 ** _.retry_count" +``` + +## Advanced Patterns + +### State Machines + +Implement state machine patterns: + +```yaml +main: + - evaluate: + state: "initial" + + - while: _.state != "completed" + do: + - switch: + - case: _.state == "initial" + then: + - tool: initialize + arguments: + data: _.input + - evaluate: + state: "processing" + + - case: _.state == "processing" + then: + - tool: process + arguments: + data: _.result + - if: _.processing_complete + then: + - evaluate: + state: "completed" + else: + - evaluate: + state: "processing" +``` + +### Pipeline Pattern + +Create data processing pipelines: + +```yaml +main: + # Data ingestion + - parallel: + - tool: load_source1 + arguments: + params: _.source1_params + - tool: load_source2 + arguments: + params: _.source2_params + + # Data processing + - map_reduce: + over: _ + map: + - tool: clean_data + arguments: + data: _ + - tool: transform_data + arguments: + data: _ + parallelism: 3 + + # Data aggregation + - tool: aggregate_results + arguments: + data: _ + + # Result validation + - if: _.validation_score > 0.9 + then: + - tool: save_results + arguments: + data: _.aggregated_data + else: + - return: + error: "Validation failed" +``` + +## Best Practices + +1. **Flow Design** + - Keep workflows linear when possible + - Use parallel execution judiciously + - Handle errors at appropriate levels + +2. **Performance** + - Balance parallelism with resource constraints + - Use appropriate timeouts + - Cache results when beneficial + +3. **Maintainability** + - Document complex flow logic + - Break down complex workflows + - Use consistent patterns + +## Example: Complex Control Flow + +Here's an example combining various control flow patterns: + +```yaml +main: + # Initialize + - evaluate: + start_time: "datetime.now().isoformat()" + retry_count: 0 + batch_size: 10 + + # Batch processing with retries + - foreach: + in: "range(0, len(_.items), _.batch_size)" + do: + # Process batch in parallel + - map_reduce: + over: "_.items[_:_ + _.batch_size]" + map: + - parallel: + - tool: process_item + arguments: + item: _ + - tool: validate_item + arguments: + item: _ + parallelism: 5 + + # Handle batch results + - foreach: + in: _ + do: + - if: "_.processing_result[0].success and _.processing_result[1].valid" + then: + - tool: save_result + arguments: + result: _.processing_result + else: + # Retry failed items + - while: _.retry_count < 3 + do: + - evaluate: + retry_count: "_.retry_count + 1" + - sleep: + seconds: "2 ** _.retry_count" + - tool: retry_processing + arguments: + item: _ + + # Finalize + - return: + results: _.processed_items + metadata: + start_time: _.start_time + end_time: "datetime.now().isoformat()" + retry_count: _.retry_count +``` + +## Next Steps + +1. [Explore workflow steps](/building-blocks/tasks/workflow-steps) +2. [Learn about task basics](/building-blocks/tasks/task-basics) +3. [Understand session management](/building-blocks/sessions/session-management) \ No newline at end of file diff --git a/documentation/building-blocks/tasks/task-basics.mdx b/documentation/building-blocks/tasks/task-basics.mdx new file mode 100644 index 000000000..3b050e54a --- /dev/null +++ b/documentation/building-blocks/tasks/task-basics.mdx @@ -0,0 +1,318 @@ +--- +title: 'Task Basics' +description: 'Understanding task structure and components in Julep' +--- + +## Overview + +Tasks in Julep are the building blocks for creating complex AI workflows. They define a sequence of steps that an agent can execute, including prompts, tool calls, and control flow logic. + +## Task Structure + +A basic task consists of: + +```yaml +name: Task Name +description: Task description +input_schema: # Optional: Define expected input format + type: object + properties: + param1: + type: string + description: First parameter + param2: + type: integer + description: Second parameter + +tools: # Optional: Define tools needed for the task + - name: tool1 + integration: + provider: provider_name + method: method_name + +main: # Required: Define the main workflow steps + - prompt: "First step" + - tool: tool1 + arguments: + param: "value" +``` + +## Creating Tasks + +You can create tasks using either the Python or Node.js SDK: + +```python Python +# Create a task using YAML +task = client.tasks.create( + agent_id=agent.id, + yaml=""" + name: Simple Task + description: A basic example task + + main: + - prompt: "Hello, how can I help?" + """ +) + +# Create a task using dictionary +task = client.tasks.create( + agent_id=agent.id, + name="Simple Task", + description="A basic example task", + main=[ + {"prompt": "Hello, how can I help?"} + ] +) +``` + +```javascript JavaScript +// Create a task using YAML +const task = await client.tasks.create( + agentId, + ` + name: Simple Task + description: A basic example task + + main: + - prompt: "Hello, how can I help?" + ` +); + +// Create a task using object +const task = await client.tasks.create( + agentId, + { + name: "Simple Task", + description: "A basic example task", + main: [ + {prompt: "Hello, how can I help?"} + ] + } +); +``` + +## Task Components + +### 1. Input Schema + +Define expected input parameters: + +```yaml +input_schema: + type: object + required: ["query"] + properties: + query: + type: string + description: Search query + limit: + type: integer + description: Maximum number of results + default: 10 +``` + +### 2. Tools + +Declare tools needed for the task: + +```yaml +tools: + - name: web_search + integration: + provider: brave + method: search + + - name: summarize + function: + parameters: + type: object + properties: + text: + type: string +``` + +### 3. Main Workflow + +Define the sequence of steps: + +```yaml +main: + # Simple prompt + - prompt: "What can I help you with?" + + # Prompt with system and user messages + - prompt: + - role: system + content: "You are a helpful assistant" + - role: user + content: "Hello!" + + # Tool usage + - tool: web_search + arguments: + query: "{{inputs.query}}" + + # Evaluate expressions + - evaluate: + result_count: "len(_.search_results)" + + # Conditional logic + - if: "_.result_count > 0" + then: + - prompt: "Found {{_.result_count}} results" + else: + - prompt: "No results found" +``` + +## Executing Tasks + +Execute tasks with input parameters: + +```python Python +# Execute a task +execution = client.executions.create( + task_id=task.id, + input={ + "query": "AI developments", + "limit": 5 + } +) + +# Monitor execution progress +while True: + result = client.executions.get(execution.id) + if result.status in ["succeeded", "failed"]: + break + time.sleep(1) + +# Get the final result +if result.status == "succeeded": + print(result.output) +else: + print(f"Error: {result.error}") +``` + +## Context Variables + +Tasks have access to various context variables: + +1. **Input Variables** + ```yaml + main: + - prompt: "Searching for: {{inputs.query}}" + ``` + +2. **Step Results** + ```yaml + main: + - evaluate: + value: 42 + - prompt: "The value is {{_.value}}" + ``` + +3. **Agent Context** + ```yaml + main: + - prompt: "Agent name: {{agent.name}}" + ``` + +4. **Session Context** + ```yaml + main: + - prompt: "Session ID: {{session.id}}" + ``` + +## Best Practices + +1. **Task Design** + - Keep tasks focused on a single purpose + - Use clear, descriptive names + - Document expected inputs and outputs + +2. **Error Handling** + - Validate inputs using input_schema + - Handle tool failures gracefully + - Provide meaningful error messages + +3. **Performance** + - Use parallel execution when possible + - Cache intermediate results + - Break large tasks into smaller subtasks + +## Example: Complex Task + +Here's an example of a more complex task: + +```yaml +name: Research Assistant +description: Research a topic and provide a summary + +input_schema: + type: object + required: ["topic"] + properties: + topic: + type: string + description: Research topic + depth: + type: string + enum: ["basic", "detailed", "comprehensive"] + default: "basic" + +tools: + - name: web_search + integration: + provider: brave + method: search + + - name: arxiv_search + integration: + provider: arxiv + method: search + +main: + # Initial research plan + - prompt: + - role: system + content: "You are a research assistant. Plan a research strategy for: {{inputs.topic}}" + + # Parallel research + - parallel: + - tool: web_search + arguments: + query: "{{inputs.topic}} latest developments" + + - tool: arxiv_search + arguments: + query: "{{inputs.topic}}" + max_results: 5 + + # Process results + - evaluate: + web_results: _[0] + academic_results: _[1] + + # Generate summary based on depth + - if: inputs.depth == "basic" + then: + - prompt: "Create a brief summary of {{inputs.topic}}" + else: + - if: inputs.depth == "detailed" + then: + - prompt: "Create a detailed analysis of {{inputs.topic}}" + else: + - prompt: "Create a comprehensive report on {{inputs.topic}}" + + # Return formatted results + - return: + summary: _ + sources: + web: _.web_results + academic: _.academic_results +``` + +## Next Steps + +1. [Learn about workflow steps](/building-blocks/tasks/workflow-steps) +2. [Understand control flow](/building-blocks/tasks/control-flow) +3. [Explore agent tools](/building-blocks/agents/agent-tools) \ No newline at end of file diff --git a/documentation/building-blocks/tasks/workflow-steps.mdx b/documentation/building-blocks/tasks/workflow-steps.mdx new file mode 100644 index 000000000..903db60bc --- /dev/null +++ b/documentation/building-blocks/tasks/workflow-steps.mdx @@ -0,0 +1,365 @@ +--- +title: 'Workflow Steps' +description: 'Detailed guide to all available workflow step types in Julep' +--- + +## Overview + +Workflow steps are the building blocks of tasks in Julep. Each step represents a specific action or operation that can be performed as part of a task's execution. This guide covers all available step types and their usage. + +## Common Steps + +### Prompt Step + +Send messages to the AI model: + +```yaml +# Simple prompt +- prompt: "What is your name?" + +# Multi-message prompt +- prompt: + - role: system + content: "You are a helpful assistant" + - role: user + content: "Hello!" + +# Prompt with settings +- prompt: + - role: user + content: "Generate a creative story" + settings: + model: "claude-3.5-sonnet" + temperature: 0.8 +``` + +### Tool Call Step + +Execute tools defined in the task: + +```yaml +# Simple tool call +- tool: web_search + arguments: + query: "Latest AI news" + +# Tool call with complex arguments +- tool: process_data + arguments: + input_data: _.previous_result + options: + format: "json" + validate: true +``` + +### Evaluate Step + +Perform calculations or data manipulation: + +```yaml +# Simple evaluation +- evaluate: + count: "len(_.results)" + +# Multiple evaluations +- evaluate: + total: "sum(_.numbers)" + average: "_.total / len(_.numbers)" + formatted: "f'Average: {_.average:.2f}'" +``` + +### Wait for Input Step + +Pause workflow for user input: + +```yaml +# Simple input request +- wait_for_input: + info: + message: "Please provide your name" + +# Input with validation +- wait_for_input: + info: + message: "Enter your age" + validation: + type: "number" + minimum: 0 + maximum: 150 +``` + +## Key-Value Steps + +### Get Step + +Retrieve values from storage: + +```yaml +# Get a single value +- get: user_preference + +# Get multiple values +- get: + - preference1 + - preference2 +``` + +### Set Step + +Store values for later use: + +```yaml +# Set a single value +- set: + user_name: "John" + +# Set multiple values +- set: + count: "len(_.results)" + has_data: "_.count > 0" +``` + +## Iteration Steps + +### Foreach Step + +Iterate over a collection: + +```yaml +# Simple foreach +- foreach: + in: _.items + do: + - log: "Processing {{_}}" + +# Foreach with complex processing +- foreach: + in: _.documents + do: + - tool: analyze + arguments: + text: _.content + - evaluate: + results: "_ + [_.analysis]" +``` + +### Map-Reduce Step + +Process collections in parallel: + +```yaml +# Simple map-reduce +- map_reduce: + over: _.urls + map: + - tool: fetch_content + arguments: + url: _ + reduce: results + [_] + +# Map-reduce with parallelism +- map_reduce: + over: _.queries + map: + - tool: web_search + arguments: + query: _ + parallelism: 5 +``` + +### Parallel Step + +Execute steps concurrently: + +```yaml +# Parallel execution +- parallel: + - tool: task1 + arguments: + param: "value1" + - tool: task2 + arguments: + param: "value2" +``` + +## Conditional Steps + +### If-Else Step + +Conditional execution: + +```yaml +# Simple if +- if: _.count > 0 + then: + - log: "Found results" + +# If-else +- if: _.score > 0.8 + then: + - log: "High score" + else: + - log: "Low score" + +# Nested conditions +- if: _.type == "A" + then: + - if: _.value > 10 + then: + - log: "High value A" + else: + - log: "Low value A" + else: + - log: "Not type A" +``` + +### Switch Step + +Multiple condition handling: + +```yaml +# Switch statement +- switch: + - case: _.category == "A" + then: + - log: "Category A" + - case: _.category == "B" + then: + - log: "Category B" + - case: _ # Default case + then: + - log: "Unknown category" +``` + +## Other Control Flow + +### Sleep Step + +Pause execution: + +```yaml +# Sleep for duration +- sleep: + seconds: 30 + +# Sleep with different units +- sleep: + minutes: 5 + # hours: 1 + # days: 1 +``` + +### Return Step + +Return values from workflow: + +```yaml +# Simple return +- return: _.result + +# Structured return +- return: + data: _.processed_data + metadata: + count: _.count + timestamp: "datetime.now().isoformat()" +``` + +### Yield Step + +Execute subworkflows: + +```yaml +# Yield to subworkflow +- yield: + workflow: process_data + arguments: + input_data: _.raw_data + +# Yield with result handling +- yield: + workflow: analyze + arguments: + text: _.content +- evaluate: + analysis_result: _ +``` + +## Best Practices + +1. **Step Organization** + - Group related steps logically + - Use comments to explain complex steps + - Keep step chains focused and manageable + +2. **Error Handling** + - Use if-else for error conditions + - Provide fallback options + - Log important state changes + +3. **Performance** + - Use parallel execution when possible + - Optimize data passing between steps + - Cache frequently used values + +## Example: Complex Workflow + +Here's an example combining various step types: + +```yaml +main: + # Initial setup + - evaluate: + start_time: "datetime.now().isoformat()" + + # Get user input + - wait_for_input: + info: + message: "Enter search topics (comma-separated)" + + # Process input + - evaluate: + topics: "_.input.split(',')" + + # Parallel search + - map_reduce: + over: _.topics + map: + - parallel: + - tool: web_search + arguments: + query: _ + - tool: arxiv_search + arguments: + query: _ + parallelism: 3 + + # Process results + - foreach: + in: _ + do: + - evaluate: + web_results: _[0] + academic_results: _[1] + - if: "len(_.web_results) > 0 or len(_.academic_results) > 0" + then: + - tool: summarize + arguments: + texts: _.web_results + _.academic_results + else: + - evaluate: + summary: "'No results found'" + + # Return final results + - return: + results: _ + metadata: + start_time: _.start_time + end_time: "datetime.now().isoformat()" +``` + +## Next Steps + +1. [Learn about control flow](/building-blocks/tasks/control-flow) +2. [Explore task basics](/building-blocks/tasks/task-basics) +3. [Understand agent tools](/building-blocks/agents/agent-tools) \ No newline at end of file diff --git a/documentation/building-blocks/users/user-context.mdx b/documentation/building-blocks/users/user-context.mdx new file mode 100644 index 000000000..f69e7cef5 --- /dev/null +++ b/documentation/building-blocks/users/user-context.mdx @@ -0,0 +1,373 @@ +--- +title: 'User Context' +description: 'Managing user-specific data and preferences in Julep' +--- + +## Overview + +User context in Julep enables personalized experiences by maintaining user-specific data, preferences, and settings across interactions. This guide explains how to effectively manage and utilize user context in your applications. + +## Understanding User Context + +### Context Types + +1. **User Preferences** + - Language settings + - UI preferences + - Notification settings + +2. **Interaction History** + - Past conversations + - Previous tasks + - Usage patterns + +3. **Custom Data** + - Application-specific settings + - User-defined variables + - Integration preferences + +## Managing User Context + +### Setting Context + +Set user-specific context: + +```python Python +# Update user preferences +context = client.context.set( + user_id, + preferences={ + "language": "en", + "theme": "dark", + "notifications": { + "email": True, + "push": False + } + } +) + +# Add custom context +custom_context = client.context.set( + user_id, + custom_data={ + "project_id": "proj_123", + "role": "admin", + "features": ["advanced_search", "analytics"] + } +) +``` + +### Retrieving Context + +Access user context: + +```python Python +# Get all context +context = client.context.get(user_id) + +# Get specific context +preferences = client.context.get( + user_id, + path="preferences" +) + +# Get nested context +notification_settings = client.context.get( + user_id, + path="preferences.notifications" +) +``` + +### Updating Context + +Modify existing context: + +```python Python +# Update specific fields +updated_context = client.context.update( + user_id, + path="preferences.theme", + value="light" +) + +# Merge context +merged_context = client.context.merge( + user_id, + preferences={ + "notifications": { + "desktop": True + } + } +) +``` + +## Context in Tasks + +### Accessing Context + +Use context in task workflows: + +```yaml +tools: + - name: get_context + system: + resource: agent + subresource: context + operation: get + +main: + # Get user preferences + - tool: get_context + arguments: + user_id: "{{inputs.user_id}}" + path: "preferences" + + # Use preferences in prompt + - prompt: + - role: system + content: > + User preferences: + Language: {{_.preferences.language}} + Theme: {{_.preferences.theme}} + - role: user + content: "{{inputs.query}}" +``` + +### Updating Context in Tasks + +Modify context during task execution: + +```yaml +tools: + - name: update_context + system: + resource: agent + subresource: context + operation: update + +main: + # Update user preferences based on interaction + - prompt: + - role: user + content: "{{inputs.query}}" + + - tool: update_context + arguments: + user_id: "{{inputs.user_id}}" + path: "preferences.last_topic" + value: "{{inputs.query}}" +``` + +## Context Persistence + +### Storage Options + +Configure context storage: + +```python Python +# Set context with storage options +context = client.context.set( + user_id, + preferences={ + "language": "en" + }, + storage_options={ + "persistence": "permanent", + "encryption": True, + "ttl": 86400 # 24 hours + } +) + +# Set temporary context +temp_context = client.context.set( + user_id, + temporary_data={ + "current_task": "analysis" + }, + storage_options={ + "persistence": "temporary", + "ttl": 3600 # 1 hour + } +) +``` + +### Context Lifecycle + +Manage context lifecycle: + +```python Python +# Clear specific context +client.context.clear( + user_id, + path="temporary_data" +) + +# Clear all context +client.context.clear(user_id) + +# Export context +context_backup = client.context.export(user_id) + +# Import context +client.context.import_( + user_id, + context_data=context_backup +) +``` + +## Best Practices + +1. **Context Organization** + - Use clear hierarchical structure + - Separate permanent and temporary data + - Document context schema + +2. **Performance** + - Cache frequently accessed context + - Use selective updates + - Implement context pruning + +3. **Security** + - Encrypt sensitive data + - Implement access controls + - Regular context cleanup + +## Example: Advanced Context Management + +Here's a comprehensive example of context management: + +```python Python +class ContextManager: + def __init__(self, client): + self.client = client + + async def initialize_user_context(self, user_id, initial_data): + # Set up basic context structure + context = await self.client.context.set( + user_id, + preferences=initial_data.get("preferences", {}), + settings=initial_data.get("settings", {}), + metadata={ + "created_at": datetime.now().isoformat(), + "version": "1.0" + } + ) + + # Set up temporary storage + temp_context = await self.client.context.set( + user_id, + temporary_data={}, + storage_options={ + "persistence": "temporary", + "ttl": 3600 + } + ) + + return { + "permanent": context, + "temporary": temp_context + } + + async def update_interaction_context(self, user_id, interaction_data): + # Get current context + context = await self.client.context.get(user_id) + + # Update interaction history + history = context.get("interaction_history", []) + history.append({ + "timestamp": datetime.now().isoformat(), + "type": interaction_data["type"], + "data": interaction_data["data"] + }) + + # Trim history if needed + if len(history) > 100: + history = history[-100:] + + # Update context + updated_context = await self.client.context.merge( + user_id, + interaction_history=history, + metadata={ + "last_interaction": datetime.now().isoformat() + } + ) + + # Update temporary context + temp_context = await self.client.context.set( + user_id, + temporary_data={ + "current_interaction": interaction_data, + "session_data": { + "start_time": context.get("temporary_data", {}).get("session_data", {}).get("start_time", datetime.now().isoformat()), + "interaction_count": len(history) + } + }, + storage_options={ + "persistence": "temporary", + "ttl": 3600 + } + ) + + return { + "permanent": updated_context, + "temporary": temp_context + } + + async def get_user_insights(self, user_id): + # Get full context + context = await self.client.context.get(user_id) + + # Analyze interaction history + history = context.get("interaction_history", []) + + # Generate insights + insights = { + "total_interactions": len(history), + "interaction_types": Counter(i["type"] for i in history), + "recent_topics": [i["data"].get("topic") for i in history[-5:]], + "preferences": context.get("preferences", {}), + "session_data": context.get("temporary_data", {}).get("session_data", {}) + } + + return insights + +# Use the manager +manager = ContextManager(client) + +# Initialize context +context = await manager.initialize_user_context( + user_id, + initial_data={ + "preferences": { + "language": "en", + "theme": "dark" + }, + "settings": { + "notifications": True + } + } +) + +# Update context with interaction +updated = await manager.update_interaction_context( + user_id, + interaction_data={ + "type": "query", + "data": { + "topic": "AI", + "query": "How does machine learning work?" + } + } +) + +# Get insights +insights = await manager.get_user_insights(user_id) +print("User insights:", insights) +``` + +## Next Steps + +1. [Explore user sessions](/building-blocks/users/user-sessions) +2. [Learn about user management](/building-blocks/users/user-management) +3. [Understand session management](/building-blocks/sessions/session-management) \ No newline at end of file diff --git a/documentation/building-blocks/users/user-management.mdx b/documentation/building-blocks/users/user-management.mdx new file mode 100644 index 000000000..cc52ea7ef --- /dev/null +++ b/documentation/building-blocks/users/user-management.mdx @@ -0,0 +1,385 @@ +--- +title: 'User Management' +description: 'Creating and managing user profiles in Julep' +--- + +## Overview + +User management in Julep allows you to create and manage user profiles, enabling personalized experiences and user-specific context in your applications. This guide covers the essential aspects of user management. + +## Creating Users + +### Basic User Creation + +Create a new user profile: + +```python Python +# Create a user +user = client.users.create( + username="john_doe", + metadata={ + "name": "John Doe", + "email": "john@example.com", + "preferences": { + "language": "en", + "timezone": "UTC" + } + } +) + +print(f"Created user: {user.id}") +``` + +### Batch User Creation + +Create multiple users efficiently: + +```python Python +# Create multiple users +users = client.users.create_batch([ + { + "username": "user1", + "metadata": { + "name": "User One", + "email": "user1@example.com" + } + }, + { + "username": "user2", + "metadata": { + "name": "User Two", + "email": "user2@example.com" + } + } +]) + +for user in users: + print(f"Created user: {user.id}") +``` + +## Managing Users + +### Retrieving Users + +Get user information: + +```python Python +# Get user by ID +user = client.users.get(user_id) + +# List all users +users = client.users.list() + +# Search users +filtered_users = client.users.search( + query="john", + metadata_filter={ + "preferences.language": "en" + } +) +``` + +### Updating Users + +Update user profiles: + +```python Python +# Update user metadata +updated_user = client.users.update( + user_id, + metadata={ + "preferences": { + "language": "es", + "notifications_enabled": True + } + } +) + +# Patch specific fields +patched_user = client.users.patch( + user_id, + metadata={ + "last_login": "2024-01-01T00:00:00Z" + } +) +``` + +### Deleting Users + +Remove user profiles: + +```python Python +# Delete a user +client.users.delete(user_id) + +# Batch delete users +client.users.delete_batch(user_ids) +``` + +## User Data Management + +### User Metadata + +Structure user metadata effectively: + +```python Python +metadata = { + "profile": { + "name": "John Doe", + "email": "john@example.com", + "avatar_url": "https://example.com/avatar.jpg" + }, + "preferences": { + "language": "en", + "timezone": "UTC", + "theme": "dark", + "notifications": { + "email": True, + "push": False + } + }, + "settings": { + "default_model": "gpt-4", + "max_tokens": 1000, + "temperature": 0.7 + } +} + +user = client.users.create( + username="john_doe", + metadata=metadata +) +``` + +### User Groups + +Manage user groups: + +```python Python +# Create a group +group = client.groups.create( + name="premium_users", + metadata={ + "access_level": "premium", + "features": ["advanced_tools", "priority_support"] + } +) + +# Add users to group +client.groups.add_users( + group_id=group.id, + user_ids=[user1_id, user2_id] +) + +# Get group members +members = client.groups.list_users(group.id) +``` + +## User Authentication + +### Token Management + +Manage user authentication tokens: + +```python Python +# Create user token +token = client.users.create_token( + user_id, + expires_in=3600, # 1 hour + metadata={ + "device": "mobile", + "platform": "ios" + } +) + +# Revoke token +client.users.revoke_token(token.id) + +# List user tokens +tokens = client.users.list_tokens(user_id) +``` + +### Session Management + +Handle user sessions: + +```python Python +# Create user session +session = client.sessions.create( + user_id=user.id, + metadata={ + "device": "web", + "ip_address": "192.168.1.1" + } +) + +# End session +client.sessions.end(session.id) + +# List active sessions +active_sessions = client.sessions.list( + user_id=user.id, + status="active" +) +``` + +## Best Practices + +1. **User Data Organization** + - Structure metadata consistently + - Use meaningful field names + - Include essential user information + +2. **Security** + - Implement proper authentication + - Manage tokens securely + - Regular security audits + +3. **Performance** + - Use batch operations + - Implement caching + - Optimize queries + +## Example: Complete User Management + +Here's a comprehensive example of user management: + +```python Python +class UserManager: + def __init__(self, client): + self.client = client + + async def create_user_with_preferences(self, username, email, preferences): + # Create user + user = await self.client.users.create( + username=username, + metadata={ + "email": email, + "preferences": preferences, + "created_at": datetime.now().isoformat() + } + ) + + # Create initial session + session = await self.client.sessions.create( + user_id=user.id, + metadata={ + "type": "initial_setup", + "created_at": datetime.now().isoformat() + } + ) + + # Set up user workspace + workspace = await self.client.workspaces.create( + name=f"{username}'s Workspace", + metadata={ + "owner_id": user.id, + "created_at": datetime.now().isoformat() + } + ) + + # Update user with workspace + updated_user = await self.client.users.update( + user.id, + metadata={ + **user.metadata, + "workspace_id": workspace.id + } + ) + + return { + "user": updated_user, + "session": session, + "workspace": workspace + } + + async def archive_user(self, user_id): + # Get user data + user = await self.client.users.get(user_id) + + # End all sessions + sessions = await self.client.sessions.list( + user_id=user_id, + status="active" + ) + for session in sessions: + await self.client.sessions.end(session.id) + + # Archive workspace + if "workspace_id" in user.metadata: + await self.client.workspaces.update( + user.metadata["workspace_id"], + metadata={ + "status": "archived", + "archived_at": datetime.now().isoformat() + } + ) + + # Archive user + archived_user = await self.client.users.update( + user_id, + metadata={ + **user.metadata, + "status": "archived", + "archived_at": datetime.now().isoformat() + } + ) + + return archived_user + + async def get_user_activity(self, user_id): + # Get user sessions + sessions = await self.client.sessions.list( + user_id=user_id, + limit=100 + ) + + # Get user interactions + interactions = await self.client.interactions.list( + user_id=user_id, + limit=100 + ) + + # Analyze activity + activity_summary = { + "total_sessions": len(sessions), + "active_sessions": sum(1 for s in sessions if s.status == "active"), + "total_interactions": len(interactions), + "last_active": max(s.created_at for s in sessions), + "interaction_types": Counter(i.type for i in interactions) + } + + return activity_summary + +# Use the manager +manager = UserManager(client) + +# Create new user +result = await manager.create_user_with_preferences( + username="jane_doe", + email="jane@example.com", + preferences={ + "language": "en", + "timezone": "UTC", + "theme": "light" + } +) + +print("Created user:", result["user"].id) +print("Initial session:", result["session"].id) +print("Workspace:", result["workspace"].id) + +# Get user activity +activity = await manager.get_user_activity(result["user"].id) +print("User activity:", activity) + +# Archive user +archived = await manager.archive_user(result["user"].id) +print("Archived user:", archived.id) +``` + +## Next Steps + +1. [Learn about user context](/building-blocks/users/user-context) +2. [Explore user sessions](/building-blocks/users/user-sessions) +3. [Understand session management](/building-blocks/sessions/session-management) \ No newline at end of file diff --git a/documentation/building-blocks/users/user-sessions.mdx b/documentation/building-blocks/users/user-sessions.mdx new file mode 100644 index 000000000..5aa27b675 --- /dev/null +++ b/documentation/building-blocks/users/user-sessions.mdx @@ -0,0 +1,396 @@ +--- +title: 'User Sessions' +description: 'Linking users with sessions and managing user state in Julep' +--- + +## Overview + +User sessions in Julep provide a way to manage user interactions and maintain state across conversations. This guide explains how to effectively manage user sessions and integrate them with your applications. + +## Session Management + +### Creating Sessions + +Create new user sessions: + +```python Python +# Create basic session +session = client.sessions.create( + user_id=user.id, + metadata={ + "device": "web", + "ip_address": "192.168.1.1" + } +) + +# Create session with configuration +configured_session = client.sessions.create( + user_id=user.id, + metadata={ + "device": "mobile", + "platform": "ios" + }, + config={ + "timeout": 3600, # 1 hour + "max_messages": 100, + "context_window": 10 + } +) +``` + +### Session Lifecycle + +Manage session states: + +```python Python +# Start session +active_session = client.sessions.start(session.id) + +# Pause session +paused_session = client.sessions.pause(session.id) + +# Resume session +resumed_session = client.sessions.resume(session.id) + +# End session +ended_session = client.sessions.end(session.id) +``` + +### Session Retrieval + +Access session information: + +```python Python +# Get session by ID +session = client.sessions.get(session_id) + +# List user sessions +sessions = client.sessions.list( + user_id=user.id, + status="active" +) + +# Search sessions +filtered_sessions = client.sessions.search( + metadata_filter={ + "device": "web" + } +) +``` + +## Session Context + +### Managing Session State + +Handle session-specific context: + +```python Python +# Set session context +context = client.sessions.set_context( + session_id, + context={ + "current_task": "analysis", + "last_response": "Previous response data", + "user_input": { + "query": "How does this work?", + "timestamp": "2024-01-01T00:00:00Z" + } + } +) + +# Get session context +session_context = client.sessions.get_context(session_id) + +# Update session context +updated_context = client.sessions.update_context( + session_id, + path="current_task", + value="processing" +) +``` + +### Session History + +Track conversation history: + +```python Python +# Add message to history +client.sessions.add_message( + session_id, + message={ + "role": "user", + "content": "How can I use this feature?", + "timestamp": "2024-01-01T00:00:00Z" + } +) + +# Get session history +history = client.sessions.get_history( + session_id, + limit=10 +) + +# Clear history +client.sessions.clear_history(session_id) +``` + +## Session Integration + +### Tasks and Sessions + +Use sessions in task workflows: + +```yaml +tools: + - name: get_session + system: + resource: agent + subresource: session + operation: get + + - name: update_session + system: + resource: agent + subresource: session + operation: update + +main: + # Get session context + - tool: get_session + arguments: + session_id: "{{inputs.session_id}}" + + # Use context in prompt + - prompt: + - role: system + content: > + Current task: {{_.context.current_task}} + Last response: {{_.context.last_response}} + - role: user + content: "{{inputs.query}}" + + # Update session + - tool: update_session + arguments: + session_id: "{{inputs.session_id}}" + context: + current_task: "completed" + last_response: _ +``` + +### Session Events + +Handle session-related events: + +```python Python +# Subscribe to session events +client.sessions.subscribe( + session_id, + event_types=["message", "state_change"], + callback=handle_session_event +) + +# Handle session events +async def handle_session_event(event): + if event.type == "message": + print(f"New message in session {event.session_id}") + print(f"Content: {event.data.content}") + elif event.type == "state_change": + print(f"Session {event.session_id} state changed to {event.data.state}") +``` + +## Session Storage + +### Configuration Options + +Configure session storage: + +```python Python +# Configure session storage +session = client.sessions.create( + user_id=user.id, + storage_options={ + "persistence": "permanent", + "encryption": True, + "ttl": 86400 # 24 hours + } +) + +# Set temporary storage +temp_session = client.sessions.create( + user_id=user.id, + storage_options={ + "persistence": "temporary", + "ttl": 3600 # 1 hour + } +) +``` + +### Data Management + +Manage session data: + +```python Python +# Export session data +session_data = client.sessions.export(session_id) + +# Import session data +client.sessions.import_( + session_id, + session_data=session_data +) + +# Archive session +client.sessions.archive(session_id) + +# Delete session +client.sessions.delete(session_id) +``` + +## Best Practices + +1. **Session Management** + - Set appropriate timeouts + - Handle session expiry + - Implement proper cleanup + +2. **Context Handling** + - Maintain relevant state + - Clear unnecessary data + - Handle context updates + +3. **Performance** + - Use efficient storage + - Implement caching + - Handle concurrent sessions + +## Example: Complete Session Management + +Here's a comprehensive example of session management: + +```python Python +class SessionManager: + def __init__(self, client): + self.client = client + + async def create_user_session(self, user_id, device_info): + # Create session + session = await self.client.sessions.create( + user_id=user_id, + metadata={ + "device": device_info["type"], + "platform": device_info["platform"], + "created_at": datetime.now().isoformat() + }, + config={ + "timeout": 3600, + "max_messages": 100, + "context_window": 10 + } + ) + + # Initialize session context + context = await self.client.sessions.set_context( + session.id, + context={ + "state": "initialized", + "current_task": None, + "history": [], + "metadata": { + "start_time": datetime.now().isoformat(), + "message_count": 0 + } + } + ) + + return { + "session": session, + "context": context + } + + async def handle_user_message(self, session_id, message): + # Get session + session = await self.client.sessions.get(session_id) + + # Update context + context = await self.client.sessions.get_context(session_id) + + # Add message to history + history = context.get("history", []) + history.append({ + "role": "user", + "content": message, + "timestamp": datetime.now().isoformat() + }) + + # Update session context + updated_context = await self.client.sessions.update_context( + session_id, + context={ + "state": "processing", + "current_task": "handle_message", + "history": history[-10:], # Keep last 10 messages + "metadata": { + "start_time": context["metadata"]["start_time"], + "message_count": len(history) + } + } + ) + + return { + "session": session, + "context": updated_context + } + + async def end_user_session(self, session_id): + # Get final context + context = await self.client.sessions.get_context(session_id) + + # Export session data + session_data = await self.client.sessions.export(session_id) + + # Archive session + archived = await self.client.sessions.archive(session_id) + + # Store session summary + summary = { + "session_id": session_id, + "start_time": context["metadata"]["start_time"], + "end_time": datetime.now().isoformat(), + "message_count": context["metadata"]["message_count"], + "final_state": context["state"] + } + + return { + "summary": summary, + "data": session_data + } + +# Use the manager +manager = SessionManager(client) + +# Create session +session = await manager.create_user_session( + user_id, + device_info={ + "type": "web", + "platform": "chrome" + } +) + +# Handle message +result = await manager.handle_user_message( + session["session"].id, + "How can I use this feature?" +) + +# End session +summary = await manager.end_user_session(session["session"].id) +print("Session summary:", summary) +``` + +## Next Steps + +1. [Learn about user context](/building-blocks/users/user-context) +2. [Explore user management](/building-blocks/users/user-management) +3. [Understand session management](/building-blocks/sessions/session-management) \ No newline at end of file diff --git a/documentation/development.mdx b/documentation/development.mdx new file mode 100644 index 000000000..0ba0c593e --- /dev/null +++ b/documentation/development.mdx @@ -0,0 +1,97 @@ +--- +title: 'Development' +description: 'Learn how to preview changes locally' +--- + + + **Prerequisite**: Please install Node.js (version 19 or higher) before proceeding. + + +Step 1. Install Mintlify on your OS: + + + +```bash npm +npm i -g mintlify +``` + +```bash yarn +yarn global add mintlify +``` + + + +Step 2. Go to the docs are located (where you can find `mint.json`) and run the following command: + +```bash +mintlify dev +``` + +The documentation website is now available at `http://localhost:3000`. + +### Custom Ports + +Mintlify uses port 3000 by default. You can use the `--port` flag to customize the port Mintlify runs on. For example, use this command to run in port 3333: + +```bash +mintlify dev --port 3333 +``` + +You will see an error like this if you try to run Mintlify in a port that's already taken: + +```md +Error: listen EADDRINUSE: address already in use :::3000 +``` + +## Mintlify Versions + +Each CLI is linked to a specific version of Mintlify. Please update the CLI if your local website looks different than production. + + + +```bash npm +npm i -g mintlify@latest +``` + +```bash yarn +yarn global upgrade mintlify +``` + + + +## Deployment + + + Unlimited editors available under the [Pro + Plan](https://mintlify.com/pricing) and above. + + +You should see the following if the deploy successfully went through: + + + + + +## Troubleshooting + +Here's how to solve some common problems when working with the CLI. + + + + Update to Node v18. Run `mintlify install` and try again. + + +Go to the `C:/Users/Username/.mintlify/` directory and remove the `mint` +folder. Then Open the Git Bash in this location and run `git clone +https://github.com/mintlify/mint.git`. + +Repeat step 3. + + + + Try navigating to the root of your device and delete the ~/.mintlify folder. + Then run `mintlify dev` again. + + + +Curious about what changed in a CLI version? [Check out the CLI changelog.](/changelog/command-line) diff --git a/documentation/favicon.svg b/documentation/favicon.svg new file mode 100755 index 000000000..972328bca --- /dev/null +++ b/documentation/favicon.svg @@ -0,0 +1,5 @@ + + + + + diff --git a/documentation/getting-started/core-concepts.mdx b/documentation/getting-started/core-concepts.mdx new file mode 100644 index 000000000..2fe65a210 --- /dev/null +++ b/documentation/getting-started/core-concepts.mdx @@ -0,0 +1,189 @@ +--- +title: 'Core Concepts' +description: 'Essential concepts and terminology needed to understand Julep' +--- + +## Core Concepts + +Understanding Julep's core concepts is essential for building effective AI applications. This guide covers the fundamental components and how they work together. + +### Agents + +Agents are AI-powered entities that can perform tasks and interact with users. They are the central building blocks of Julep applications. + +```python +agent = client.agents.create( + name="Customer Service Agent", + model="claude-3.5-sonnet", + about="An AI assistant that helps with customer inquiries" +) +``` + +Key aspects of agents: +- **Identity**: Each agent has a name and description that defines its role +- **Model**: The underlying language model (e.g., Claude, GPT-4) +- **Memory**: Ability to maintain context across interactions +- **Tools**: Access to various capabilities through integrated tools + +### Tasks + +Tasks are multi-step workflows that agents can execute. They define a sequence of actions to achieve a specific goal. + +```yaml +name: Process Customer Inquiry +description: Handle a customer question and provide a response + +main: + - prompt: + - role: system + content: "You are a customer service agent." + - role: user + content: "{{inputs.question}}" + + - tool: search_knowledge_base + arguments: + query: "{{_.content}}" + + - prompt: + - role: system + content: "Use this information to answer: {{_.search_results}}" + - role: user + content: "{{inputs.question}}" +``` + +Key aspects of tasks: +- **Structure**: Defined sequence of steps +- **Steps Types**: Various actions like prompts, tool calls, and control flow +- **Context**: Access to inputs and previous step results +- **Tools**: Integration with external services and APIs + +### Sessions + +Sessions maintain the state and context of interactions between users and agents. + +```python +session = client.sessions.create( + agent_id=agent.id, + user_id=user.id, + context_overflow="adaptive" +) + +response = client.sessions.chat( + session_id=session.id, + messages=[{"role": "user", "content": "Hello!"}] +) +``` + +Key aspects of sessions: +- **State Management**: Maintains conversation history +- **Context**: Preserves relevant information across interactions +- **Memory**: Handles long-term and working memory +- **User Association**: Links conversations to specific users + +### Tools + +Tools extend an agent's capabilities by providing access to external functionality. + +```yaml +tools: + - name: search_knowledge_base + type: integration + integration: + provider: elasticsearch + setup: + endpoint: "https://search.example.com" + index: "knowledge_base" +``` + +Types of tools: +1. **User-defined Functions**: Custom functions you implement +2. **System Tools**: Built-in Julep API operations +3. **Integrations**: Pre-built third-party service connections +4. **API Calls**: Direct external API interactions + +### Executions + +Executions are instances of tasks being run with specific inputs. + +```python +execution = client.executions.create( + task_id=task.id, + input={"question": "How do I reset my password?"} +) + +# Monitor execution status +while execution.status not in ['succeeded', 'failed']: + execution = client.executions.get(execution.id) +``` + +Key aspects of executions: +- **State**: Tracks progress and status +- **Input/Output**: Manages data flow +- **History**: Records step-by-step execution +- **Error Handling**: Manages failures and retries + +### Documents + +Documents store information that agents can reference during tasks. + +```python +document = client.agents.docs.create( + agent_id=agent.id, + title="Product Manual", + content="Detailed product information...", + metadata={"category": "documentation"} +) + +# Search documents +results = client.agents.docs.search( + agent_id=agent.id, + text="password reset", + metadata_filter={"category": "documentation"} +) +``` + +Key aspects of documents: +- **Storage**: Persistent knowledge base +- **Search**: Semantic search capabilities +- **Metadata**: Additional context and categorization +- **Versioning**: Document history and updates + +### Putting It All Together + +Here's how these concepts work together in a typical Julep application: + +1. Create an **Agent** with specific capabilities +2. Define **Tasks** the agent can perform +3. Use **Tools** to extend functionality +4. Maintain context with **Sessions** +5. Store knowledge in **Documents** +6. Run **Executions** to complete tasks + + + Julep Core Concepts + + +### Next Steps + +Now that you understand the core concepts, you can: + + + + Learn how to work with agents, tasks, and sessions + + + Explore available tools and integrations + + \ No newline at end of file diff --git a/documentation/getting-started/installation.mdx b/documentation/getting-started/installation.mdx new file mode 100644 index 000000000..c24256d31 --- /dev/null +++ b/documentation/getting-started/installation.mdx @@ -0,0 +1,221 @@ +--- +title: 'Installation' +description: 'Step-by-step installation instructions for different environments' +--- + +## Installation Guide + +This guide covers the installation of Julep in various environments and configurations. + +### Prerequisites + +Before installing Julep, ensure you have: + +- Python 3.8+ or Node.js 16+ installed +- pip (for Python) or npm/bun (for Node.js) package manager +- A Julep API key ([Get one here](https://dashboard.julep.ai)) + +### Package Installation + +#### Python Installation + +1. Using pip: +```bash +pip install julep +``` + +2. Using poetry: +```bash +poetry add julep +``` + +3. Using pipenv: +```bash +pipenv install julep +``` + +#### Node.js Installation + +1. Using npm: +```bash +npm install @julep/sdk +``` + +2. Using yarn: +```bash +yarn add @julep/sdk +``` + +3. Using bun: +```bash +bun add @julep/sdk +``` + +### Environment Setup + +#### Setting up Environment Variables + +It's recommended to use environment variables for sensitive information like API keys: + +1. Create a `.env` file in your project root: +```bash +JULEP_API_KEY=your_api_key_here +JULEP_ENVIRONMENT=production # or development +``` + +2. Load the environment variables in your code: + + + ```python Python + import os + from dotenv import load_dotenv + from julep import Julep + + load_dotenv() + + client = Julep( + api_key=os.getenv('JULEP_API_KEY'), + environment=os.getenv('JULEP_ENVIRONMENT', 'production') + ) + ``` + + ```javascript Node.js + import dotenv from 'dotenv'; + import { Julep } from '@julep/sdk'; + + dotenv.config(); + + const client = new Julep({ + apiKey: process.env.JULEP_API_KEY, + environment: process.env.JULEP_ENVIRONMENT || 'production' + }); + ``` + + +### Docker Installation + +If you prefer using Docker, you can run Julep in a containerized environment: + +1. Create a `Dockerfile`: +```dockerfile +# Python +FROM python:3.11-slim +WORKDIR /app +COPY requirements.txt . +RUN pip install -r requirements.txt +COPY . . +CMD ["python", "your_script.py"] + +# Node.js +FROM node:16-slim +WORKDIR /app +COPY package*.json ./ +RUN npm install +COPY . . +CMD ["node", "your_script.js"] +``` + +2. Build and run the container: +```bash +docker build -t my-julep-app . +docker run -e JULEP_API_KEY=your_api_key_here my-julep-app +``` + +### Local Development Setup + +For local development, you can run Julep locally: + +1. Clone the repository: +```bash +git clone https://github.com/julep-ai/julep.git +cd julep +``` + +2. Create required volumes: +```bash +docker volume create cozo_backup +docker volume create cozo_data +``` + +3. Set up environment: +```bash +cp .env.example .env # Edit this file with your settings +``` + +4. Start the services: +```bash +docker compose --env-file .env --profile temporal-ui --profile single-tenant --profile self-hosted-db up --build +``` + +### Verification + +To verify your installation: + + + ```python Python + from julep import Julep + + client = Julep(api_key="your_api_key") + + # Test connection + agent = client.agents.create( + name="Test Agent", + model="claude-3.5-sonnet", + about="A test agent" + ) + print(f"Successfully created agent: {agent.id}") + ``` + + ```javascript Node.js + import { Julep } from '@julep/sdk'; + + const client = new Julep({ + apiKey: 'your_api_key' + }); + + // Test connection + const agent = await client.agents.create({ + name: "Test Agent", + model: "claude-3.5-sonnet", + about: "A test agent" + }); + console.log(`Successfully created agent: ${agent.id}`); + ``` + + +### Troubleshooting + +Common installation issues and solutions: + +1. **API Key Issues** + - Ensure your API key is valid and properly set in environment variables + - Check if you're using the correct environment (production/development) + +2. **Version Compatibility** + - Make sure you're using compatible versions of Python/Node.js + - Update to the latest SDK version if you encounter issues + +3. **Docker Issues** + - Verify Docker is running and has sufficient resources + - Check if required ports are available and not blocked + +### Next Steps + +Now that you have Julep installed, you can: + + + + Create your first Julep agent and task + + + Learn about Julep's fundamental concepts + + \ No newline at end of file diff --git a/documentation/getting-started/quick-start.mdx b/documentation/getting-started/quick-start.mdx new file mode 100644 index 000000000..eb24a6c47 --- /dev/null +++ b/documentation/getting-started/quick-start.mdx @@ -0,0 +1,189 @@ +--- +title: 'Quick Start Guide' +description: '5-minute guide to create your first Julep agent and task' +--- + +## Quick Start Guide + +This guide will help you get started with Julep in just 5 minutes. You'll learn how to create your first AI agent and execute a simple task. + +### Prerequisites + +- Python 3.8+ or Node.js 16+ +- A Julep API key ([Get one here](https://dashboard.julep.ai)) + +### Step 1: Install Julep + +Choose your preferred language: + + + ```bash Python + pip install julep + ``` + + ```bash Node.js + npm install @julep/sdk + # or + bun add @julep/sdk + ``` + + +### Step 2: Initialize the Client + + + ```python Python + from julep import Julep + + client = Julep(api_key="your_julep_api_key") + ``` + + ```javascript Node.js + import { Julep } from '@julep/sdk'; + + const client = new Julep({ + apiKey: 'your_julep_api_key' + }); + ``` + + +### Step 3: Create Your First Agent + +Let's create a simple AI agent that can help with writing tasks: + + + ```python Python + agent = client.agents.create( + name="Writing Assistant", + model="claude-3.5-sonnet", + about="A helpful AI assistant that specializes in writing and editing." + ) + ``` + + ```javascript Node.js + const agent = await client.agents.create({ + name: "Writing Assistant", + model: "claude-3.5-sonnet", + about: "A helpful AI assistant that specializes in writing and editing." + }); + ``` + + +### Step 4: Create a Simple Task + +Let's create a task that generates a short story based on a given topic: + + + ```python Python + task = client.tasks.create( + agent_id=agent.id, + name="Story Generator", + description="Generate a short story based on a given topic", + main=[ + { + "prompt": [ + { + "role": "system", + "content": "You are a creative story writer." + }, + { + "role": "user", + "content": "Write a short story about {{inputs.topic}}" + } + ] + } + ] + ) + ``` + + ```javascript Node.js + const task = await client.tasks.create( + agent.id, + { + name: "Story Generator", + description: "Generate a short story based on a given topic", + main: [ + { + prompt: [ + { + role: "system", + content: "You are a creative story writer." + }, + { + role: "user", + content: "Write a short story about {{inputs.topic}}" + } + ] + } + ] + } + ); + ``` + + +### Step 5: Execute the Task + +Now let's run the task with a specific topic: + + + ```python Python + execution = client.executions.create( + task_id=task.id, + input={"topic": "a magical garden"} + ) + + # Wait for the execution to complete + while (result := client.executions.get(execution.id)).status not in ['succeeded', 'failed']: + print(result.status) + time.sleep(1) + + if result.status == "succeeded": + print(result.output) + else: + print(f"Error: {result.error}") + ``` + + ```javascript Node.js + const execution = await client.executions.create( + task.id, + { + input: { topic: "a magical garden" } + } + ); + + // Wait for the execution to complete + let result; + while (true) { + result = await client.executions.get(execution.id); + if (result.status === 'succeeded' || result.status === 'failed') break; + console.log(result.status); + await new Promise(resolve => setTimeout(resolve, 1000)); + } + + if (result.status === 'succeeded') { + console.log(result.output); + } else { + console.error(`Error: ${result.error}`); + } + ``` + + +### Next Steps + +Congratulations! You've created your first Julep agent and executed a task. Here's what you can explore next: + + + + Learn about advanced installation options and configurations + + + Understand the fundamental concepts of Julep + + \ No newline at end of file diff --git a/documentation/images/julep-hero-dark.png b/documentation/images/julep-hero-dark.png new file mode 100755 index 000000000..5a40d4f3b Binary files /dev/null and b/documentation/images/julep-hero-dark.png differ diff --git a/documentation/images/julep-hero-light.png b/documentation/images/julep-hero-light.png new file mode 100755 index 000000000..a7c75c4f8 Binary files /dev/null and b/documentation/images/julep-hero-light.png differ diff --git a/documentation/introduction/architecture-overview.mdx b/documentation/introduction/architecture-overview.mdx new file mode 100644 index 000000000..31b52f51c --- /dev/null +++ b/documentation/introduction/architecture-overview.mdx @@ -0,0 +1,117 @@ +--- +title: 'Architecture Overview' +description: 'Technical overview of how Julep components work together' +--- + +## System Components + + + Julep Architecture + + +## Core Components + +### Agents +- AI-powered entities backed by large language models (LLMs) +- Execute tasks and interact with users +- Maintain persistent state and memory +- Can be extended with tools and integrations + +### Sessions +- Stateful interactions between agents and users +- Maintain context across multiple exchanges +- Support long-running conversations +- Handle context management automatically + +### Tasks +- Multi-step, programmatic workflows +- Support various step types: + - Prompts and LLM interactions + - Tool calls and integrations + - Conditional logic and loops + - Parallel execution + +### Tools +Four types of tool integrations: +1. **User-defined Functions** + - Custom function signatures + - Client-side execution + - Flexible implementation + +2. **System Tools** + - Built-in platform capabilities + - Direct access to Julep APIs + - Automatic execution + +3. **Built-in Integrations** + - Pre-configured third-party tools + - Server-side execution + - Managed authentication + +4. **Direct API Calls** + - HTTP/REST endpoints + - Custom API integration + - Runtime parameter support + +## Infrastructure Components + +### Document Store +- Vector database for semantic search +- Document management system +- Support for various file types +- Automatic indexing and retrieval + +### Task Execution Engine +- Distributed task processing +- State management +- Error handling and retries +- Parallel execution support + +### API Layer +- RESTful API endpoints +- SDK support +- Authentication and authorization +- Rate limiting and quotas + +## Data Flow + +1. **Client Interaction** + - SDK or API calls initiate requests + - Authentication and validation + - Request routing + +2. **Task Processing** + - Task decomposition + - Step execution + - State management + - Tool integration + +3. **Response Handling** + - Result aggregation + - Error handling + - Client notification + - State persistence + +## Security Architecture + +### Authentication +- API key-based access +- Role-based permissions +- Session management +- Token validation + +### Data Protection +- Encryption at rest +- Secure communication +- Data isolation +- Access controls + +### Monitoring +- Audit logging +- Performance metrics +- Error tracking +- Usage analytics \ No newline at end of file diff --git a/documentation/introduction/key-features.mdx b/documentation/introduction/key-features.mdx new file mode 100644 index 000000000..28a56d796 --- /dev/null +++ b/documentation/introduction/key-features.mdx @@ -0,0 +1,89 @@ +--- +title: 'Key Features' +description: "Detailed breakdown of Julep's main capabilities and benefits" +--- + +## Core Features + + + + Create agents that maintain context and remember information across multiple interactions. Agents can learn from past conversations and apply that knowledge to future tasks. + + + + Keep track of conversation history and context across multiple interactions. Sessions can be paused, resumed, and maintain their state indefinitely. + + + + Build complex workflows with decision-making capabilities, loops, and conditional logic. Tasks can be as simple or as sophisticated as needed. + + + + Handle long-running tasks that can run indefinitely. Tasks are automatically managed, with built-in support for retries and error handling. + + + +## Advanced Capabilities + + + + Access a wide range of built-in tools and easily integrate with external APIs. Tools can be added to agents to extend their capabilities. + + + + Automatic retry mechanisms for failed steps, message resending, and robust task management keep your workflows running smoothly. + + + + Built-in support for Retrieval-Augmented Generation. Use Julep's document store to build systems that can retrieve and utilize your own data. + + + + Seamlessly integrate with your existing infrastructure using our comprehensive SDKs for Python and Node.js. + + + +## Development Features + +### Workflow Language +Julep provides a powerful YAML-based workflow language that allows you to: +- Define complex multi-step processes +- Handle conditional logic and branching +- Manage parallel execution +- Integrate with external tools and APIs + +### SDK Support +Comprehensive SDKs available for: +- Python with full async support +- Node.js with TypeScript definitions +- RESTful API for other languages + +### Tool Integration +Multiple ways to extend agent capabilities: +- User-defined functions +- System tools +- Built-in integrations +- Direct API calls + +## Enterprise Features + +### Security +- Role-based access control +- Secure API key management +- Data encryption at rest and in transit + +### Scalability +- Distributed task execution +- Automatic load balancing +- Horizontal scaling capabilities + +### Monitoring +- Task execution tracking +- Performance metrics +- Error logging and debugging tools + +### Reliability +- Automatic retry mechanisms +- Error handling +- State persistence +- Task recovery \ No newline at end of file diff --git a/documentation/introduction/what-is-julep.mdx b/documentation/introduction/what-is-julep.mdx new file mode 100644 index 000000000..231b77c09 --- /dev/null +++ b/documentation/introduction/what-is-julep.mdx @@ -0,0 +1,51 @@ +--- +title: 'What is Julep?' +description: 'High-level overview of Julep, its purpose, and key differentiators' +--- + +## Overview + +Julep is a powerful platform for creating AI agents that remember past interactions and can perform complex tasks. Unlike simple chatbots or linear AI workflows, Julep enables the creation of sophisticated agents that can: + +- Maintain long-term memory across conversations +- Execute multi-step tasks with decision-making capabilities +- Integrate with numerous external tools and APIs +- Handle complex workflows with parallel processing + +## Purpose + +While many AI applications are limited to simple, linear chains of prompts and API calls with minimal branching, Julep is built to handle more complex scenarios which: + +- Have multiple steps and decision points +- Make intelligent decisions based on model outputs +- Spawn parallel execution branches +- Utilize multiple tools and integrations +- Run for extended periods + +## Key Differentiators + +### Platform vs Library +Julep is a complete platform that includes: +- A specialized language for describing workflows +- A robust server infrastructure for running those workflows +- SDKs for seamless platform interaction + +### Stateful vs Stateless +Unlike traditional AI frameworks, Julep maintains state through: +- Persistent sessions that remember context +- Long-term agent memory +- Ability to resume and continue tasks + +### Complex Workflows +Julep excels at handling: +- Multi-step processes with conditional logic +- Parallel task execution +- Integration with multiple external services +- Long-running operations with automatic state management + +### Enterprise Ready +Built with production use cases in mind: +- Robust error handling and retry mechanisms +- Automatic task management and orchestration +- Scalable architecture for high-load scenarios +- Security-first design principles \ No newline at end of file diff --git a/documentation/logo/dark.svg b/documentation/logo/dark.svg new file mode 100644 index 000000000..c3f8a565f --- /dev/null +++ b/documentation/logo/dark.svg @@ -0,0 +1,5 @@ + + + + + diff --git a/documentation/logo/light.svg b/documentation/logo/light.svg new file mode 100644 index 000000000..06070bc12 --- /dev/null +++ b/documentation/logo/light.svg @@ -0,0 +1,5 @@ + + + + + diff --git a/documentation/mint.json b/documentation/mint.json new file mode 100644 index 000000000..a4f82b385 --- /dev/null +++ b/documentation/mint.json @@ -0,0 +1,349 @@ +{ + "$schema": "https://mintlify.com/schema.json", + "name": "Julep", + "logo": { + "dark": "/logo/dark.svg", + "light": "/logo/light.svg" + }, + "favicon": "/favicon.svg", + "theme": "quill", + "background": { + "style": "gradient" + }, + "colors": { + "primary": "#004E64", + "light": "#00A5CF", + "dark": "#25A18E", + "background": { + "dark": "#072b3f", + "light": "#F7FCF7" + }, + "anchors": { + "from": "#25A18E", + "to": "#7AE582" + } + }, + "layout": "topnav", + "font": { + "headings": { + "family": "Instrument Sans", + "weight": 500 + }, + "body": { + "family": "Figtree", + "weight": 500 + } + }, + "rounded": "sharp", + "modeToggle": { + "default": "light", + "isHidden": false + }, + "codeBlock": { + "mode": "dark" + }, + "sidebar": { + "items": "card" + }, + "topbar": { + "style": "gradient" + }, + "search": { + "location": "top", + "prompt": "Search Julep docs" + }, + "versions": ["v1", "dev"], + "topbarLinks": [ + { + "name": "Support", + "url": "mailto:developers@julep.ai" + } + ], + "topbarCtaButton": { + "name": "Dashboard", + "url": "https://dashboard.julep.ai" + }, + "tabs": [ + { + "name": "Documentation", + "url": "welcome" + }, + { + "name": "Examples", + "url": "examples" + }, + { + "name": "SDKs", + "url": "sdks" + }, + { + "name": "API Reference", + "url": "api-reference" + } + ], + "anchors": [ + { + "name": "Documentation", + "icon": "book-open", + "iconType": "sharp-duotone-solid", + "url": "/" + }, + { + "name": "Community", + "icon": "discord", + "url": "https://discord.gg/p4c7ehs4vD" + } + ], + "navigation": [ + { + "group": "Introduction", + "pages": [ + "welcome", + "introduction/what-is-julep", + "introduction/key-features", + "introduction/architecture-overview" + ] + }, + { + "group": "Getting Started", + "pages": [ + "getting-started/quick-start", + "getting-started/installation", + "getting-started/core-concepts" + ] + }, + { + "group": "Building Blocks", + "pages": [ + { + "group": "Agents", + "pages": [ + "building-blocks/agents/creating-agents", + "building-blocks/agents/agent-memory", + "building-blocks/agents/agent-tools" + ] + }, + { + "group": "Tasks", + "pages": [ + "building-blocks/tasks/task-basics", + "building-blocks/tasks/workflow-steps", + "building-blocks/tasks/control-flow" + ] + }, + { + "group": "Sessions", + "pages": [ + "building-blocks/sessions/session-management", + "building-blocks/sessions/context-and-state" + ] + }, + { + "group": "Doc Store", + "pages": [ + "building-blocks/doc-store/document-management", + "building-blocks/doc-store/vector-search", + "building-blocks/doc-store/document-integration" + ] + }, + { + "group": "Users", + "pages": [ + "building-blocks/users/user-management", + "building-blocks/users/user-context", + "building-blocks/users/user-sessions" + ] + } + ] + }, + { + "group": "Tools & Integrations", + "pages": [ + "tools/built-in-tools", + "tools/integration-types", + "tools/available-integrations" + ] + }, + { + "group": "Advanced Topics", + "pages": [ + "advanced/error-handling", + "advanced/performance-optimization", + "advanced/security-best-practices" + ] + }, + { + "group": "Examples", + "pages": [ + { + "group": "Getting Started Examples", + "pages": [ + "examples/basic-agent-creation", + "examples/task-workflow-basics", + "examples/tool-integration-demo" + ] + }, + { + "group": "Use Case Examples", + "pages": [ + "examples/customer-service", + "examples/research-assistant", + "examples/document-processing", + "examples/data-analysis" + ] + }, + { + "group": "Advanced Examples", + "pages": [ + "examples/multi-agent-systems", + "examples/complex-workflows", + "examples/integration-patterns" + ] + }, + { + "group": "Cookbooks", + "pages": [ + "examples/quick-solutions", + "examples/industry-solutions", + "examples/community-examples" + ] + } + ] + }, + { + "group": "SDKs", + "pages": [ + "sdks/index", + { + "group": "Python SDK", + "pages": [ + "sdks/python/installation", + { + "group": "Core Components", + "pages": [ + "sdks/python/agents", + "sdks/python/tasks", + "sdks/python/sessions" + ] + }, + "sdks/python/tools-integration", + "sdks/python/advanced-usage", + "sdks/python/reference" + ] + }, + { + "group": "Node.js SDK", + "pages": [ + "sdks/nodejs/installation", + { + "group": "Core Components", + "pages": [ + "sdks/nodejs/agents", + "sdks/nodejs/tasks", + "sdks/nodejs/sessions" + ] + }, + "sdks/nodejs/tools-integration", + "sdks/nodejs/advanced-usage", + "sdks/nodejs/reference" + ] + }, + { + "group": "Common Patterns", + "pages": [ + "sdks/common/error-handling", + "sdks/common/authentication", + "sdks/common/testing" + ] + } + ] + }, + { + "group": "API Reference", + "pages": [ + "api-reference/introduction", + { + "group": "Agent Endpoints", + "pages": [ + "api-reference/agents/create", + "api-reference/agents/update", + "api-reference/agents/delete", + "api-reference/agents/list" + ] + }, + { + "group": "Task Endpoints", + "pages": [ + "api-reference/tasks/create", + "api-reference/tasks/execute", + "api-reference/tasks/status", + "api-reference/tasks/list" + ] + }, + { + "group": "Session Endpoints", + "pages": [ + "api-reference/sessions/create", + "api-reference/sessions/update", + "api-reference/sessions/list" + ] + }, + { + "group": "Tool Endpoints", + "pages": [ + "api-reference/tools/register", + "api-reference/tools/update", + "api-reference/tools/list" + ] + }, + { + "group": "Types", + "pages": [ + "api-reference/types/responses", + "api-reference/types/errors", + "api-reference/types/pagination" + ] + } + ] + } + ], + "footerSocials": { + "x": "https://x.com/julepai", + "github": "https://github.com/julep-ai" + }, + "seo": { + "indexHiddenPages": false + }, + "api": { + "auth": { + "method": "bearer", + "name": "Authorization", + "inputPrefix": "Bearer " + }, + "baseUrl": [ + "https://api.julep.ai/api", + "https://dev.julep.ai/api" + ], + "maintainOrder": false, + "paramFields": { + "expanded": "topLevel" + }, + "request": { + "example": { + "showOptionalParams": true, + "languages": ["python", "javascript"] + } + }, + "playground": { + "disableProxy": false, + "mode": "show" + } + }, + "openapi": [ + "https://dev.julep.ai/api/openapi.json" + ], + "feedback": { + "suggestEdit": true, + "raiseIssue": true + } +} diff --git a/documentation/openapi.yaml b/documentation/openapi.yaml new file mode 120000 index 000000000..1c2a243ef --- /dev/null +++ b/documentation/openapi.yaml @@ -0,0 +1 @@ +../openapi.yaml \ No newline at end of file diff --git a/documentation/sdks/index.mdx b/documentation/sdks/index.mdx new file mode 100644 index 000000000..0fb37b0e7 --- /dev/null +++ b/documentation/sdks/index.mdx @@ -0,0 +1,219 @@ +--- +title: 'Introduction' +description: 'Getting started with Julep SDKs for Python and Node.js' +--- + +The Julep SDKs provide powerful interfaces to interact with Julep's AI agent platform. These SDKs allow you to create, manage, and execute AI agents, tasks, and sessions directly from your applications. + +## Installation + + +```bash Python +# Install using pip +pip install julep-sdk + +# Or using poetry +poetry add julep-sdk +``` + +```bash Node.js +# Install using npm +npm install @julep/sdk + +# Or using yarn +yarn add @julep/sdk + +# Or using bun +bun add @julep/sdk +``` + + +## Basic Usage + + +```python Python +from julep import Julep + +# Initialize the client +client = Julep( + api_key='your_api_key', + environment='production' # or 'development' +) + +# Create an agent +agent = client.agents.create( + name='My First Agent', + model='claude-3.5-sonnet', + about='A helpful AI assistant' +) + +# Create a task +task = client.tasks.create( + agent_id=agent.id, + name='Simple Task', + description='A basic task example', + main=[ + { + 'prompt': 'Hello! How can I help you today?' + } + ] +) + +# Execute the task +execution = client.executions.create(task_id=task.id) +``` + +```javascript Node.js +const { Julep } = require('@julep/sdk'); + +// Initialize the client +const client = new Julep({ + apiKey: 'your_api_key', + environment: 'production' // or 'development' +}); + +// Create an agent +const agent = await client.agents.create({ + name: 'My First Agent', + model: 'claude-3.5-sonnet', + about: 'A helpful AI assistant' +}); + +// Create a task +const task = await client.tasks.create(agent.id, { + name: 'Simple Task', + description: 'A basic task example', + main: [ + { + prompt: 'Hello! How can I help you today?' + } + ] +}); + +// Execute the task +const execution = await client.executions.create(task.id); +``` + + +## Features + +- **Comprehensive API Coverage**: Access all Julep platform features +- **Type Safety**: Built with TypeScript (Node.js) and type hints (Python) +- **Modern Async Support**: Promise-based interface in Node.js and optional async support in Python +- **Error Handling**: Detailed error information and handling +- **Automatic Retries**: Built-in retry mechanism for failed requests + +## SDK Documentation + + + + Get started with the Python SDK + + + Get started with the Node.js SDK + + + +## Core Components + + + + + + Learn how to create and manage AI agents with Python + + + Create and execute complex AI workflows in Python + + + Manage stateful conversations with agents using Python + + + Extend your agents with tools and integrations in Python + + + + + + + + Learn how to create and manage AI agents with Node.js + + + Create and execute complex AI workflows in Node.js + + + Manage stateful conversations with agents using Node.js + + + Extend your agents with tools and integrations in Node.js + + + + + +## Additional Resources + + + + Complete API reference documentation + + + Sample code and use cases + + + Learn advanced patterns and best practices + + \ No newline at end of file diff --git a/documentation/sdks/nodejs/advanced-usage.mdx b/documentation/sdks/nodejs/advanced-usage.mdx new file mode 100644 index 000000000..8cd84211a --- /dev/null +++ b/documentation/sdks/nodejs/advanced-usage.mdx @@ -0,0 +1,339 @@ +--- +title: 'Advanced Usage' +description: 'Advanced patterns and best practices for the Node.js SDK' +--- + +This guide covers advanced usage patterns and best practices for the Julep Node.js SDK. + +## Parallel Task Execution + +Execute multiple tasks in parallel for better performance: + +```javascript +// Create multiple tasks +const tasks = await Promise.all([ + client.tasks.create(agentId, { + name: 'Task 1', + main: [/* ... */] + }), + client.tasks.create(agentId, { + name: 'Task 2', + main: [/* ... */] + }) +]); + +// Execute tasks in parallel +const executions = await Promise.all( + tasks.map(task => client.executions.create(task.id)) +); + +// Wait for all executions to complete +const results = await Promise.all( + executions.map(async execution => { + let status; + do { + status = await client.executions.get(execution.id); + await new Promise(resolve => setTimeout(resolve, 1000)); + } while (status.status !== 'succeeded' && status.status !== 'failed'); + return status; + }) +); +``` + +## Custom Error Handling + +Implement robust error handling with retries: + +```javascript +class RetryableError extends Error { + constructor(message, retryAfter = 1000) { + super(message); + this.name = 'RetryableError'; + this.retryAfter = retryAfter; + } +} + +async function withRetry(fn, maxRetries = 3, initialDelay = 1000) { + let lastError; + let delay = initialDelay; + + for (let attempt = 0; attempt < maxRetries; attempt++) { + try { + return await fn(); + } catch (error) { + lastError = error; + + if (error.name === 'ValidationError') { + throw error; // Don't retry validation errors + } + + if (error.status === 429) { // Rate limit + delay = error.retryAfter || delay * 2; + } else if (error.status >= 500) { // Server error + delay = delay * 2; + } else { + throw error; // Don't retry other errors + } + + await new Promise(resolve => setTimeout(resolve, delay)); + } + } + + throw lastError; +} + +// Usage example +const createAgentWithRetry = async () => { + return await withRetry(async () => { + return await client.agents.create({ + name: 'Resilient Agent', + model: 'claude-3.5-sonnet' + }); + }); +}; +``` + +## Event Streaming + +Handle real-time updates from task executions: + +```javascript +const { EventEmitter } = require('events'); + +class ExecutionStream extends EventEmitter { + constructor(client, executionId, pollInterval = 1000) { + super(); + this.client = client; + this.executionId = executionId; + this.pollInterval = pollInterval; + this.isRunning = false; + } + + async start() { + this.isRunning = true; + while (this.isRunning) { + try { + const status = await this.client.executions.get(this.executionId); + this.emit('update', status); + + if (status.status === 'succeeded' || status.status === 'failed') { + this.isRunning = false; + this.emit('end', status); + break; + } + + await new Promise(resolve => setTimeout(resolve, this.pollInterval)); + } catch (error) { + this.emit('error', error); + this.isRunning = false; + break; + } + } + } + + stop() { + this.isRunning = false; + } +} + +// Usage example +const stream = new ExecutionStream(client, executionId); + +stream.on('update', status => { + console.log('Execution status:', status.status); +}); + +stream.on('end', status => { + console.log('Execution completed:', status); +}); + +stream.on('error', error => { + console.error('Execution error:', error); +}); + +stream.start(); +``` + +## Batch Processing + +Process large amounts of data efficiently: + +```javascript +async function processBatch(items, batchSize = 10) { + const batches = []; + for (let i = 0; i < items.length; i += batchSize) { + batches.push(items.slice(i, i + batchSize)); + } + + const results = []; + for (const batch of batches) { + const batchResults = await Promise.all( + batch.map(async item => { + try { + const execution = await client.executions.create(taskId, { + input: { item } + }); + return { item, execution }; + } catch (error) { + return { item, error }; + } + }) + ); + results.push(...batchResults); + + // Optional: Add delay between batches + await new Promise(resolve => setTimeout(resolve, 1000)); + } + + return results; +} + +// Usage example +const items = ['item1', 'item2', 'item3', /* ... */]; +const results = await processBatch(items, 5); +``` + +## Custom Task Middleware + +Add custom middleware to task executions: + +```javascript +class TaskMiddleware { + constructor(client) { + this.client = client; + this.middlewares = []; + } + + use(fn) { + this.middlewares.push(fn); + return this; + } + + async execute(taskId, input) { + let execution = await this.client.executions.create(taskId, { input }); + + for (const middleware of this.middlewares) { + execution = await middleware(execution, this.client); + } + + return execution; + } +} + +// Usage example +const middleware = new TaskMiddleware(client); + +// Add logging middleware +middleware.use(async (execution, client) => { + console.log(`Execution ${execution.id} started`); + const result = await client.executions.get(execution.id); + console.log(`Execution ${execution.id} completed:`, result.status); + return result; +}); + +// Add error handling middleware +middleware.use(async (execution, client) => { + try { + return await client.executions.get(execution.id); + } catch (error) { + console.error(`Execution ${execution.id} failed:`, error); + throw error; + } +}); + +// Execute task with middleware +const result = await middleware.execute(taskId, { data: 'test' }); +``` + +## Advanced Session Management + +Implement sophisticated session management: + +```javascript +class SessionManager { + constructor(client) { + this.client = client; + this.sessions = new Map(); + } + + async getOrCreateSession(userId, agentId) { + if (this.sessions.has(userId)) { + const session = this.sessions.get(userId); + try { + await this.client.sessions.get(session.id); + return session; + } catch (error) { + this.sessions.delete(userId); + } + } + + const session = await this.client.sessions.create({ + user_id: userId, + agent_id: agentId, + context_overflow: 'adaptive' + }); + + this.sessions.set(userId, session); + return session; + } + + async chat(userId, message) { + const session = await this.getOrCreateSession(userId); + return await this.client.sessions.chat(session.id, { + messages: [{ role: 'user', content: message }] + }); + } + + async cleanup(maxAge = 24 * 60 * 60 * 1000) { + const now = Date.now(); + for (const [userId, session] of this.sessions) { + if (now - new Date(session.created_at).getTime() > maxAge) { + await this.client.sessions.delete(session.id); + this.sessions.delete(userId); + } + } + } +} + +// Usage example +const sessionManager = new SessionManager(client); + +// Chat with automatic session management +const response = await sessionManager.chat(userId, 'Hello!'); + +// Cleanup old sessions +await sessionManager.cleanup(); +``` + +## Next Steps + + + + Complete API documentation + + + Real-world examples + + + Common error patterns + + + Testing strategies + + \ No newline at end of file diff --git a/documentation/sdks/nodejs/agents.mdx b/documentation/sdks/nodejs/agents.mdx new file mode 100644 index 000000000..46e1d428a --- /dev/null +++ b/documentation/sdks/nodejs/agents.mdx @@ -0,0 +1,182 @@ +--- +title: 'Agents' +description: 'Create and manage AI agents with the Node.js SDK' +--- + +Agents are the core building blocks in Julep. They are AI-powered entities that can execute tasks and interact with users through sessions. + +## Creating an Agent + +```javascript +const agent = await client.agents.create({ + name: 'Customer Support Agent', + model: 'claude-3.5-sonnet', + about: 'A helpful customer support agent that assists users with their queries', + metadata: { + department: 'support', + language: 'english' + } +}); +``` + +## Retrieving Agents + +```javascript +// Get a specific agent +const agent = await client.agents.get(agentId); + +// List all agents +const agents = await client.agents.list({ + limit: 10, + offset: 0 +}); + +// Search agents +const searchResults = await client.agents.search({ + query: 'support', + metadata: { + department: 'support' + } +}); +``` + +## Updating Agents + +```javascript +const updatedAgent = await client.agents.update(agentId, { + name: 'Senior Support Agent', + metadata: { + department: 'support', + seniority: 'senior' + } +}); +``` + +## Deleting Agents + +```javascript +await client.agents.delete(agentId); +``` + +## Managing Agent Documents + +Agents can be associated with documents that provide context for their tasks: + +```javascript +// Add a document +const document = await client.agents.docs.create(agentId, { + title: 'Support Guidelines', + content: 'Here are the guidelines for customer support...', + metadata: { + category: 'guidelines', + version: '1.0' + } +}); + +// Search documents +const docs = await client.agents.docs.search(agentId, { + query: 'refund policy', + metadata: { + category: 'policy' + } +}); + +// Delete a document +await client.agents.docs.delete(agentId, documentId); +``` + +## Adding Tools to Agents + +Extend your agent's capabilities by adding tools: + +```javascript +// Add a web search tool +const tool = await client.agents.tools.create(agentId, { + name: 'web_search', + description: 'Search the web for information', + integration: { + provider: 'brave', + method: 'search', + setup: { + api_key: process.env.BRAVE_API_KEY + } + } +}); + +// Add a custom function tool +const customTool = await client.agents.tools.create(agentId, { + name: 'calculate_price', + description: 'Calculate the final price including tax', + type: 'function', + function: { + parameters: { + type: 'object', + properties: { + base_price: { + type: 'number', + description: 'Base price before tax' + }, + tax_rate: { + type: 'number', + description: 'Tax rate as a decimal' + } + }, + required: ['base_price', 'tax_rate'] + } + } +}); +``` + +## Error Handling + +The SDK uses custom error classes for better error handling: + +```javascript +try { + const agent = await client.agents.create({ + name: 'Test Agent', + model: 'invalid-model' + }); +} catch (error) { + if (error.name === 'ValidationError') { + console.error('Invalid model specified:', error.message); + } else if (error.name === 'ApiError') { + console.error('API error:', error.message, error.status); + } else { + console.error('Unexpected error:', error); + } +} +``` + +## Next Steps + + + + Learn how to create and execute tasks + + + Manage agent sessions + + + Add more capabilities to your agents + + + Explore advanced patterns + + \ No newline at end of file diff --git a/documentation/sdks/nodejs/installation.mdx b/documentation/sdks/nodejs/installation.mdx new file mode 100644 index 000000000..2e8835fce --- /dev/null +++ b/documentation/sdks/nodejs/installation.mdx @@ -0,0 +1,132 @@ +--- +title: 'Installation & Setup' +description: 'Get started with the Julep Node.js SDK' +--- + +## Installation + +The Julep Node.js SDK can be installed using npm, yarn, or bun: + +```bash +# Using npm +npm install @julep/sdk + +# Using yarn +yarn add @julep/sdk + +# Using bun +bun add @julep/sdk +``` + +## Configuration + +After installation, you'll need to configure the SDK with your API key: + +```javascript +const { Julep } = require('@julep/sdk'); +// Or using ES modules +import { Julep } from '@julep/sdk'; + +const client = new Julep({ + apiKey: 'your_api_key', + environment: 'production', // or 'development' + // Optional configuration + timeout: 30000, // Request timeout in milliseconds + retries: 3, // Number of retries for failed requests + baseUrl: 'https://api.julep.ai' // Custom API endpoint if needed +}); +``` + +## Environment Variables + +We recommend using environment variables to manage your API key securely: + +```javascript +// Load environment variables +require('dotenv').config(); + +const client = new Julep({ + apiKey: process.env.JULEP_API_KEY, + environment: process.env.JULEP_ENVIRONMENT || 'production' +}); +``` + +Example `.env` file: +```plaintext +JULEP_API_KEY=your_api_key_here +JULEP_ENVIRONMENT=production +``` + +## TypeScript Support + +The SDK is written in TypeScript and includes type definitions out of the box. No additional installation is required for TypeScript support. + +```typescript +import { Julep, Agent, Task, Execution } from '@julep/sdk'; + +const client = new Julep({ + apiKey: process.env.JULEP_API_KEY +}); + +async function createAgent(): Promise { + return await client.agents.create({ + name: 'My Agent', + model: 'claude-3.5-sonnet', + about: 'A helpful AI assistant' + }); +} +``` + +## Verification + +To verify your installation and configuration, you can run a simple test: + +```javascript +async function testConnection() { + try { + const agent = await client.agents.create({ + name: 'Test Agent', + model: 'claude-3.5-sonnet', + about: 'Testing the SDK setup' + }); + console.log('Successfully connected to Julep!', agent); + } catch (error) { + console.error('Connection test failed:', error); + } +} + +testConnection(); +``` + +## Next Steps + + + + Learn how to create and manage AI agents + + + Create and execute tasks with your agents + + + Manage conversational sessions + + + Add capabilities to your agents + + \ No newline at end of file diff --git a/documentation/sdks/nodejs/reference.mdx b/documentation/sdks/nodejs/reference.mdx new file mode 100644 index 000000000..c62afb545 --- /dev/null +++ b/documentation/sdks/nodejs/reference.mdx @@ -0,0 +1,8 @@ +--- +title: 'Node.js SDK Reference' +description: 'Complete reference documentation for the Node.js SDK' +--- + +import Content from "/snippets/node-sdk.mdx" + + diff --git a/documentation/sdks/nodejs/sessions.mdx b/documentation/sdks/nodejs/sessions.mdx new file mode 100644 index 000000000..3df4eca33 --- /dev/null +++ b/documentation/sdks/nodejs/sessions.mdx @@ -0,0 +1,218 @@ +--- +title: 'Sessions' +description: 'Manage conversational sessions with the Node.js SDK' +--- + +Sessions in Julep enable persistent, stateful interactions between users and agents. They maintain context across multiple exchanges and can be used to build conversational interfaces. + +## Creating Sessions + +```javascript +// Create a new session +const session = await client.sessions.create({ + agent_id: agentId, + user_id: userId, // Optional + metadata: { + channel: 'web', + language: 'english' + }, + context_overflow: 'adaptive' // or 'truncate' or 'summarize' +}); +``` + +## Session Chat + +```javascript +// Send a message and get a response +const response = await client.sessions.chat(sessionId, { + messages: [ + { + role: 'user', + content: 'Hello! Can you help me with my order?' + } + ] +}); + +// Continue the conversation in the same session +const followUp = await client.sessions.chat(sessionId, { + messages: [ + { + role: 'user', + content: 'I need to change my shipping address.' + } + ] +}); +``` + +## Managing Context + +Sessions automatically maintain context, but you can also manage it manually: + +```javascript +// Add context to the session +await client.sessions.update(sessionId, { + metadata: { + order_id: '12345', + customer_tier: 'premium' + } +}); + +// Get session history +const history = await client.sessions.history(sessionId, { + limit: 10, + offset: 0 +}); +``` + +## Session Tools + +Tools can be added specifically for a session: + +```javascript +// Add a session-specific tool +await client.sessions.tools.create(sessionId, { + name: 'check_order_status', + description: 'Check the status of an order', + type: 'function', + function: { + parameters: { + type: 'object', + properties: { + order_id: { + type: 'string', + description: 'The order ID to check' + } + }, + required: ['order_id'] + } + } +}); +``` + +## Session Documents + +Add relevant documents to the session for context: + +```javascript +// Add a document to the session +const document = await client.sessions.docs.create(sessionId, { + title: 'Order Details', + content: 'Order #12345: 2 items, shipping to...', + metadata: { + order_id: '12345', + type: 'order_details' + } +}); + +// Search session documents +const docs = await client.sessions.docs.search(sessionId, { + query: 'shipping policy', + metadata: { + type: 'policy' + } +}); +``` + +## Managing Sessions + +```javascript +// Get a specific session +const session = await client.sessions.get(sessionId); + +// List all sessions +const sessions = await client.sessions.list({ + limit: 10, + offset: 0, + agent_id: agentId // Optional filter +}); + +// Update a session +const updatedSession = await client.sessions.update(sessionId, { + metadata: { + status: 'resolved' + } +}); + +// Delete a session +await client.sessions.delete(sessionId); +``` + +## Error Handling + +```javascript +try { + const response = await client.sessions.chat(sessionId, { + messages: [ + { + role: 'user', + content: 'Hello!' + } + ] + }); +} catch (error) { + if (error.name === 'SessionError') { + console.error('Session error:', error.message); + } else if (error.name === 'ApiError') { + console.error('API error:', error.message, error.status); + } else { + console.error('Unexpected error:', error); + } +} +``` + +## Context Overflow Strategies + +Julep provides different strategies for handling context overflow: + +```javascript +// Adaptive strategy (default) +const adaptiveSession = await client.sessions.create({ + agent_id: agentId, + context_overflow: 'adaptive' +}); + +// Truncate strategy +const truncateSession = await client.sessions.create({ + agent_id: agentId, + context_overflow: 'truncate' +}); + +// Summarize strategy +const summarizeSession = await client.sessions.create({ + agent_id: agentId, + context_overflow: 'summarize' +}); +``` + +## Next Steps + + + + Add tools to your sessions + + + Explore advanced patterns + + + View the complete API reference + + + See real-world examples + + \ No newline at end of file diff --git a/documentation/sdks/nodejs/tasks.mdx b/documentation/sdks/nodejs/tasks.mdx new file mode 100644 index 000000000..70cf63389 --- /dev/null +++ b/documentation/sdks/nodejs/tasks.mdx @@ -0,0 +1,217 @@ +--- +title: 'Tasks' +description: 'Create and manage tasks with the Node.js SDK' +--- + +Tasks are multi-step workflows that agents can execute. They can include prompts, tool calls, conditional logic, and more. + +## Creating Tasks + +Tasks can be created using either YAML or JavaScript objects: + +```javascript +// Using a JavaScript object +const task = await client.tasks.create(agentId, { + name: 'Customer Support Task', + description: 'Handle customer support requests', + main: [ + { + prompt: [ + { + role: 'system', + content: 'You are a helpful customer support agent.' + }, + { + role: 'user', + content: '{{_.user_query}}' + } + ] + }, + { + tool: 'web_search', + arguments: { + query: '{{_.user_query}}' + } + } + ] +}); + +// Using YAML +const taskYaml = ` +name: Customer Support Task +description: Handle customer support requests +main: + - prompt: + - role: system + content: You are a helpful customer support agent. + - role: user + content: "{{_.user_query}}" + - tool: web_search + arguments: + query: "{{_.user_query}}" +`; + +const task = await client.tasks.create(agentId, yaml.parse(taskYaml)); +``` + +## Task Steps + +Tasks can include various types of steps: + +```javascript +const task = await client.tasks.create(agentId, { + name: 'Complex Task', + description: 'A task with multiple step types', + main: [ + // Prompt step + { + prompt: 'Analyze the following data: {{_.data}}' + }, + + // Tool call step + { + tool: 'web_search', + arguments: { + query: '{{_.search_query}}' + } + }, + + // Evaluate step + { + evaluate: { + average_score: 'sum(_.scores) / len(_.scores)' + } + }, + + // Conditional step + { + if: '_.score > 0.8', + then: [ + { log: 'High score achieved' } + ], + else: [ + { error: 'Score too low' } + ] + }, + + // Iteration step + { + foreach: { + in: '_.items', + do: [ + { log: 'Processing item {{_}}' } + ] + } + }, + + // Parallel execution + { + parallel: [ + { + tool: 'web_search', + arguments: { query: 'query1' } + }, + { + tool: 'web_search', + arguments: { query: 'query2' } + } + ] + } + ] +}); +``` + +## Executing Tasks + +```javascript +// Execute a task +const execution = await client.executions.create(taskId, { + input: { + user_query: 'How do I reset my password?' + } +}); + +// Get execution status +const status = await client.executions.get(execution.id); + +// Wait for execution to complete +while (status.status !== 'succeeded' && status.status !== 'failed') { + await new Promise(resolve => setTimeout(resolve, 1000)); + const updatedStatus = await client.executions.get(execution.id); + console.log('Execution status:', updatedStatus.status); +} +``` + +## Managing Tasks + +```javascript +// Get a specific task +const task = await client.tasks.get(taskId); + +// List all tasks +const tasks = await client.tasks.list({ + limit: 10, + offset: 0 +}); + +// Update a task +const updatedTask = await client.tasks.update(taskId, { + description: 'Updated task description' +}); + +// Delete a task +await client.tasks.delete(taskId); +``` + +## Error Handling + +```javascript +try { + const execution = await client.executions.create(taskId, { + input: { + user_query: 'How do I reset my password?' + } + }); +} catch (error) { + if (error.name === 'ValidationError') { + console.error('Invalid task configuration:', error.message); + } else if (error.name === 'ExecutionError') { + console.error('Execution failed:', error.message); + } else { + console.error('Unexpected error:', error); + } +} +``` + +## Next Steps + + + + Learn about session management + + + Add tools to your tasks + + + Explore advanced patterns + + + View the complete API reference + + \ No newline at end of file diff --git a/documentation/sdks/nodejs/tools-integration.mdx b/documentation/sdks/nodejs/tools-integration.mdx new file mode 100644 index 000000000..2a179c7a0 --- /dev/null +++ b/documentation/sdks/nodejs/tools-integration.mdx @@ -0,0 +1,262 @@ +--- +title: 'Tools Integration' +description: 'Add powerful capabilities to your agents with tools' +--- + +Tools in Julep extend your agents' capabilities by allowing them to interact with external services and perform specific functions. There are several types of tools available: + +## Tool Types + +1. **User-defined Functions**: Custom functions that you implement +2. **System Tools**: Built-in tools for interacting with Julep's APIs +3. **Integrations**: Pre-built integrations with third-party services +4. **Direct API Calls**: Make HTTP requests to external APIs + +## User-defined Functions + +Create custom tools that your agents can use: + +```javascript +// Create a custom function tool +const tool = await client.agents.tools.create(agentId, { + name: 'calculate_discount', + description: 'Calculate the final price after applying a discount', + type: 'function', + function: { + parameters: { + type: 'object', + properties: { + original_price: { + type: 'number', + description: 'Original price before discount' + }, + discount_percentage: { + type: 'number', + description: 'Discount percentage (0-100)' + } + }, + required: ['original_price', 'discount_percentage'] + } + } +}); +``` + +## System Tools + +Use built-in tools to interact with Julep's APIs: + +```javascript +// Add a system tool for listing agents +const systemTool = await client.agents.tools.create(agentId, { + name: 'list_agent_docs', + description: 'List all documents for the given agent', + type: 'system', + system: { + resource: 'agent', + subresource: 'doc', + operation: 'list' + } +}); +``` + +## Built-in Integrations + +Julep provides several pre-built integrations: + +### Brave Search Integration + +```javascript +// Add Brave Search integration +const braveSearch = await client.agents.tools.create(agentId, { + name: 'web_search', + description: 'Search the web for information', + integration: { + provider: 'brave', + method: 'search', + setup: { + api_key: process.env.BRAVE_API_KEY + } + } +}); +``` + +### Email Integration + +```javascript +// Add email integration +const emailTool = await client.agents.tools.create(agentId, { + name: 'send_email', + description: 'Send an email', + integration: { + provider: 'email', + setup: { + host: 'smtp.example.com', + port: 587, + user: process.env.EMAIL_USER, + password: process.env.EMAIL_PASSWORD + } + } +}); +``` + +### Weather Integration + +```javascript +// Add weather integration +const weatherTool = await client.agents.tools.create(agentId, { + name: 'check_weather', + description: 'Get weather information', + integration: { + provider: 'weather', + setup: { + openweathermap_api_key: process.env.OPENWEATHER_API_KEY + } + } +}); +``` + +### Wikipedia Integration + +```javascript +// Add Wikipedia integration +const wikiTool = await client.agents.tools.create(agentId, { + name: 'wiki_search', + description: 'Search Wikipedia articles', + integration: { + provider: 'wikipedia' + } +}); +``` + +## Direct API Calls + +Make direct HTTP requests to external APIs: + +```javascript +// Add a direct API call tool +const apiTool = await client.agents.tools.create(agentId, { + name: 'github_stars', + description: 'Get GitHub repository stars', + type: 'api_call', + api_call: { + method: 'GET', + url: 'https://api.github.com/repos/{{owner}}/{{repo}}', + headers: { + Authorization: 'Bearer {{github_token}}' + } + } +}); +``` + +## Using Tools in Tasks + +Once tools are added to an agent, they can be used in tasks: + +```javascript +const task = await client.tasks.create(agentId, { + name: 'Research Task', + description: 'Research a topic using multiple tools', + main: [ + // Use web search + { + tool: 'web_search', + arguments: { + query: '{{_.topic}}' + } + }, + + // Use Wikipedia + { + tool: 'wiki_search', + arguments: { + query: '{{_.topic}}' + } + }, + + // Send results via email + { + tool: 'send_email', + arguments: { + to: '{{_.email}}', + subject: 'Research Results: {{_.topic}}', + body: '{{_.results}}' + } + } + ] +}); +``` + +## Tool Management + +```javascript +// List tools for an agent +const tools = await client.agents.tools.list(agentId); + +// Get a specific tool +const tool = await client.agents.tools.get(agentId, toolId); + +// Update a tool +const updatedTool = await client.agents.tools.update(agentId, toolId, { + description: 'Updated tool description' +}); + +// Delete a tool +await client.agents.tools.delete(agentId, toolId); +``` + +## Error Handling + +```javascript +try { + const tool = await client.agents.tools.create(agentId, { + name: 'web_search', + integration: { + provider: 'brave', + setup: { + api_key: process.env.BRAVE_API_KEY + } + } + }); +} catch (error) { + if (error.name === 'ValidationError') { + console.error('Invalid tool configuration:', error.message); + } else if (error.name === 'IntegrationError') { + console.error('Integration setup failed:', error.message); + } else { + console.error('Unexpected error:', error); + } +} +``` + +## Next Steps + + + + Learn advanced patterns and best practices + + + View the complete API reference + + + See real-world examples + + + Learn common integration patterns + + \ No newline at end of file diff --git a/documentation/sdks/python/advanced-usage.mdx b/documentation/sdks/python/advanced-usage.mdx new file mode 100644 index 000000000..f4e11eee3 --- /dev/null +++ b/documentation/sdks/python/advanced-usage.mdx @@ -0,0 +1,121 @@ +--- +title: 'Advanced Usage' +description: 'Advanced patterns and best practices for the Python SDK' +--- + +## Async Operations + +Use the async client for better performance: + +```python +from julep import AsyncJulep +import asyncio + +async def main(): + client = AsyncJulep(api_key="your_julep_api_key") + + # Create multiple agents concurrently + agents = await asyncio.gather(*[ + client.agents.create(name=f"Agent {i}") + for i in range(5) + ]) + + # Execute multiple tasks concurrently + executions = await asyncio.gather(*[ + client.executions.create(task_id=task.id) + for task in tasks + ]) + +if __name__ == "__main__": + asyncio.run(main()) +``` + +## Complex Workflows + +Create sophisticated task workflows: + +```yaml +name: Advanced Workflow +description: Complex task with multiple steps and error handling + +tools: + - name: web_search + type: integration + integration: + provider: brave + method: search + + - name: process_data + type: function + function: + parameters: + type: object + properties: + data: + type: array + items: + type: string + +main: + # Parallel processing with error handling + - try: + - map_reduce: + over: _.topics + map: + - tool: web_search + arguments: + query: _ + parallelism: 5 + catch: + - log: Search failed + - return: {"error": "Search operation failed"} + + # Conditional branching + - if: len(_.search_results) > 0 + then: + - evaluate: + processed_data: process_results(_.search_results) + else: + - return: {"error": "No results found"} + + # Custom aggregation + - evaluate: + summary: aggregate_results(_.processed_data) + confidence: calculate_confidence(_.processed_data) + + # Dynamic tool selection + - switch: + - case: _.confidence > 0.8 + then: + - tool: high_confidence_processor + - case: _.confidence > 0.5 + then: + - tool: medium_confidence_processor + - case: _ + then: + - tool: low_confidence_processor +``` + +## Custom Tool Implementation + + + Work in progress. We're working on a way to allow you to implement your own tools. + + +## Advanced Error Handling + + + Work in progress. We're working on a way to handle errors in a more robust way. + + +## Performance Optimization + + + Work in progress. We're working on a way to optimize the performance of the SDK. + + +## Testing Strategies + + + Work in progress. We're working on a way to test the SDK. + \ No newline at end of file diff --git a/documentation/sdks/python/agents.mdx b/documentation/sdks/python/agents.mdx new file mode 100644 index 000000000..058b1f312 --- /dev/null +++ b/documentation/sdks/python/agents.mdx @@ -0,0 +1,118 @@ +--- +title: 'Working with Agents' +description: 'Learn how to create and manage AI agents using the Python SDK' +--- + +## Creating an Agent + +Create an AI agent with specific capabilities: + +```python +agent = client.agents.create( + name="Research Assistant", + model="claude-3.5-sonnet", # or any supported model + about="A helpful research assistant that can search and summarize information.", + metadata={ + "expertise": "research", + "language": "english" + } +) +``` + +## Retrieving Agents + +```python +# Get a specific agent +agent = client.agents.get(agent_id="agent_123") + +# List all agents +agents = client.agents.list( + limit=10, + offset=0, + metadata_filter={"expertise": "research"} +) +``` + +## Updating Agents + +```python +updated_agent = client.agents.update( + agent_id="agent_123", + name="Advanced Research Assistant", + metadata={"expertise": ["research", "analysis"]} +) +``` + +## Managing Agent Tools + +Add capabilities to your agent by attaching tools: + +```python +# Add a web search tool +client.agents.tools.create( + agent_id=agent.id, + name="web_search", + description="Search the web for information", + integration={ + "provider": "brave", + "method": "search", + "setup": {"api_key": "your_brave_api_key"} + } +) + +# List agent's tools +tools = client.agents.tools.list(agent_id=agent.id) + +# Remove a tool +client.agents.tools.delete( + agent_id=agent.id, + tool_id="tool_123" +) +``` + +## Working with Documents + +Manage documents associated with your agent: + +```python +# Add a document +doc = client.agents.docs.create( + agent_id=agent.id, + title="Research Paper", + content="Content of the research paper...", + metadata={"category": "science"} +) + +# Search documents +results = client.agents.docs.search( + agent_id=agent.id, + text="quantum physics", + metadata_filter={"category": "science"}, + limit=5 +) + +# Delete a document +client.agents.docs.delete( + agent_id=agent.id, + doc_id="doc_123" +) +``` + +## Deleting Agents + +```python +client.agents.delete(agent_id="agent_123") +``` + +## Error Handling + +```python +from julep.exceptions import JulepError, AgentNotFoundError + +try: + agent = client.agents.get("nonexistent_id") +except AgentNotFoundError: + print("Agent not found") +except JulepError as e: + print(f"An error occurred: {e}") +``` \ No newline at end of file diff --git a/documentation/sdks/python/installation.mdx b/documentation/sdks/python/installation.mdx new file mode 100644 index 000000000..b6fdc54d3 --- /dev/null +++ b/documentation/sdks/python/installation.mdx @@ -0,0 +1,68 @@ +--- +title: 'Installation & Setup' +description: 'Getting started with the Python SDK' +--- + +## Installation + +Install the Julep Python SDK using pip: + +```bash +pip install julep +``` + +## Quick Setup + +```python +from julep import Julep + +# Initialize the client +client = Julep(api_key="your_julep_api_key") +``` + +## Environment Setup + +You can also configure the client using environment variables: + +```bash +export JULEP_API_KEY=your_julep_api_key +export JULEP_ENVIRONMENT=production # or development +``` + +Then initialize without parameters: + +```python +from julep import Julep + +client = Julep() # Will use environment variables +``` + +## Configuration Options + +The Julep client can be configured with several options: + +```python +client = Julep( + api_key="your_julep_api_key", + environment="production", # or "development" + base_url="https://api.julep.ai", # Optional: custom API endpoint + timeout=30 # Optional: custom timeout in seconds +) +``` + +## Async Support + +Julep also provides an async client for use with asyncio: + +```python +from julep import AsyncJulep + +async def main(): + client = AsyncJulep(api_key="your_julep_api_key") + # Use the client asynchronously + agent = await client.agents.create(name="My Agent") + +# Run with asyncio +import asyncio +asyncio.run(main()) +``` \ No newline at end of file diff --git a/documentation/sdks/python/reference.mdx b/documentation/sdks/python/reference.mdx new file mode 100644 index 000000000..44f3f3644 --- /dev/null +++ b/documentation/sdks/python/reference.mdx @@ -0,0 +1,8 @@ +--- +title: 'Python SDK Reference' +description: 'Complete reference documentation for the Python SDK' +--- + +import Content from "/snippets/python-sdk.mdx" + + diff --git a/documentation/sdks/python/sessions.mdx b/documentation/sdks/python/sessions.mdx new file mode 100644 index 000000000..e6cfab156 --- /dev/null +++ b/documentation/sdks/python/sessions.mdx @@ -0,0 +1,158 @@ +--- +title: 'Working with Sessions' +description: 'Learn how to manage sessions and maintain conversation context using the Python SDK' +--- + +## Creating Sessions + +Create a session to maintain conversation context: + +```python +session = client.sessions.create( + agent_id=agent.id, + user_id=user.id, # Optional + context_overflow="adaptive", # or "truncate" or "summarize" + metadata={ + "channel": "web", + "language": "english" + } +) +``` + +## Session Chat + +Interact with an agent through a session: + +```python +# Single message +response = client.sessions.chat( + session_id=session.id, + messages=[ + { + "role": "user", + "content": "What can you help me with?" + } + ] +) + +# Multiple messages in a conversation +response = client.sessions.chat( + session_id=session.id, + messages=[ + { + "role": "user", + "content": "I need help with research" + }, + { + "role": "assistant", + "content": "I can help you with that. What topic would you like to research?" + }, + { + "role": "user", + "content": "Let's research quantum computing" + } + ] +) +``` + +## Managing Session Context + +```python +# Get session history +history = client.sessions.history( + session_id=session.id, + limit=10, + before=datetime.now() +) + +# Update session context +session = client.sessions.update( + session_id=session.id, + metadata={"topic": "quantum computing"} +) + +# Clear session history +client.sessions.clear(session_id=session.id) +``` + +## Session Documents + +Manage documents associated with a session: + +```python +# Add a document to the session +doc = client.sessions.docs.create( + session_id=session.id, + title="Research Notes", + content="Notes about quantum computing...", + metadata={"type": "notes"} +) + +# Search session documents +results = client.sessions.docs.search( + session_id=session.id, + text="quantum", + metadata_filter={"type": "notes"} +) + +# Delete a session document +client.sessions.docs.delete( + session_id=session.id, + doc_id=doc.id +) +``` + +## Session Management + +```python +# List sessions +sessions = client.sessions.list( + agent_id=agent.id, + user_id=user.id, # Optional + limit=10, + offset=0 +) + +# Get session details +session = client.sessions.get(session_id=session.id) + +# Delete a session +client.sessions.delete(session_id=session.id) +``` + +## Error Handling + +```python +from julep.exceptions import JulepError, SessionNotFoundError + +try: + session = client.sessions.get("nonexistent_id") +except SessionNotFoundError: + print("Session not found") +except JulepError as e: + print(f"An error occurred: {e}") +``` + +## Working with Context Overflow + +Julep provides different strategies for handling context overflow: + +```python +# Adaptive context handling (default) +session = client.sessions.create( + agent_id=agent.id, + context_overflow="adaptive" +) + +# Truncate old messages +session = client.sessions.create( + agent_id=agent.id, + context_overflow="truncate" +) + +# Summarize old messages +session = client.sessions.create( + agent_id=agent.id, + context_overflow="summarize" +) +``` \ No newline at end of file diff --git a/documentation/sdks/python/tasks.mdx b/documentation/sdks/python/tasks.mdx new file mode 100644 index 000000000..f01e442ed --- /dev/null +++ b/documentation/sdks/python/tasks.mdx @@ -0,0 +1,170 @@ +--- +title: 'Working with Tasks' +description: 'Learn how to create and manage tasks using the Python SDK' +--- + +## Creating Tasks + +Create a task with a specific workflow: + +```python +import yaml + +task_yaml = """ +name: Research Task +description: Perform research on a given topic + +tools: + - name: web_search + type: integration + integration: + provider: brave + method: search + +main: + - prompt: + - role: system + content: You are {{agent.name}}. {{agent.about}} + - role: user + content: Research the topic: {{_.topic}} + unwrap: true + + - tool: web_search + arguments: + query: _.topic + + - prompt: + - role: system + content: Summarize the research findings + - role: user + content: Here are the search results: {{_.search_results}} +""" + +task = client.tasks.create( + agent_id=agent.id, + **yaml.safe_load(task_yaml) +) +``` + +## Task Components + +A task in Julep consists of several components: + +```python +task = client.tasks.create( + agent_id=agent.id, + name="Complex Task", + description="A multi-step task with various components", + input_schema={ + "type": "object", + "properties": { + "topic": {"type": "string"}, + "depth": {"type": "integer", "minimum": 1, "maximum": 5} + }, + "required": ["topic"] + }, + tools=[ + { + "name": "web_search", + "type": "integration", + "integration": { + "provider": "brave", + "method": "search" + } + } + ], + main=[ + {"prompt": "Research {{_.topic}} at depth {{_.depth}}"}, + {"tool": "web_search", "arguments": {"query": "_.topic"}}, + {"evaluate": {"results": "process_results(_)"}} + ] +) +``` + +## Executing Tasks + +Execute a task with specific inputs: + +```python +# Create an execution +execution = client.executions.create( + task_id=task.id, + input={"topic": "quantum computing", "depth": 3} +) + +# Check execution status +while True: + result = client.executions.get(execution.id) + if result.status in ['succeeded', 'failed']: + break + time.sleep(1) + +# Get the results +if result.status == "succeeded": + print(result.output) +else: + print(f"Execution failed: {result.error}") +``` + +## Managing Task Executions + +```python +# List executions for a task +executions = client.executions.list( + task_id=task.id, + limit=10, + offset=0, + status="succeeded" # Filter by status +) + +# Cancel an execution +client.executions.cancel(execution_id=execution.id) +``` + +## Task Control Flow + +Julep supports various control flow operations in tasks: + +```yaml +main: + # Conditional execution + - if: _.score > 0.8 + then: + - log: High score achieved + else: + - log: Score needs improvement + + # Iteration + - foreach: + in: _.data_list + do: + - log: "Processing {{_}}" + + # Parallel processing + - map_reduce: + over: _.topics + map: + - prompt: Write about {{_}} + parallelism: 5 + + # Error handling + - try: + - tool: risky_operation + catch: + - log: Operation failed +``` + +## Error Handling + +```python +from julep.exceptions import JulepError, TaskNotFoundError, ExecutionError + +try: + execution = client.executions.create(task_id="nonexistent_id") +except TaskNotFoundError: + print("Task not found") +except ExecutionError as e: + print(f"Execution failed: {e}") +except JulepError as e: + print(f"An error occurred: {e}") +``` \ No newline at end of file diff --git a/documentation/sdks/python/tools-integration.mdx b/documentation/sdks/python/tools-integration.mdx new file mode 100644 index 000000000..e0f62000d --- /dev/null +++ b/documentation/sdks/python/tools-integration.mdx @@ -0,0 +1,192 @@ +--- +title: 'Tools & Integration' +description: 'Learn how to use tools and integrations with the Python SDK' +--- + +## Overview + +Julep supports various types of tools and integrations that can be used in your tasks: + +1. Built-in integrations (e.g., web search, email) +2. User-defined functions +3. System tools +4. Direct API calls + +## Built-in Integrations + +### Web Search Integration + +```python +# Add web search capability to an agent +client.agents.tools.create( + agent_id=agent.id, + name="web_search", + type="integration", + integration={ + "provider": "brave", + "method": "search", + "setup": { + "api_key": "your_brave_api_key" + } + } +) +``` + +### Email Integration + +```python +# Add email capability +client.agents.tools.create( + agent_id=agent.id, + name="send_email", + type="integration", + integration={ + "provider": "email", + "setup": { + "host": "smtp.gmail.com", + "port": 587, + "user": "your_email@gmail.com", + "password": "your_app_password" + } + } +) +``` + +## User-defined Functions + +Create custom tools using function definitions: + +```python +# Define a custom tool +client.agents.tools.create( + agent_id=agent.id, + name="calculate_price", + type="function", + function={ + "description": "Calculate total price including tax", + "parameters": { + "type": "object", + "properties": { + "base_price": { + "type": "number", + "description": "Base price before tax" + }, + "tax_rate": { + "type": "number", + "description": "Tax rate as a decimal" + } + }, + "required": ["base_price", "tax_rate"] + } + } +) +``` + +## System Tools + +Use built-in system operations: + +```python +# Add document management capability +client.agents.tools.create( + agent_id=agent.id, + name="manage_docs", + type="system", + system={ + "resource": "agent", + "subresource": "doc", + "operation": "create" + } +) +``` + +## Direct API Calls + +Make direct API calls from your tasks: + +```python +# Add external API integration +client.agents.tools.create( + agent_id=agent.id, + name="weather_api", + type="api_call", + api_call={ + "method": "GET", + "url": "https://api.weather.com/v1/current", + "headers": { + "Authorization": "Bearer {{env.WEATHER_API_KEY}}" + } + } +) +``` + +## Using Tools in Tasks + +Example of using tools in a task: + +```yaml +name: Research Assistant +description: Research and summarize topics + +tools: + - name: web_search + type: integration + integration: + provider: brave + method: search + + - name: send_email + type: integration + integration: + provider: email + + - name: calculate_price + type: function + function: + parameters: + type: object + properties: + base_price: + type: number + tax_rate: + type: number + +main: + - tool: web_search + arguments: + query: _.topic + + - tool: calculate_price + arguments: + base_price: 100 + tax_rate: 0.1 + + - tool: send_email + arguments: + to: _.email + subject: "Research Results" + body: _.summary +``` + +## Error Handling + +Handle tool-specific errors: + +```python +from julep.exceptions import ToolError, IntegrationError + +try: + result = client.executions.create(task_id=task.id) +except ToolError as e: + print(f"Tool execution failed: {e}") +except IntegrationError as e: + print(f"Integration error: {e}") +``` + +## Best Practices + +1. **Security**: Store sensitive credentials in environment variables or secure storage +2. **Rate Limiting**: Be aware of API rate limits for external services +3. **Error Handling**: Implement proper error handling for each tool +4. **Testing**: Test tools with sample data before using in production +5. **Documentation**: Document tool usage and requirements for team reference \ No newline at end of file diff --git a/documentation/snippets/node-sdk.mdx b/documentation/snippets/node-sdk.mdx new file mode 120000 index 000000000..ce84e9fb2 --- /dev/null +++ b/documentation/snippets/node-sdk.mdx @@ -0,0 +1 @@ +../../sdks/node-sdk/api.md \ No newline at end of file diff --git a/documentation/snippets/python-sdk.mdx b/documentation/snippets/python-sdk.mdx new file mode 120000 index 000000000..d646d5064 --- /dev/null +++ b/documentation/snippets/python-sdk.mdx @@ -0,0 +1 @@ +../../sdks/python-sdk/api.md \ No newline at end of file diff --git a/documentation/welcome.mdx b/documentation/welcome.mdx new file mode 100644 index 000000000..5ffd3b906 --- /dev/null +++ b/documentation/welcome.mdx @@ -0,0 +1,129 @@ +--- +title: Welcome +description: 'Welcome to Julep - The Platform for Building Advanced AI Agents' +--- + + + Julep Hero Light + Julep Hero Dark + + +## Welcome to Julep + +Julep is a platform that helps you build advanced AI agents capable of handling complex tasks, maintaining long-term memory, and integrating with various tools and services. Whether you're building a sophisticated AI assistant, automating workflows, or creating intelligent systems, Julep provides the infrastructure you need. + +## Quick Overview + + + + Learn about Julep's purpose and what makes it different from other AI frameworks + + + Discover Julep's main capabilities and how they can benefit your projects + + + Understand how Julep's components work together to power your AI applications + + + Get started with your first Julep agent in just a few minutes + + + +## Getting Started + +The fastest way to get started with Julep is to: + +1. Install the SDK for your preferred language: + ```bash + # Python + pip install julep + + # Node.js + npm install @julep/sdk + ``` + +2. Get your API key from the [Julep Dashboard](https://dashboard.julep.ai) + +3. Create your first agent: + ```python + from julep import Julep + + client = Julep(api_key="your_api_key") + + agent = client.agents.create( + name="My First Agent", + model="claude-3.5-sonnet", + about="A helpful AI assistant" + ) + ``` + +## Next Steps + + + + Detailed setup instructions + + + Essential concepts and terminology + + + Learn from practical examples + + + +## Need Help? + + + + Get help and share ideas with other Julep developers + + + Reach out to our team for assistance + + diff --git a/sdks/node-sdk b/sdks/node-sdk index 6cb742bba..ff0443945 160000 --- a/sdks/node-sdk +++ b/sdks/node-sdk @@ -1 +1 @@ -Subproject commit 6cb742bba2b408ef2ea070bfe284595bcdb974fe +Subproject commit ff0443945294c2638b7cc796456d271c1b669fa2 diff --git a/sdks/python-sdk b/sdks/python-sdk index 7f9bc0c59..96cd8e74b 160000 --- a/sdks/python-sdk +++ b/sdks/python-sdk @@ -1 +1 @@ -Subproject commit 7f9bc0c59d2e80f6e707f5dcc9e78fecd197c3ca +Subproject commit 96cd8e74bc95bc83158f07489916b7f4214aa002 diff --git a/typespec/main.tsp b/typespec/main.tsp index 3ec3739dd..4b6ae5692 100644 --- a/typespec/main.tsp +++ b/typespec/main.tsp @@ -31,7 +31,6 @@ using Versions; title: "Julep API", }) @versioned(ApiVersions) -@summary("A backend for creating stateful AI apps") @info({ termsOfService: "https://julep.ai/terms", contact: { @@ -50,7 +49,7 @@ using Versions; "The julep cloud service endpoint", { @doc("The environment to use") - serverEnv?: "api" | "api-alpha" = "api-alpha", + serverEnv?: "api" | "dev" = "api", } ) @useAuth( diff --git a/typespec/tsp-output/@typespec/openapi3/openapi-1.0.0.yaml b/typespec/tsp-output/@typespec/openapi3/openapi-1.0.0.yaml index 0e3c66d18..53f176b57 100644 --- a/typespec/tsp-output/@typespec/openapi3/openapi-1.0.0.yaml +++ b/typespec/tsp-output/@typespec/openapi3/openapi-1.0.0.yaml @@ -9,7 +9,6 @@ info: license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html - summary: A backend for creating stateful AI apps description: Julep is a backend for creating stateful AI apps with background tasks and long-term memory easily. version: 1.0.0 externalDocs: @@ -9195,8 +9194,8 @@ servers: description: The julep cloud service endpoint variables: serverEnv: - default: api-alpha + default: api description: The environment to use enum: - api - - api-alpha + - dev