# Feedback Source: https://docs.snowleopard.ai/cloud/endpoints/feedback cloud_openapi.json POST /v1/instances/{instance_id}/feedback Give Snow Leopard feedback in plain text so it can understand your business logic and ontology better for more accurate answers Use the Feedback API endpoint to teach Snow Leopard about your business logic, column definitions, and terminology. Feedback can be given at any time, in plain text. Feedback is processed asynchronously, and can take up to 5 minutes to be applied. ```python Python theme={null} from snowleopard import SnowLeopardClient client = SnowLeopardClient(api_key="{api_key}") response = client.feedback( instance_id="{instance_id}", feedback_text="The revenue column should be labeled 'gross revenue before discounts'." ) ``` # Response Source: https://docs.snowleopard.ai/cloud/endpoints/response cloud_openapi.json POST /v1/instances/{instance_id}/response Execute a natural language query and return the summarized results in natural language. # Retrieve Source: https://docs.snowleopard.ai/cloud/endpoints/retrieve cloud_openapi.json POST /v1/instances/{instance_id}/retrieve Execute a natural language query against your instance's data sources and return the retrieved data. # Getting Started Source: https://docs.snowleopard.ai/cloud/getting-started This documentation is specific to the [Snow Leopard Cloud](https://cloud.snowleopard.ai/). With Snow Leopard Cloud, you can build AI Agents that use accurate data directly from multiple sytems of record, without needing any initial MCP setup or tuning. **Get started for free!** Sign up, create an instance, connect your data, and start querying! Snow Leopard automatically creates a semantic understanding of the connected data sources for very high accuracy out of the box, so you don't need to spend time defining ontology and business rules, creating evals or context engineering. You can also *give feedback* to Snow Leopard any time to help it understand your internal business logic better for even higher accuracy! If you want to deploy Snow Leopard on-prem or within your enterprise VPC, [contact us](mailto:sales@snowleopard.ai)! You can also check out our [Enterprise documentation](/enterprise/getting-started). To get started with Snow Leopard Cloud you need to: 1. [Sign up](#sign-up) at [cloud.snowleopard.ai](https://cloud.snowleopard.ai) 2. [Create an instance](#creating-an-instance) 3. [Add your data sources](#adding-a-data-source) and authorize Snow Leopard to connect to them 4. [Use our SDKs or the API](#using-the-api) directly See details below. ### Sign Up Visit [cloud.snowleopard.ai](https://cloud.snowleopard.ai) to create your account. ### Creating an Instance An instance is an isolated environment that holds your data source connections and API keys. From the [Instances page](https://cloud.snowleopard.ai/instances), click **Create Instance**. Once created, click through to the new instance to see its data source configuration and settings. ### Adding a Data Source You can add one or more data sources with one or more schemas to your instance. Snow Leopard has a built-in planner and router - at query time, it will automatically route the query (or sub-queries as necessary) to the right data source(s) in real-time to answer the question. From the instance page, click **Add Data Source** and follow the prompts: 1. Enter a name for the data source. 2. Select the type of data source. Currently supported: 1) Enter your **Google Cloud Project ID**. 2) Authorize Snow Leopard using OAuth. Snow Leopard will configure the data source to read from all datasets accessible to the OAuth user that have at least one table in the given Project ID. 1. Enter the **host**, **database name**, and **username/password** credentials for your database. Snow Leopard will configure the data source to read from all schemas accessible with the given credentials that have at least one table in the database. 1. Enter the **host**, **database name**, and **username/password** credentials for your database. 2. Use direct connections to your Neon database. Snow Leopard will configure the data source to read from all schemas accessible with the given credentials that have at least one table in the database. 1. Enter the **host**, **database name**, and **username/password** credentials for your database. 2. Use Supabase's [Shared Pooler (Supavisor)](https://supabase.com/docs/guides/database/connecting-to-postgres#pooler-session-mode) to connect your database to Snow Leopard Snow Leopard will configure the data source to read from all schemas accessible with the given credentials that have at least one table in the database. ### API Keys API keys are created per instance. 1. From the instance page, click the **Keys** tab. 2. Click **Create Key**. 3. Enter a name for the key. 4. Click **Create**. The key is displayed only once. Copy and save it at creation time if you want it for later use. ### Authentication All API endpoints are authenticated using API keys, also known as Bearer Tokens. Pass your key as a `Bearer` token in the `Authorization` header of every request: ``` Authorization: Bearer {api_key} ``` API keys are scoped to a specific instance. See [API Keys](#api-keys) above for how to create them. ### Connection Info From the instance page, click the **Connection Info** tab to find the instance's base URL. It will look like: ``` https://api.snowleopard.ai/v1/instances/ ``` You will need both the `instance_id` (visible in this URL) and your API key to make requests. ### Using the API There are currently **multiple ways** of interacting with the Snow Leopard API: 1. Python SDK ([pypi](https://pypi.org/project/snowleopard/)) 2. TypeScript SDK ([npm](https://www.npmjs.com/package/@snowleopard-ai/client)) 3. REST endpoints ```python Python theme={null} from snowleopard import SnowLeopardClient client = SnowLeopardClient(api_key="{api_key}") response = client.retrieve( instance_id="{instance_id}", user_query="How many users signed up last month?" ) print(response.data) ``` ```python Python Async theme={null} from snowleopard import AsyncSnowLeopardClient async def main(): client = AsyncSnowLeopardClient(api_key="{api_key}") response = await client.retrieve( instance_id="{instance_id}", user_query="How many users signed up last month?" ) print(response.data) ``` ```typescript TypeScript theme={null} import { SnowLeopardClient } from '@snowleopard-ai/client'; const client = new SnowLeopardClient({ apiKey: 'your-api-key' }); const response = await client.retrieve({ instanceId: 'your-instance-id', userQuery: 'How many users signed up last month?' }); console.log(response.data); await client.close(); ``` ```bash cURL theme={null} curl --request POST \ --url https://api.snowleopard.ai/v1/instances/{instance_id}/retrieve \ --header 'Authorization: Bearer {api_key}' \ --header 'Content-Type: application/json' \ --data '{"userQuery": "How many users signed up last month?"}' ``` # Response Source: https://docs.snowleopard.ai/enterprise/endpoints/response enterprise_openapi.json POST /response Execute a natural language query and return the summarized results in natural language. # Retrieve Source: https://docs.snowleopard.ai/enterprise/endpoints/retrieve enterprise_openapi.json POST /retrieve Execute a natural language query against your enterprise deployment and return the retrieved data. # Getting Started Source: https://docs.snowleopard.ai/enterprise/getting-started This documentation is for Snow Leopard enterprise deployments. Enterprise deployments are dedicated instances configured for your specific dataset and infrastructure. Not an enterprise customer? [Contact us](mailto:sales@snowleopard.ai) to get Snow Leopard for your org. You can also see our [Cloud documentation](/cloud/getting-started) to get started for free with [Snow Leopard Cloud](https://cloud.snowleopard.ai). To build AI agents on Snow Leopard's Enterprise deployment you need to: 1. Retrieve your [deployment URL](#deployment-configuration) 2. Get your [authentication](#authentication) information from Snow Leopard 3. Use our [SDKs or the API](#using-the-api) directly See below for details. ### Deployment Configuration Your Snow Leopard Enterprise deployment is hosted at a custom URL specific to your infrastructure. You will receive the VM IP address and port from the Snow Leopard team during setup. ### Authentication All API endpoints are authenticated using API Keys, also known as Bearer Tokens. Your API token will be provided to you by the Snow Leopard team during your initial deployment setup. Contact your Snow Leopard representative if you need a new API token. ### Using the API There are currently **multiple ways** of interacting with the Snow Leopard API: 1. Python SDK ([pypi](https://pypi.org/project/snowleopard/)) 2. TypeScript SDK ([npm](https://www.npmjs.com/package/@snowleopard-ai/client)) 3. REST endpoints ```python Python theme={null} from snowleopard import SnowLeopardClient client = SnowLeopardClient( url="https://{vm_ip_address}:{port}", api_key="{api_key}" ) response = client.retrieve( user_query="How many users signed up last month?" ) print(response.data) ``` ```python Python Async theme={null} from snowleopard import AsyncSnowLeopardClient async def main(): client = AsyncSnowLeopardClient( url="https://{vm_ip_address}:{port}", api_key="{api_key}" ) response = await client.retrieve( user_query="How many users signed up last month?" ) print(response.data) ``` ```typescript TypeScript theme={null} import { SnowLeopardClient } from '@snowleopard-ai/client'; const client = new SnowLeopardClient({ url: 'https://{vm_ip_address}:{port}', apiKey: '{api_key}' }); const response = await client.retrieve({ userQuery: 'How many users signed up last month?' }); console.log(response.data); await client.close(); ``` ```bash cURL theme={null} curl --request POST \ --url https://{vm_ip_address}:{port}/retrieve \ --header 'Authorization: Bearer {api_key}' \ --header 'Content-Type: application/json' \ --data '{"userQuery": "How many users signed up last month?"}' ``` # Introduction Source: https://docs.snowleopard.ai/index Snow Leopard Product and API documentation ## Welcome ### About Snow Leopard [Snow Leopard](https://www.snowleopard.ai/) is an AI-powered data retrieval platform that helps you build AI Agents that use accurate data directly from systems of record, for critical workflows. It can retrieve live, accurate data from multiple data sources (SQL databases, data warehouses, etc.). And, it doesn't require any initial setup. Just connect any number of data sources and start querying. No MCP setup, no ETL, and no iteration for weeks/months on context engineering. **Zero to ad-hoc data retrieval in minutes!** ### How it works 1. **Natural Language Input**: Your agent can ask questions about your data in plain English 2. **Intelligent Routing**: Snow Leopard creates a retrieval plan in real-time to the data that is needed to answer the question 3. **Live Retrieval**: Snow Leopard generates native SQL queries for the specific database on-demand and fetches live data directly from all the needed source(s) 4. **Agent-ready Response**: Returns live data in JSON-format for agent interactions, and can also provide natural language responses 5. **Response Summarization**: Provides clear, actionable insights from the retrieved data ### Why Snow Leopard? * Accuracy and reliability: Empower your AI Agents and agentic workflows with accurate data from multiple data sources in real-time, without needing to ETL and create/manage data pipelines * Get started in minutes: Connect data sources to Snow Leopard and your agent can start accessing that data in minutes, without weeks and months of setup and iteration * Get 90+% accurate data retrieval out of the box * No MCP setup or tuning required ## Understanding the API Snow Leopard exposes two REST endpoints: `Retrieve` and `Response`. #### `Retrieve` `Retrieve` is primarily for developers building AI agents that needs to retrieve data from a database directly. It takes a natural language question (usually from the user or the agent) and returns the required data in an LLM-friendly JSON object. Behind the scenes, Snow Leopard: * creates a retrieval plan in real time for the data needed to answer your question * builds a SQL query on-demand, and * executes that SQL query on the database to retrieve data needed The endpoint returns both the retrieved data and the generated SQL query for transparency. See the [`Retrieve` API endpoint](/cloud/endpoints/retrieve) for code examples and more details. #### `Response` `Response` is a conversational-AI-focused endpoint. It behaves like `Retrieve`, but subsequently sends the retrieved data to an LLM for summarization and natural language response generation. This endpoint also returns a JSON object with the SQL query, the data retrieved, *and* a natural language response that summarizes the retrieved data and answers the original question. This endpoint helps you build conversational BI agents easily and quickly. See the [`Response` API endpoint](/cloud/endpoints/response) for code examples and more details. ## Next Steps Ready to get started? Try Snow Leopard for free - see how your agents can start using your databases with highly accurate data in minutes. Learn more about Snow Leoaprd's BYOC deployment model, and how you can use Snow Leopard on-prem or within your VPC. # Response Source: https://docs.snowleopard.ai/playground/endpoints/response playground_openapi.json POST /datafiles/{datafile_id}/response Execute a natural language query and return the summarized results in natural language. # Retrieve Source: https://docs.snowleopard.ai/playground/endpoints/retrieve playground_openapi.json POST /datafiles/{datafile_id}/retrieve Execute a natural language query against a Playground datafile and return the retrieved data. # Getting Started Source: https://docs.snowleopard.ai/playground/getting-started This documentation is specific to the [Snow Leopard Playground](https://try.snowleopard.ai/). The Playground is free to use and allows you to get a sense of Snow Leopard. Get started by using one of the public datasets available there. You can also upload your own SQLite datafile and see how you can get started in minutes without any upfront data engineering or semantic definitions required. See our [FAQ](https://www.snowleopard.ai/faq) for more details on the Playground, supported datatypes etc. Want to start using Snow Leopard for your production AI Agents? See our [Cloud documentation](https://docs.snowleopard.ai/cloud/getting-started) to get started for **free** with [Snow Leopard Cloud](https://cloud.snowleopard.ai/). To build AI agents on Snow Leopard's Playground APIs you need to: 1. Create [API keys](#authentication) for authentication 2. Get the [Playground Datafile ID](#getting-your-datafile-id) for the SQLite database you want to use with your agent 3. Use our [SDKs or the API](#using-the-api) directly See below for details. ### Authentication All API endpoints are authenticated using API Keys, also known as Bearer Tokens. You can generate a key/token from your [Snow Leopard account](https://auth.snowleopard.ai/account) page. Generate a [new API Key](https://auth.snowleopard.ai/account/api_keys) ### Getting your Datafile ID Don't have your own data? Use one of our [sample datasets](https://github.com/SnowLeopard-AI/playground_datasets) to get started. To retrieve your datafile id, find the desired SQLite file on [your datafiles page](https://try.snowleopard.ai/datafiles) and click the `Copy ID` button in the `File ID` column. This will copy the file ID, which you can then use in the API calls to fetch live data from the SQLite datafile. ### Using the API There are currently **multiple ways** of interacting with the Snow Leopard API: 1. Python SDK ([pypi](https://pypi.org/project/snowleopard/)) 2. TypeScript SDK ([npm](https://www.npmjs.com/package/@snowleopard-ai/client)) 3. REST endpoints ```python Python theme={null} from snowleopard import SnowLeopardClient client = SnowLeopardClient(api_key="{api_key}") response = client.retrieve( datafile_id="{datafile_id}", user_query="How many superheroes are there?" ) print(response.data) ``` ```python Python Async theme={null} from snowleopard import AsyncSnowLeopardClient async def main(): client = AsyncSnowLeopardClient(api_key="{api_key}") response = await client.retrieve( datafile_id="{datafile_id}", user_query="How many superheroes are there?" ) print(response.data) ``` ```typescript TypeScript theme={null} import { SnowLeopardClient } from '@snowleopard-ai/client'; const client = new SnowLeopardClient({ apiKey: 'your-api-key' }); const response = await client.retrieve({ datafileId: 'your-datafile-id', userQuery: 'How many superheroes are there?' }); console.log(response.data); await client.close(); ``` ```bash cURL theme={null} curl --request POST \ --url https://api.snowleopard.ai/datafiles/{datafile_id}/retrieve \ --header 'Authorization: Bearer {api_key}' \ --header 'Content-Type: application/json' \ --data '{"userQuery": "How many superheroes are there?"}' ``` # Agentuity Source: https://docs.snowleopard.ai/quickstarts/agentuity Build a data retrieval agent with [Snow Leopard](https://snowleopard.ai) and [Agentuity](https://agentuity.com). ## What You'll Build A question-answering agent that: * Leverages Agentuity for easy deployment and monitoring * Retrieves live data from a SQL database through Snow Leopard * Requires no MCP setup, no ETL or data pipelines, and no RAG setup for data retrieval ## Prerequisites * [Agentuity CLI](https://agentuity.dev/Get-Started/installation) * [Snow Leopard API key](https://auth.snowleopard.ai/account/api_keys) * A datafile uploaded to [Snow Leopard Playground](https://try.snowleopard.ai) * OpenAI API key (or another [supported model provider](https://python.langchain.com/docs/integrations/chat/)) Don't have data? Use our [sample Northwind dataset](https://github.com/SnowLeopard-AI/playground_datasets/raw/refs/heads/main/northwind.db) to get started, or choose from our other [sample datasets](https://github.com/SnowLeopard-AI/playground_datasets/). ## 1. Create an Agentuity project ```bash theme={null} agentuity create ``` Follow along with the interactive project create which will create a directory for your agentuity agent. This quickstart doesn't need auth, db access, or any other options, so feel free to reject any Agentuity features you do not plan on using. ## 2. Install dependencies Once you have an Agentuity project and are in its working directory, we will need to add a few new dependencies to add live data retrieval to your agent. ```bash theme={null} bun add @snowleopard-ai/client ai zod @ai-sdk/openai ``` ## 3. Configure environment variables Add your API keys and datafile ID to your `.env` file: ```.env .env theme={null} OPENAI_API_KEY= SNOWLEOPARD_API_KEY= SNOWLEOPARD_DATAFILE_ID= ``` ## 4. Create the Snow Leopard tool Create a Vercel AI tool that calls Snow Leopard to retrieve data: ```typescript src/agent/getData.ts highlight={5-7,17-20} theme={null} import { tool } from "ai"; import { z } from "zod"; import { SnowLeopardClient } from "@snowleopard-ai/client"; const snowy = new SnowLeopardClient({ apiKey: process.env.SNOWLEOPARD_API_KEY! }); export const getData = tool({ description: 'Retrieve data from the database. ' + 'Describe your data here - this becomes part of the tool description.', inputSchema: z.object({ userQuestion: z.string().describe('the natural language query to answer'), }), execute: async ({ userQuestion }) => { return await snowy.retrieve({ userQuery: userQuestion, datafileId: process.env.SNOWLEOPARD_DATAFILE_ID! }); }, }); ``` ## 5. Create the agent Build an Agentuity agent that uses the Snow Leopard tool: ```typescript src/agent/agent.ts theme={null} import { createAgent } from '@agentuity/runtime'; import { s } from '@agentuity/schema'; import { generateText, type ModelMessage } from 'ai'; import { openai } from '@ai-sdk/openai'; import { getData } from './getData'; const agent = createAgent('chat', { description: 'A chat agent with data retrieval', handler: async (ctx, { message }) => { const messages: ModelMessage[] = [ { role: 'system', content: 'You are a helpful assistant that answers questions using your data tools.' }, { role: 'user', content: message } ]; for (let step = 0; step < 10; step++) { const result = await generateText({ model: openai('gpt-5-mini'), messages: messages, tools: { getData } }); messages.push(...result.response.messages); if (result.finishReason !== 'tool-calls') { return { response: result.text }; } } throw new Error('Agent exceeded maximum number of steps'); }, schema: { input: s.object({ message: s.string() }), output: s.object({ response: s.string() }), }, }); export default agent; ``` ## 6. Expose the agent via HTTP Add an API route to handle chat requests: ```typescript src/api/index.ts theme={null} import { createRouter } from '@agentuity/runtime'; import chat from '../agent/agent'; const api = createRouter(); /* Existing api definitions... */ api.post('/chat', chat.validator(), async (c) => { const data = c.req.valid('json'); return await chat.run(data); }); export default api; ``` ## 7. Try it out! Start your development server: ```bash theme={null} agentuity dev ``` Query your data: ```bash theme={null} curl -X POST http://localhost:3500/api/chat \ -H "Content-Type: application/json" \ -d '{"message": "How many customers do we have?"}' ``` ```json theme={null} { "response": "You have 91 customers (counted as non-null customer_id entries in the customers table). \n\nWould you like a breakdown by segment, region, sign-up date, or any other criteria?" } ``` ## Next steps * View the [full example on GitHub](https://github.com/SnowLeopard-AI/snowy-examples/tree/main/quickstart/agentuity) * Learn more about [Agentuity agents](https://agentuity.dev/Learn/Cookbook/Tutorials/rag-agent) * See our full [API documentation](https://docs.snowleopard.ai/) to learn about the [Retrieve](/playground/endpoints/retrieve) and [Response](/playground/endpoints/response) endpoints * Explore [Recipes](/recipes) for more agent examples # LangChain Source: https://docs.snowleopard.ai/quickstarts/langchain Integrate Snow Leopard with LangChain agents for natural language data queries. This guide shows you how to add Snow Leopard data retrieval to a [LangChain](https://python.langchain.com/) agent. ## Prerequisites * Python 3.10+ * OpenAI API key (or another [supported model provider](https://python.langchain.com/docs/integrations/chat/)) * [Snow Leopard API key](https://auth.snowleopard.ai/account/api_keys) * A datafile uploaded to [Snow Leopard Playground](https://try.snowleopard.ai) Don't have data? Use our [sample superheroes dataset](https://github.com/SnowLeopard-AI/playground_datasets/raw/refs/heads/main/superheroes.db) to get started, or choose from our other [sample datasets](https://github.com/SnowLeopard-AI/playground_datasets/). ## Start from scratch Clone and run the [complete working example](https://github.com/SnowLeopard-AI/snowy-examples/tree/main/quickstart/langchain): ```bash theme={null} git clone https://github.com/SnowLeopard-AI/snowy-examples.git cd snowy-examples/quickstart/langchain ``` Install dependencies: ```bash theme={null} pip install langchain langchain-openai snowleopard ``` Set your environment variables: ```bash theme={null} export OPENAI_API_KEY=your-openai-key export SNOWLEOPARD_API_KEY=your-snowleopard-key export SNOWLEOPARD_DATAFILE_ID=your-datafile-id ``` Run the example: ```bash theme={null} python langchain_quickstart.py ``` ## Bring your own agent Already have a LangChain agent? Add Snow Leopard data retrieval with these steps. ### 1. Install dependencies ```bash theme={null} pip install snowleopard ``` ### 2. Create the Snow Leopard tool Create a LangChain `Tool` that calls Snow Leopard to retrieve data: ```python theme={null} from langchain_core.tools import Tool from snowleopard import SnowLeopardClient client = SnowLeopardClient(api_key="{your-snowleopard-api-key}") def query_data(natural_language_query: str) -> str: """Query your database using natural language.""" response = client.retrieve( datafile_id="{your-datafile-id}", user_query=natural_language_query ) return str(response) snowleopard_tool = Tool( name="query_database", func=query_data, description="Query your database with natural language questions. " "Describe your data here - this becomes part of the agent's context." ) ``` ### 3. Add the tool to your agent Add the Snow Leopard tool to your agent's tool list: ```python theme={null} from langchain_openai import ChatOpenAI from langchain.agents import create_tool_calling_agent, AgentExecutor from langchain_core.prompts import ChatPromptTemplate llm = ChatOpenAI(model="gpt-4o") tools = [snowleopard_tool] # Add to your existing tools prompt = ChatPromptTemplate.from_messages([ ("system", "You are a helpful assistant that can query databases."), ("human", "{input}"), ("placeholder", "{agent_scratchpad}"), ]) agent = create_tool_calling_agent(llm, tools, prompt) agent_executor = AgentExecutor(agent=agent, tools=tools) ``` ## Next steps * View the [full example on GitHub](https://github.com/SnowLeopard-AI/snowy-examples/tree/main/quickstart/langchain) * See our full [API documentation](https://docs.snowleopard.ai/) to learn about the [Retrieve](/playground/endpoints/retrieve) and [Response](/playground/endpoints/response) endpoints * Explore [Recipes](/recipes) for production-ready agent examples # LangGraph Source: https://docs.snowleopard.ai/quickstarts/langgraph Integrate Snow Leopard with LangGraph workflows for stateful data retrieval. This guide shows you how to add Snow Leopard data retrieval to a [LangGraph](https://langchain-ai.github.io/langgraph/) workflow. ## Prerequisites * Python 3.10+ * OpenAI API key (or another [supported model provider](https://python.langchain.com/docs/integrations/chat/)) * [Snow Leopard API key](https://auth.snowleopard.ai/account/api_keys) * A datafile uploaded to [Snow Leopard Playground](https://try.snowleopard.ai) Don't have data? Use our [sample superheroes dataset](https://github.com/SnowLeopard-AI/playground_datasets/raw/refs/heads/main/superheroes.db) to get started, or choose from our other [sample datasets](https://github.com/SnowLeopard-AI/playground_datasets/). ## Start from scratch Clone and run the [complete working example](https://github.com/SnowLeopard-AI/snowy-examples/tree/main/quickstart/langgraph): ```bash theme={null} git clone https://github.com/SnowLeopard-AI/snowy-examples.git cd snowy-examples/quickstart/langgraph ``` Install dependencies: ```bash theme={null} pip install langgraph langchain-openai snowleopard ``` Set your environment variables: ```bash theme={null} export OPENAI_API_KEY=your-openai-key export SNOWLEOPARD_API_KEY=your-snowleopard-key export SNOWLEOPARD_DATAFILE_ID=your-datafile-id ``` Run the example: ```bash theme={null} python langgraph_quickstart.py ``` ## Bring your own agent Already have a LangGraph workflow? Add Snow Leopard data retrieval with these steps. ### 1. Install dependencies ```bash theme={null} pip install snowleopard ``` ### 2. Add Snow Leopard fields to your state Add fields to your graph state to store query results: ```python theme={null} from typing_extensions import TypedDict class GraphState(TypedDict): user_question: str query_result: str # Add this field for Snow Leopard results # ... your other state fields ``` ### 3. Create a Snow Leopard query node Create a node that calls Snow Leopard to retrieve data: ```python theme={null} from snowleopard import SnowLeopardClient client = SnowLeopardClient(api_key="{your-snowleopard-api-key}") def query_database(state: GraphState) -> GraphState: """Query the database using Snow Leopard.""" response = client.retrieve( datafile_id="{your-datafile-id}", user_query=state["user_question"] ) state["query_result"] = str(response) return state ``` ### 4. Add the node to your workflow Add the query node and connect it to your existing workflow: ```python theme={null} from langgraph.graph import StateGraph workflow = StateGraph(GraphState) # Add the Snow Leopard query node workflow.add_node("query", query_database) # Connect it to your workflow workflow.set_entry_point("query") workflow.add_edge("query", "your_next_node") ``` ## Next steps * View the [full example on GitHub](https://github.com/SnowLeopard-AI/snowy-examples/tree/main/quickstart/langgraph) * See our full [API documentation](https://docs.snowleopard.ai/) to learn about the [Retrieve](/playground/endpoints/retrieve) and [Response](/playground/endpoints/response) endpoints * See this quickstart in action with the [Financial Coach recipe](/recipes/financial-coach) # MCP Source: https://docs.snowleopard.ai/quickstarts/mcp Run a Snow Leopard MCP server and connect it to Claude Desktop or other MCP clients. This guide shows you how to run a Snow Leopard [MCP](https://modelcontextprotocol.io/) server using [FastMCP](https://github.com/jlowin/fastmcp) and connect it to an MCP client. ## Prerequisites * Python 3.10+ * [uv](https://docs.astral.sh/uv/) package manager * [Snow Leopard API key](https://auth.snowleopard.ai/account/api_keys) * A datafile uploaded to [Snow Leopard Playground](https://try.snowleopard.ai) * [Claude Desktop](https://claude.ai/download) (or another MCP client) Don't have data? Use our [sample superheroes dataset](https://github.com/SnowLeopard-AI/playground_datasets/raw/refs/heads/main/superheroes.db) to get started, or choose from our other [sample datasets](https://github.com/SnowLeopard-AI/playground_datasets/). ## Run the Snow Leopard MCP server Clone the [example server](https://github.com/SnowLeopard-AI/snowy-examples/tree/main/quickstart/fastmcp): ```bash theme={null} git clone https://github.com/SnowLeopard-AI/snowy-examples.git cd snowy-examples/quickstart/fastmcp ``` Set your environment variables: ```bash theme={null} export SNOWLEOPARD_API_KEY=your-snowleopard-key export SNOWLEOPARD_DATAFILE_ID=your-datafile-id ``` Run the server: ```bash theme={null} uv run fastmcp run server.py ``` ### Customize the tool description (optional) The tool's docstring tells agents when and how to use it. Edit `server.py` to describe your specific data: ```python theme={null} @mcp.tool def get_data(user_query: str): """ Retrieve customer order data. Contains order history, products, and customer information. Use this to answer questions about sales, orders, and customers. """ return snowy.retrieve(user_query=user_query, datafile_id=datafile_id) ``` ## Connect to the MCP server You can now connect the server to any application that supports MCP. Below we show how to connect with Claude Desktop. ### Claude Desktop Add the server to your Claude Desktop configuration (`claude_desktop_config.json`): ```json theme={null} { "mcpServers": { "snowy": { "command": "uv", "args": [ "--directory", "/path/to/snowy-examples/quickstart/fastmcp", "run", "fastmcp", "run", "server.py" ], "env": { "SNOWLEOPARD_API_KEY": "your-api-key", "SNOWLEOPARD_DATAFILE_ID": "your-datafile-id" } } } } ``` Now you can ask Claude questions about your data. ## Next steps * View the [full example on GitHub](https://github.com/SnowLeopard-AI/snowy-examples/tree/main/quickstart/fastmcp) * See our full [API documentation](https://docs.snowleopard.ai/) to learn about the [Retrieve](/playground/endpoints/retrieve) and [Response](/playground/endpoints/response) endpoints * Explore [Recipes](/recipes) for production-ready agent examples # Pydantic Source: https://docs.snowleopard.ai/quickstarts/pydantic-ai Integrate Snow Leopard with Pydantic AI agents for structured data retrieval. This guide shows you how to add Snow Leopard data retrieval to a [Pydantic](https://pydantic.dev/) [AI](https://ai.pydantic.dev/) agent. ## Prerequisites * Python 3.10+ * [uv](https://docs.astral.sh/uv/) package manager * Anthropic API key (or another [supported model provider](https://ai.pydantic.dev/models/)) * [Snow Leopard API key](https://auth.snowleopard.ai/account/api_keys) * A datafile uploaded to [Snow Leopard Playground](https://try.snowleopard.ai) Don't have data? Use our [sample superheroes dataset](https://github.com/SnowLeopard-AI/playground_datasets/raw/refs/heads/main/superheroes.db) to get started, or choose from our other [sample datasets](https://github.com/SnowLeopard-AI/playground_datasets/). ## Start from scratch Clone and run the [complete working example](https://github.com/SnowLeopard-AI/snowy-examples/tree/main/quickstart/pydantic-ai): ```bash theme={null} git clone https://github.com/SnowLeopard-AI/snowy-examples.git cd snowy-examples/quickstart/pydantic-ai ``` Set your environment variables: ```bash theme={null} export ANTHROPIC_API_KEY=your-anthropic-key export SNOWLEOPARD_API_KEY=your-snowleopard-key export SNOWLEOPARD_DATAFILE_ID=your-datafile-id ``` Run the agent: ```bash theme={null} uv run clai --agent agent:agent ``` You now have an interactive REPL where you can ask questions about your data: ``` clai ➤ How many superheroes are there? ``` ## Bring your own agent Already have a Pydantic AI agent? Add Snow Leopard data retrieval with these steps. ### 1. Install dependencies ```bash theme={null} uv add snowleopard ``` ### 2. Create the Snow Leopard tool Add a tool to your agent that calls Snow Leopard to retrieve data: ```python theme={null} from pydantic_ai import Agent, RunContext from snowleopard import SnowLeopardClient # Your existing agent agent = Agent( 'anthropic:claude-sonnet-4-5', instructions='Be concise, reply with one sentence.', ) # Initialize the Snow Leopard client snowy = SnowLeopardClient(api_key="{your-snowleopard-api-key}") # Add the data retrieval tool @agent.tool def get_data(ctx: RunContext[str], user_query: str) -> str: """ Retrieve data from the database. Describe your data here - this becomes part of the agent's context. """ response = snowy.retrieve(user_query=user_query, datafile_id="{your-datafile-id}") return str(response) ``` ### 3. Customize the tool description The tool's docstring tells the agent when and how to use it. Update it to describe your specific data: ```python theme={null} @agent.tool def get_data(ctx: RunContext[str], user_query: str) -> str: """ Retrieve customer order data. Contains order history, products, and customer information. Use this to answer questions about sales, orders, and customers. """ response = snowy.retrieve(user_query=user_query, datafile_id=datafile_id) return str(response) ``` ## Next steps * View the [full example on GitHub](https://github.com/SnowLeopard-AI/snowy-examples/tree/main/quickstart/pydantic-ai) * See our full [API documentation](https://docs.snowleopard.ai/) to learn about the [Retrieve](/playground/endpoints/retrieve) and [Response](/playground/endpoints/response) endpoints * See this quickstart in action with the [Data Agent recipe](/recipes/copilotkit-data-agent) # Vercel Source: https://docs.snowleopard.ai/quickstarts/vercel-ai Integrate Snow Leopard with Vercel AI SDK for natural language data queries. This guide shows you how to add Snow Leopard data retrieval to a [Vercel](https://vercel.com/) [AI SDK](https://sdk.vercel.ai/) agent. ## Prerequisites * Node.js v18+ * OpenAI API key (or another [supported model provider](https://sdk.vercel.ai/providers/ai-sdk-providers)) * [Snow Leopard API key](https://auth.snowleopard.ai/account/api_keys) * A datafile uploaded to [Snow Leopard Playground](https://try.snowleopard.ai) Don't have data? Use our [sample superheroes dataset](https://github.com/SnowLeopard-AI/playground_datasets/raw/refs/heads/main/superheroes.db) to get started, or choose from our other [sample datasets](https://github.com/SnowLeopard-AI/playground_datasets/). ## Start from scratch Clone and run the [complete working example](https://github.com/SnowLeopard-AI/snowy-examples/tree/main/quickstart/vercel-ai): ```bash theme={null} git clone https://github.com/SnowLeopard-AI/snowy-examples.git cd snowy-examples/quickstart/vercel-ai ``` Install dependencies: ```bash theme={null} npm install ``` Set your environment variables: ```bash theme={null} export OPENAI_API_KEY=your-openai-key export SNOWLEOPARD_API_KEY=your-snowleopard-key export SNOWLEOPARD_DATAFILE_ID=your-datafile-id ``` Run the example: ```bash theme={null} npm run snowy ``` You now have an interactive REPL where you can ask questions about your data. ## Bring your own agent Already have a Vercel AI agent? Add Snow Leopard data retrieval with these steps. ### 1. Install dependencies ```bash theme={null} npm install @snowleopard-ai/client ``` ### 2. Create the Snow Leopard tool Create a tool that calls Snow Leopard to retrieve data: ```javascript theme={null} const { tool } = require('ai'); const { z } = require('zod'); const { SnowLeopardClient } = require('@snowleopard-ai/client'); const snowy = new SnowLeopardClient({ apiKey: '{your-snowleopard-api-key}' }); const getData = tool({ description: 'Retrieve data from the database. ' + 'Describe your data here - this becomes part of the tool description.', inputSchema: z.object({ userQuestion: z.string().describe('the natural language query to answer'), }), execute: async ({ userQuestion }) => { return await snowy.retrieve({ userQuery: userQuestion, datafileId: '{your-datafile-id}' }); } }); ``` ### 3. Customize the tool description The tool's description tells the agent when and how to use it. Update it to describe your specific data: ```javascript theme={null} const getData = tool({ description: 'Retrieve customer order data. ' + 'Contains order history, products, and customer information. ' + 'Use this to answer questions about sales, orders, and customers.', // ... }); ``` ## Next steps * View the [full example on GitHub](https://github.com/SnowLeopard-AI/snowy-examples/tree/main/quickstart/vercel-ai) * See our full [API documentation](https://docs.snowleopard.ai/) to learn about the [Retrieve](/playground/endpoints/retrieve) and [Response](/playground/endpoints/response) endpoints * Explore [Recipes](/recipes) for production-ready agent examples # Data Agent (CopilotKit + Pydantic) Source: https://docs.snowleopard.ai/recipes/copilotkit-data-agent Build a "chat with your data" application using CopilotKit and Pydantic AI. An application that lets users chat with their data through a web UI. Built with [CopilotKit](https://copilotkit.ai/) for the frontend and [Pydantic AI](https://ai.pydantic.dev/) for the backend agent. Chat with your data agent screenshot ## What it does This agent provides a chat interface for querying your data in natural language. Users can: * Ask questions about their data in plain English * View query results in a formatted table * Have multi-turn conversations to drill down into the data The agent translates natural language questions into SQL queries via Snow Leopard, executes them, and presents results in a user-friendly format. ## Architecture The application has two main components: ### Frontend (Next.js + CopilotKit) * **Next.js** provides the web application framework * **CopilotKit** provides the chat UI components and handles communication with the backend agent * **Data tables** display query results returned from the agent ### Backend (Pydantic AI + Snow Leopard) * **Pydantic AI** agent with two tools: * `get_data`: Calls Snow Leopard to convert natural language to SQL and retrieve results * `read_get_data_response`: Allows paginated reading of large result sets * **AG-UI state management** keeps the frontend in sync with query results * **Snow Leopard** handles natural language to SQL conversion ## Run the example ### Prerequisites * Python 3.12+ * Node.js 20+ * [uv](https://docs.astral.sh/uv/) package manager * pnpm (or npm) * OpenAI API key * [Snow Leopard API key](https://auth.snowleopard.ai/account/api_keys) * A datafile uploaded to [Snow Leopard Playground](https://try.snowleopard.ai) Don't have data? This example uses northwind.db, a public sales database. You can download it from our [sample datasets](https://github.com/SnowLeopard-AI/playground_datasets/) using [this link](https://github.com/SnowLeopard-AI/playground_datasets/raw/refs/heads/main/northwind.db). ### Setup Clone the [repository](https://github.com/SnowLeopard-AI/snowy-examples/tree/main/agent_examples/chat_with_your_data_copilotkit): ```bash theme={null} git clone https://github.com/SnowLeopard-AI/snowy-examples.git cd snowy-examples/agent_examples/chat_with_your_data_copilotkit ``` Install dependencies: ```bash theme={null} pnpm install ``` Create a `.env` file in the `agent` folder: ```bash theme={null} OPENAI_API_KEY=your-openai-key SNOWLEOPARD_API_KEY=your-snowleopard-key SNOWLEOPARD_DATAFILE_ID=your-datafile-id ``` Start the development server: ```bash theme={null} pnpm dev ``` This starts both the UI and agent servers. Open [http://localhost:3000](http://localhost:3000) to start chatting with your data. ## Next steps * View the [full source code on GitHub](https://github.com/SnowLeopard-AI/snowy-examples/tree/main/agent_examples/chat_with_your_data_copilotkit) * Learn more about [CopilotKit](https://docs.copilotkit.ai/) * Explore the [Pydantic AI quickstart](/quickstarts/pydantic-ai) # Financial Coach (LangGraph) Source: https://docs.snowleopard.ai/recipes/financial-coach Build a CLI financial coaching agent that analyzes spending data and provides personalized recommendations. A CLI agent that analyzes personal spending data and provides AI-powered financial coaching. Built with [LangGraph](https://langchain-ai.github.io/langgraph/) for multi-step workflows. ## What it does This agent acts as a personal financial coach through a command-line interface. Users can: * Ask questions about their spending in natural language * Get breakdowns by category, merchant, or time period * Receive personalized recommendations and savings opportunities * Have multi-turn conversations with conversation memory Example interaction: ``` You: Show me my spending by category ╔══════════════════════════════════════════════════════════╗ ║ 💡 FINANCIAL COACHING INSIGHTS ║ ╚══════════════════════════════════════════════════════════╝ 📊 YOUR SPENDING ANALYSIS ────────────────────────────────────────────────────────────── 💰 Real Monthly Spending: $2,543.22 🔴 Highest Expense: Rent @ $1,200.00 (47.2% of total) 💡 Found 3 optimization opportunities totaling $425/month 💡 RECOMMENDATIONS FOR YOU ────────────────────────────────────────────────────────────── 1. Your Rent is your largest expense (47.2%). This should be priority #1. 2. Meal prep 2x/week could save $127/month (Highest impact) ``` ## Architecture The agent uses a 4-node LangGraph workflow: 1. **Enrich query** - Adds context about time period, categories, and merchants 2. **Query Snow Leopard** - Converts natural language to SQL and retrieves data 3. **Analyze and coach** - Generates insights, recommendations, and follow-up questions 4. **Format response** - Creates formatted CLI output with Rich ### Key components * **LangGraph** orchestrates the multi-step workflow * **Snow Leopard** handles natural language to SQL conversion * **Coaching analyzer** generates personalized financial insights * **Memory manager** maintains conversation context across turns * **Rich CLI** provides formatted terminal output ## Run the example ### Prerequisites * Python 3.10+ * OpenAI API key * [Snow Leopard API key](https://auth.snowleopard.ai/account/api_keys) * A datafile uploaded to [Snow Leopard Playground](https://try.snowleopard.ai) The example includes a script to generate sample financial data, or you can use your own SQLite database with transaction data. ### Setup Clone the [repository](https://github.com/SnowLeopard-AI/snowy-examples/tree/main/agent_examples/financial_coach_langchain): ```bash theme={null} git clone https://github.com/SnowLeopard-AI/snowy-examples.git cd snowy-examples/agent_examples/financial_coach_langchain ``` Install dependencies: ```bash theme={null} pip install -r requirements.txt ``` Generate sample data (optional): ```bash theme={null} python data/create_sample_data.py ``` Create a `.env` file: ```bash theme={null} OPENAI_API_KEY=your-openai-key SNOWLEOPARD_API_KEY=your-snowleopard-key SNOWLEOPARD_DATAFILE_ID=your-datafile-id ``` Run the agent: ```bash theme={null} python main.py ``` ### Example queries * "Show me my spending by category" * "Which merchants did I spend the most at?" * "Compare this month vs last month" * "How much did I spend on groceries?" ## Next steps * View the [full source code on GitHub](https://github.com/SnowLeopard-AI/snowy-examples/tree/main/agent_examples/financial_coach_langchain) * Learn more about [LangGraph](https://langchain-ai.github.io/langgraph/) * Explore the [LangGraph quickstart](/quickstarts/langgraph) # Game Club Planner (CrewAI) Source: https://docs.snowleopard.ai/recipes/gameclub-planner Build a multi-agent system that researches games and plans discussion club meetings. A multi-agent system that helps plan game discussion club meetings by researching game data. Built with [CrewAI](https://www.crewai.com/) for agent orchestration. ## What it does This crew of AI agents works together to plan game club meetings. The system: * Researches games using a Metacritic dataset via Snow Leopard * Analyzes game scores, platforms, and release dates * Generates a formatted report with meeting recommendations The crew consists of two agents that collaborate sequentially: 1. **Researcher** - Queries the game database to find relevant titles 2. **Reporting Analyst** - Compiles findings into a formatted report ``` ╭─────────────────────────────────────────────────────────────────────────── Crew Execution Started ───────────────────────────────────────────────────────────────────────────╮ │ │ │ Crew Execution Started │ │ Name: crew │ │ ID: 42f359a6-4cf6-44e2-962a-b737584d4e87 │ │ Tool Args: │ │ │ │ │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ 🚀 Crew: crew └── 📋 Task: research_task (ID: 03ed5bf3-0486-4c3f-a2c3-a34fc57d125c) Status: Executing Task... ╭────────────────────────────────────────────────────────────────────────────── 🤖 Agent Started ──────────────────────────────────────────────────────────────────────────────╮ │ │ │ Agent: Game Researcher for theme: games released between 2010 and 2015 with a metascore above 90 │ │ │ │ Task: Use available tools to find games relevant to this theme: games released between 2010 and 2015 with a metascore above 90 │ │ │ │ │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ 🚀 Crew: crew └── 📋 Task: research_task (ID: 03ed5bf3-0486-4c3f-a2c3-a34fc57d125c) Status: Executing Task... ├── 🔧 Used Snow Leopard Metacritic Data (1) └── 🧠 Thinking... ╭────────────────────────────────────────────────────────────────────────── 🔧 Agent Tool Execution ───────────────────────────────────────────────────────────────────────────╮ │ │ │ Agent: Game Researcher for theme: games released between 2010 and 2015 with a metascore above 90 │ │ │ │ Thought: Thought: I need to query the Snow Leopard Metacritic Data tool to find a list of games released between 2010 and 2015 that have a Metascore above 90. │ │ │ │ Using Tool: Snow Leopard Metacritic Data │ │ │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭───────────────────────────────────────────────────────────────────────────────── Tool Input ─────────────────────────────────────────────────────────────────────────────────╮ │ │ │ { │ │ "question": "List games released between 2010 and 2015 with a Metascore above 90." │ │ } │ │ │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭──────────────────────────────────────────────────────────────────────────────── Tool Output ─────────────────────────────────────────────────────────────────────────────────╮ │ │ │ [{"name": "Super Mario Galaxy 2", "console": "WII", "date": "2010-05-23", "metascore_percent": 97}, {"name": "Grand Theft Auto V", "console": "PS3", "date": "2013-09-17", │ │ "metascore_percent": 97}, {"name": "Grand Theft Auto V", "console": "X360", "date": "2013-09-17", "metascore_percent": 97}, {"name": "Grand Theft Auto V", "console": │ │ "XONE", "date": "2014-11-18", "metascore_percent": 97}, {"name": "Grand Theft Auto V", "console": "PS4", "date": "2014-11-18", "metascore_percent": 97}, {"name": "Mass │ │ Effect 2", "console": "X360", "date": "2010-01-26", "metascore_percent": 96}, {"name": "Batman: Arkham City", "console": "PS3", "date": "2011-10-18", "metascore_percent": │ │ 96}, {"name": "The Elder Scrolls V: Skyrim", "console": "X360", "date": "2011-11-11", "metascore_percent": 96}, {"name": "Grand Theft Auto V", "console": "PC", "date": │ │ "2015-04-14", "metascore_percent": 96}, {"name": "Red Dead Redemption", "console": "PS3", "date": "2010-05-18", "metascore_percent": 95}, {"name": "Red Dead Redemption", │ │ "console": "X360", "date": "2010-05-18", "metascore_percent": 95}, {"name": "Portal 2", "console": "PC", "date": "2011-04-18", "metascore_percent": 95}, {"name": "Portal │ │ 2", "console": "X360", "date": "2011-04-19", "metascore_percent": 95}, {"name": "Portal 2", "console": "PS3", "date": "2011-04-19", "metascore_percent": 95}, {"name": │ │ "The Last of Us", "console": "PS3", "date": "2013-06-14", "metascore_percent": 95}, {"name": "The Last of Us Remastered", "console": "PS4", "date": "2014-07-29", │ │ "metascore_percent": 95}, {"name": "Metal Gear Solid V: The Phantom Pain", "console": "XONE", "date": "2015-09-01", "metascore_percent": 95}, {"name": "Mass Effect 2", │ │ "console": "PC", "date": "2010-01-26", "metascore_percent": 94}, {"name": "Mass Effect 2", "console": "PS3", "date": "2011-01-17", "metascore_percent": 94}, {"name": "The │ │ Legend of Zelda: Ocarina of Time 3D", "console": "3DS", "date": "2011-06-19", "metascore_percent": 94}, {"name": "Batman: Arkham City", "console"... │ │ │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭─────────────────────────────────────────────────────────────────────────── ✅ Agent Final Answer ────────────────────────────────────────────────────────────────────────────╮ │ │ │ Agent: Game Researcher for theme: games released between 2010 and 2015 with a metascore above 90 │ │ │ │ Final Answer: │ │ Here's a list of the top 10 games released between 2010 and 2015 with a Metascore above 90: │ │ │ │ 1. **Super Mario Galaxy 2** │ │ - Console: Wii │ │ - Release Date: 2010-05-23 │ │ - Metascore: 97 │ │ │ │ 2. **Grand Theft Auto V** │ │ - Console: PS3 │ │ - Release Date: 2013-09-17 │ │ - Metascore: 97 │ │ │ │ 3. **Mass Effect 2** │ │ - Console: Xbox 360 │ │ - Release Date: 2010-01-26 │ │ - Metascore: 96 │ │ │ │ 4. **Batman: Arkham City** │ │ - Console: PS3 │ │ - Release Date: 2011-10-18 │ │ - Metascore: 96 │ │ │ │ 5. **The Elder Scrolls V: Skyrim** │ │ - Console: Xbox 360 │ │ - Release Date: 2011-11-11 │ │ - Metascore: 96 │ │ │ │ 6. **Red Dead Redemption** │ │ - Console: PS3 │ │ - Release Date: 2010-05-18 │ │ - Metascore: 95 │ │ │ │ 7. **Portal 2** │ │ - Console: PC │ │ - Release Date: 2011-04-18 │ │ - Metascore: 95 │ │ │ │ 8. **The Last of Us** │ │ - Console: PS3 │ │ - Release Date: 2013-06-14 │ │ - Metascore: 95 │ │ │ │ 9. **The Witcher 3: Wild Hunt** │ │ - Console: PC │ │ - Release Date: 2015-05-18 │ │ - Metascore: 93 │ │ │ │ 10. **Bloodborne** │ │ - Console: PS4 │ │ - Release Date: 2015-03-24 │ │ - Metascore: 92 │ │ │ │ This list includes classics and fan favorites, making it excellent for discussion in a gaming club! │ │ │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ 🚀 Crew: crew └── 📋 Task: research_task (ID: 03ed5bf3-0486-4c3f-a2c3-a34fc57d125c) Assigned to: Game Researcher for theme: games released between 2010 and 2015 with a metascore above 90 Status: ✅ Completed └── 🔧 Used Snow Leopard Metacritic Data (1) ╭────────────────────────────────────────────────────────────────────────────── Task Completion ───────────────────────────────────────────────────────────────────────────────╮ │ │ │ Task Completed │ │ Name: research_task │ │ Agent: Game Researcher for theme: games released between 2010 and 2015 with a metascore above 90 │ │ │ │ Tool Args: │ │ │ │ │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ 🚀 Crew: crew ├── 📋 Task: research_task (ID: 03ed5bf3-0486-4c3f-a2c3-a34fc57d125c) │ Assigned to: Game Researcher for theme: games released between 2010 and 2015 with a metascore above 90 │ │ Status: ✅ Completed │ └── 🔧 Used Snow Leopard Metacritic Data (1) └── 📋 Task: reporting_task (ID: 910aee6e-5479-4d86-bafe-8518486b74bf) Status: Executing Task... ╭────────────────────────────────────────────────────────────────────────────── 🤖 Agent Started ──────────────────────────────────────────────────────────────────────────────╮ │ │ │ Agent: Game Club Planner for theme: games released between 2010 and 2015 with a metascore above 90 │ │ │ │ Task: Use the context you got to make a plan for a game discussion club that plays one game a month revolving around a theme. The theme for the next few months is: games │ │ released between 2010 and 2015 with a metascore above 90 │ │ │ │ │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ 🚀 Crew: crew ├── 📋 Task: research_task (ID: 03ed5bf3-0486-4c3f-a2c3-a34fc57d125c) │ Assigned to: Game Researcher for theme: games released between 2010 and 2015 with a metascore above 90 │ │ Status: ✅ Completed │ └── 🔧 Used Snow Leopard Metacritic Data (1) └── 📋 Task: reporting_task (ID: 910aee6e-5479-4d86-bafe-8518486b74bf) Status: Executing Task... ╭─────────────────────────────────────────────────────────────────────────── ✅ Agent Final Answer ────────────────────────────────────────────────────────────────────────────╮ │ │ │ Agent: Game Club Planner for theme: games released between 2010 and 2015 with a metascore above 90 │ │ │ │ Final Answer: │ │ ### Game Discussion Club Schedule: Games Released Between 2010 and 2015 with a Metascore Above 90 │ │ │ │ #### Month 1: **Super Mario Galaxy 2** │ │ - **Console**: Wii │ │ - **Release Date**: 2010-05-23 │ │ - **Metascore**: 97 │ │ - **Discussion Points**: │ │ - How did the game improve upon the already highly-acclaimed original Super Mario Galaxy? │ │ - What makes the level design stand out even today? │ │ - Discuss the impact of this game on platformers. │ │ │ │ #### Month 2: **Mass Effect 2** │ │ - **Console**: Xbox 360 │ │ - **Release Date**: 2010-01-26 │ │ - **Metascore**: 96 │ │ - **Discussion Points**: │ │ - Narrative depth: How does the game deliver emotional resonance through character stories? │ │ - Discuss the morality system and its influence on the gaming industry. │ │ - Favorite companions and their backstories. │ │ │ │ #### Month 3: **Red Dead Redemption** │ │ - **Console**: PS3 │ │ - **Release Date**: 2010-05-18 │ │ - **Metascore**: 95 │ │ - **Discussion Points**: │ │ - Exploration of the open-world wild west setting. │ │ - Discuss John Marston as a complex protagonist. │ │ - How does the game balance freedom and story-driven progression? │ │ │ │ #### Month 4: **Portal 2** │ │ - **Console**: PC │ │ - **Release Date**: 2011-04-18 │ │ - **Metascore**: 95 │ │ - **Discussion Points**: │ │ - The evolution of puzzles from the first game. │ │ - The game’s humor and writing, especially dialogue from GLaDOS and Wheatley. │ │ - Discuss co-op mode and its impact on the overall experience. │ │ │ │ #### Month 5: **The Elder Scrolls V: Skyrim** │ │ - **Console**: Xbox 360 │ │ - **Release Date**: 2011-11-11 │ │ - **Metascore**: 96 │ │ - **Discussion Points**: │ │ - What makes this game so enduring and deserving of its legendary status? │ │ - Discuss freedom of role-playing and character building. │ │ - Memorable quests, mods, and their contribution to the Skyrim experience. │ │ │ │ #### Month 6: **The Last of Us** │ │ - **Console**: PS3 │ │ - **Release Date**: 2013-06-14 │ │ - **Metascore**: 95 │ │ - **Discussion Points**: │ │ - How does the game create emotional impact through its story and characters? │ │ - The interplay between survival mechanics and narrative design. │ │ - Discuss the relationship between Joel and Ellie. │ │ │ │ #### Month 7: **Grand Theft Auto V** │ │ - **Console**: PS3 │ │ - **Release Date**: 2013-09-17 │ │ - **Metascore**: 97 │ │ - **Discussion Points**: │ │ - Exploration of three-protagonist storytelling. │ │ - How does the game parody contemporary American society? │ │ - Discuss standout moments, missions, and the online experience. │ │ │ │ #### Month 8: **Bloodborne** │ │ - **Console**: PS4 │ │ - **Release Date**: 2015-03-24 │ │ - **Metascore**: 92 │ │ - **Discussion Points**: │ │ - The atmosphere and lore of the gothic, Lovecraftian setting. │ │ - Combat mechanics and how they differ from Soulsborne games. │ │ - Challenges and memorable boss fights. │ │ │ │ #### Month 9: **The Witcher 3: Wild Hunt** │ │ - **Console**: PC │ │ - **Release Date**: 2015-05-18 │ │ - **Metascore**: 93 │ │ - **Discussion Points**: │ │ - Discuss the depth of side quests and their importance to the world-building. │ │ - How Geralt’s moral choices affect the narrative. │ │ - Favorite expansions, characters, and moments. │ │ │ │ #### Month 10: **Batman: Arkham City** │ │ - **Console**: PS3 │ │ - **Release Date**: 2011-10-18 │ │ - **Metascore**: 96 │ │ - **Discussion Points**: │ │ - How does the game improve on the original Arkham Asylum? │ │ - Discuss the open-world design and its influence on superhero games. │ │ - Favorite villains and boss fights. │ │ │ │ This schedule ensures a variety of genres and gameplay experiences spread across ten months, generating engaging discussion topics and a rich exploration of some of │ │ gaming's best titles. │ │ │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ✅ Crew: crew ├── 📋 Task: research_task (ID: 03ed5bf3-0486-4c3f-a2c3-a34fc57d125c) │ Assigned to: Game Researcher for theme: games released between 2010 and 2015 with a metascore above 90 │ │ Status: ✅ Completed │ └── 🔧 Used Snow Leopard Metacritic Data (1) └── 📋 Task: reporting_task (ID: 910aee6e-5479-4d86-bafe-8518486b74bf) Assigned to: Game Club Planner for theme: games released between 2010 and 2015 with a metascore above 90 Status: ✅ Completed ╭────────────────────────────────────────────────────────────────────────────── Crew Completion ───────────────────────────────────────────────────────────────────────────────╮ │ │ │ Crew Execution Completed │ │ Name: crew │ │ ID: 42f359a6-4cf6-44e2-962a-b737584d4e87 │ │ Tool Args: │ │ Final Output: ### Game Discussion Club Schedule: Games Released Between 2010 and 2015 with a Metascore Above 90 │ │ │ │ #### Month 1: **Super Mario Galaxy 2** │ │ - **Console**: Wii │ │ - **Release Date**: 2010-05-23 │ │ - **Metascore**: 97 │ │ - **Discussion Points**: │ │ - How did the game improve upon the already highly-acclaimed original Super Mario Galaxy? │ │ - What makes the level design stand out even today? │ │ - Discuss the impact of this game on platformers. │ │ │ │ #### Month 2: **Mass Effect 2** │ │ - **Console**: Xbox 360 │ │ - **Release Date**: 2010-01-26 │ │ - **Metascore**: 96 │ │ - **Discussion Points**: │ │ - Narrative depth: How does the game deliver emotional resonance through character stories? │ │ - Discuss the morality system and its influence on the gaming industry. │ │ - Favorite companions and their backstories. │ │ │ │ #### Month 3: **Red Dead Redemption** │ │ - **Console**: PS3 │ │ - **Release Date**: 2010-05-18 │ │ - **Metascore**: 95 │ │ - **Discussion Points**: │ │ - Exploration of the open-world wild west setting. │ │ - Discuss John Marston as a complex protagonist. │ │ - How does the game balance freedom and story-driven progression? │ │ │ │ #### Month 4: **Portal 2** │ │ - **Console**: PC │ │ - **Release Date**: 2011-04-18 │ │ - **Metascore**: 95 │ │ - **Discussion Points**: │ │ - The evolution of puzzles from the first game. │ │ - The game’s humor and writing, especially dialogue from GLaDOS and Wheatley. │ │ - Discuss co-op mode and its impact on the overall experience. │ │ │ │ #### Month 5: **The Elder Scrolls V: Skyrim** │ │ - **Console**: Xbox 360 │ │ - **Release Date**: 2011-11-11 │ │ - **Metascore**: 96 │ │ - **Discussion Points**: │ │ - What makes this game so enduring and deserving of its legendary status? │ │ - Discuss freedom of role-playing and character building. │ │ - Memorable quests, mods, and their contribution to the Skyrim experience. │ │ │ │ #### Month 6: **The Last of Us** │ │ - **Console**: PS3 │ │ - **Release Date**: 2013-06-14 │ │ - **Metascore**: 95 │ │ - **Discussion Points**: │ │ - How does the game create emotional impact through its story and characters? │ │ - The interplay between survival mechanics and narrative design. │ │ - Discuss the relationship between Joel and Ellie. │ │ │ │ #### Month 7: **Grand Theft Auto V** │ │ - **Console**: PS3 │ │ - **Release Date**: 2013-09-17 │ │ - **Metascore**: 97 │ │ - **Discussion Points**: │ │ - Exploration of three-protagonist storytelling. │ │ - How does the game parody contemporary American society? │ │ - Discuss standout moments, missions, and the online experience. │ │ │ │ #### Month 8: **Bloodborne** │ │ - **Console**: PS4 │ │ - **Release Date**: 2015-03-24 │ │ - **Metascore**: 92 │ │ - **Discussion Points**: │ │ - The atmosphere and lore of the gothic, Lovecraftian setting. │ │ - Combat mechanics and how they differ from Soulsborne games. │ │ - Challenges and memorable boss fights. │ │ │ │ #### Month 9: **The Witcher 3: Wild Hunt** │ │ - **Console**: PC │ │ - **Release Date**: 2015-05-18 │ │ - **Metascore**: 93 │ │ - **Discussion Points**: │ │ - Discuss the depth of side quests and their importance to the world-building. │ │ - How Geralt’s moral choices affect the narrative. │ │ - Favorite expansions, characters, and moments. │ │ │ │ #### Month 10: **Batman: Arkham City** │ │ - **Console**: PS3 │ │ - **Release Date**: 2011-10-18 │ │ - **Metascore**: 96 │ │ - **Discussion Points**: │ │ - How does the game improve on the original Arkham Asylum? │ │ - Discuss the open-world design and its influence on superhero games. │ │ - Favorite villains and boss fights. │ │ │ │ This schedule ensures a variety of genres and gameplay experiences spread across ten months, generating engaging discussion topics and a rich exploration of some of │ │ gaming's best titles. │ │ │ │ │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ``` ## Architecture The application uses CrewAI's multi-agent framework: ### Agents * **Researcher agent** - Has access to the Snow Leopard tool to query game metadata (titles, platforms, metascores, user scores, release dates) * **Reporting analyst agent** - Takes research findings and creates structured reports ### Snow Leopard tool A custom CrewAI tool that wraps the Snow Leopard client: ```python theme={null} class SnowLeopardMetacriticTool(BaseTool): name: str = "Snow Leopard Metacritic Data" description: str = ( "Takes a natural language question and returns game data " "including metascores, platforms, user scores, and release dates." ) def _run(self, question: str) -> str: sl_client = SnowLeopardClient() response = sl_client.retrieve(user_query=question, datafile_id=datafile_id) return json.dumps(response.data[0].rows) ``` ### Workflow The crew runs sequentially: 1. Research task queries game data based on the meeting topic 2. Reporting task compiles results into `report.md` ## Run the example ### Prerequisites * Python 3.10+ * [uv](https://docs.astral.sh/uv/) package manager * OpenAI API key * [Snow Leopard API key](https://auth.snowleopard.ai/account/api_keys) ### Setup Clone the [repository](https://github.com/SnowLeopard-AI/snowy-examples/tree/main/agent_examples/gameclub_crewai): ```bash theme={null} git clone https://github.com/SnowLeopard-AI/snowy-examples.git cd snowy-examples/agent_examples/gameclub_crewai ``` Download and prepare the dataset: 1. Download the Metacritic dataset from [Kaggle](https://www.kaggle.com/datasets/destring/metacritic-reviewed-games-since-2000) (get the `.csv` version) 2. Convert to SQLite: ```bash theme={null} uv run scripts/preparedata.py result.csv metacritic.sqlite ``` 3. Upload `metacritic.sqlite` to [Snow Leopard Playground](https://try.snowleopard.ai) Create a `.env` file: ```bash theme={null} OPENAI_API_KEY=your-openai-key SNOWLEOPARD_API_KEY=your-snowleopard-key SNOWLEOPARD_DATAFILE_ID=your-datafile-id ``` Run the crew: ```bash theme={null} uv run gameclub ``` The crew will research games and output a report to `report.md`. ## Next steps * View the [full source code on GitHub](https://github.com/SnowLeopard-AI/snowy-examples/tree/main/agent_examples/gameclub_crewai) * Learn more about [CrewAI](https://docs.crewai.com/)