stores 0.0.0__tar.gz → 0.1.0__tar.gz

stores-0.1.0/.gitignore

@@ -0,0 +1,177 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# PyPI configuration file
+.pypirc
+
+# Cloned tools
+.tools/
+
+# macOS metadata file
+.DS_Store

stores-0.1.0/.python-version

@@ -0,0 +1 @@
+3.10

stores-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Silanthro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stores-0.1.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: stores
+Version: 0.1.0
+Summary: Repository of Python functions and tools for LLMs
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: dirtyjson>=1.0.8
+Requires-Dist: dotenv>=0.9.9
+Requires-Dist: fuzzywuzzy>=0.18.0
+Requires-Dist: gitpython>=3.1.44
+Requires-Dist: makefun>=1.15.6
+Requires-Dist: python-levenshtein>=0.27.1
+Requires-Dist: requests>=2.32.3
+Requires-Dist: tomli>=1.1.0; python_version < '3.11'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.49.0; extra == 'anthropic'
+Provides-Extra: google
+Requires-Dist: google-genai>=1.7.0; extra == 'google'
+Provides-Extra: langchain
+Requires-Dist: langchain-google-genai>=2.1.0; extra == 'langchain'
+Provides-Extra: langgraph
+Requires-Dist: langchain-core>=0.3.45; extra == 'langgraph'
+Requires-Dist: langchain-google-genai>=2.1.0; extra == 'langgraph'
+Requires-Dist: langgraph>=0.3.16; extra == 'langgraph'
+Provides-Extra: litellm
+Requires-Dist: litellm>=1.63.11; extra == 'litellm'
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-llms-google-genai>=0.1.4; extra == 'llamaindex'
+Requires-Dist: llama-index>=0.12.25; extra == 'llamaindex'
+Provides-Extra: openai
+Requires-Dist: openai>=1.66.5; extra == 'openai'
+Provides-Extra: openai-agent
+Requires-Dist: openai-agents>=0.0.7; extra == 'openai-agent'
+Description-Content-Type: text/markdown
+
+# stores
+
+Repository of Python functions and tools for LLMs
+
+## Why we built Stores
+
+Just as tool use is often cited as a key development in human civilization, we believe that tool use represents a major transition in AI development.
+
+**The aim of Stores is to make it super simple to build LLM Agents that use tools.**
+
+There are two main elements:
+1. A public repository of [tools](https://stores-tools.vercel.app) that anyone can contribute to
+2. This Python library that handles tool installation and formatting
+
+For more details, check out the [documentation](https://stores-tools.vercel.app/docs).
+
+## Design principles
+
+- **Open-source**: Each set of tools in the Stores collection is a public git repository. In the event the Stores database is no longer operational, the library and tools will still work as long as the git repositories exist.
+- **Isolation**: Tools are isolated in their own virtual environments. This makes it trivial to manage tools with conflicting dependencies and reduces unnecessary access to sensitive environment variables.
+- **Framework compatibility**: In order to pass information about tools, LLM providers often require different formats that can make it cumbersome to switch between providers. Stores makes it easy to output the required formats across providers.
+
+## Usage
+
+```sh
+pip install stores
+```
+
+Or if you are using `uv`:
+
+```sh
+uv add stores
+```
+
+Then load one of the available indexes and use it with your favorite LLM package.
+
+```python {6, 11}
+import anthropic
+import stores
+
+client = anthropic.Anthropic()
+
+index = stores.Index(["silanthro/hackernews"])
+
+response = client.messages.create(
+    model=model,
+    messages=messages,
+    tools=index.format_tools("anthropic"),
+)
+```

stores-0.1.0/README.md

@@ -0,0 +1,50 @@
+# stores
+
+Repository of Python functions and tools for LLMs
+
+## Why we built Stores
+
+Just as tool use is often cited as a key development in human civilization, we believe that tool use represents a major transition in AI development.
+
+**The aim of Stores is to make it super simple to build LLM Agents that use tools.**
+
+There are two main elements:
+1. A public repository of [tools](https://stores-tools.vercel.app) that anyone can contribute to
+2. This Python library that handles tool installation and formatting
+
+For more details, check out the [documentation](https://stores-tools.vercel.app/docs).
+
+## Design principles
+
+- **Open-source**: Each set of tools in the Stores collection is a public git repository. In the event the Stores database is no longer operational, the library and tools will still work as long as the git repositories exist.
+- **Isolation**: Tools are isolated in their own virtual environments. This makes it trivial to manage tools with conflicting dependencies and reduces unnecessary access to sensitive environment variables.
+- **Framework compatibility**: In order to pass information about tools, LLM providers often require different formats that can make it cumbersome to switch between providers. Stores makes it easy to output the required formats across providers.
+
+## Usage
+
+```sh
+pip install stores
+```
+
+Or if you are using `uv`:
+
+```sh
+uv add stores
+```
+
+Then load one of the available indexes and use it with your favorite LLM package.
+
+```python {6, 11}
+import anthropic
+import stores
+
+client = anthropic.Anthropic()
+
+index = stores.Index(["silanthro/hackernews"])
+
+response = client.messages.create(
+    model=model,
+    messages=messages,
+    tools=index.format_tools("anthropic"),
+)
+```

stores-0.1.0/examples/README.md

@@ -0,0 +1,75 @@
+# Examples and Tutorials
+
+This directory contains examples and tutorials to help you get started with the `stores` package.
+
+## Tutorials
+
+The `tutorials` directory contains example scripts demonstrating how to use Stores with the different LLM providers and frameworks.
+
+The example scripts are tool calling or agent workflows to generate a haiku about dreams and email it to a recipient. They leverage the LLM's ability to generate text and call tools (added via Stores) to send the email.
+
+| API or Framework                              | File Name                      |
+| --------------------------------------------- | ------------------------------ |
+| OpenAI's Chat Completions API                 | `openai_chat_completions.py`   |
+| OpenAI's Response API                         | `openai_responses.py`          |
+| OpenAI's Agents SDK                           | `openai_agents.py`             |
+| Anthropic's Claude API                        | `anthropic_api.py`             |
+| Google Gemini API with automatic tool calling | `google_gemini_auto_call.py`   |
+| Google Gemini API with manual tool calling    | `google_gemini_manual_call.py` |
+| LangChain with tool calling                   | `langchain_w_tool_calling.py`  |
+| LangGraph agent                               | `langgraph_agent.py`           |
+| LiteLLM with tool calling                     | `litellm_w_tool_calling.py`    |
+| LlamaIndex agent                              | `llamaindex_agent.py`          |
+
+## How to test the tutorials
+
+1. Install the required dependencies for the example you want to run (see Installation section below)
+2. Add GMAIL_ADDRESS and GMAIL_PASSWORD to your `.env` file (see Environment Variables section below)
+3. Run `python examples/tutorials/<file_name>.py`
+
+## Installation
+
+First, install the package with the optional dependencies you need. The package supports several LLM providers and frameworks:
+
+```bash
+# For Anthropic (Claude)
+pip install -e ".[anthropic]"
+
+# For Google (Gemini)
+pip install -e ".[google]"
+
+# For OpenAI
+pip install -e ".[openai]"
+
+# For OpenAI Agents
+pip install -e ".[openai-agent]"
+
+# For LangChain
+pip install -e ".[langchain]"
+
+# For LangGraph
+pip install -e ".[langgraph]"
+
+# For LiteLLM
+pip install -e ".[litellm]"
+
+# For LlamaIndex
+pip install -e ".[llamaindex]"
+```
+
+## Environment variables
+
+The tutorial scripts require the following environment variables:
+
+- GMAIL_ADDRESS: The Gmail address for sending emails.
+- GMAIL_PASSWORD: This is NOT your regular Gmail password, but a 16-character App Password created via https://myaccount.google.com/apppasswords (see below). Treat this like you would treat your regular password e.g. do not upload this in plaintext or share this publicly
+
+You will also need the API keys for the respective LLM providers that you are using.
+
+### App Passwords
+
+In the event that the App Password is no longer required, it can be revoked without affecting your regular password.
+
+In order to create a 16-character App Password, 2-Step Verification must be set up.
+
+See the Gmail Help article at https://support.google.com/mail/answer/185833?hl=en for detailed instructions.

stores-0.1.0/examples/quickstarts/anthropic_api.py

@@ -0,0 +1,32 @@
+"""
+This example shows how to use stores with Anthropic's API.
+"""
+
+import anthropic
+from dotenv import load_dotenv
+
+import stores
+
+# Load environment variables
+load_dotenv()
+
+# Initialize Anthropic client
+client = anthropic.Anthropic()
+
+# Load the Hacker News tool index
+index = stores.Index(["silanthro/hackernews"])
+
+# Get the response from the model
+response = client.messages.create(
+    model="claude-3-5-sonnet-20241022",
+    max_tokens=1024,
+    messages=[
+        {"role": "user", "content": "What are the top 10 posts on Hacker News today?"}
+    ],
+    tools=index.format_tools("anthropic"),  # Format tools for Anthropic
+)
+
+# Execute the tool call
+tool_call = response.content[-1]
+result = index.execute(tool_call.name, tool_call.input)
+print(f"Tool output: {result}")

stores-0.1.0/examples/quickstarts/google_gemini_auto_call.py

@@ -0,0 +1,29 @@
+"""
+This example shows how to use stores with Google's Gemini API with automatic tool calling.
+"""
+
+import os
+
+from dotenv import load_dotenv
+from google import genai
+from google.genai import types
+
+import stores
+
+# Load environment variables
+load_dotenv()
+
+# Initialize Google Gemini client
+client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
+
+# Load the Hacker News tool index
+index = stores.Index(["silanthro/hackernews"])
+
+# Initialize the chat with the model
+config = types.GenerateContentConfig(tools=index.tools)
+chat = client.chats.create(model="gemini-2.0-flash", config=config)
+
+# Get the response from the model. Gemini will automatically execute tool calls
+# and generate a response.
+response = chat.send_message("What are the top 10 posts on Hacker News today?")
+print(f"Assistant response: {response.candidates[0].content.parts[0].text}")

stores-0.1.0/examples/quickstarts/google_gemini_manual_call.py

@@ -0,0 +1,40 @@
+"""
+This example shows how to use stores with Google's Gemini API with manual tool calling.
+"""
+
+import os
+
+from dotenv import load_dotenv
+from google import genai
+from google.genai import types
+
+import stores
+
+# Load environment variables
+load_dotenv()
+
+# Initialize Google Gemini client
+client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
+
+# Load the Hacker News tool index
+index = stores.Index(["silanthro/hackernews"])
+
+# Configure the model with tools
+config = types.GenerateContentConfig(
+    tools=index.tools,
+    automatic_function_calling=types.AutomaticFunctionCallingConfig(
+        disable=True  # Disable automatic function calling to manually execute tool calls
+    ),
+)
+
+# Get the response from the model
+response = client.models.generate_content(
+    model="gemini-2.0-flash",
+    contents="What are the top 10 posts on Hacker News today?",
+    config=config,
+)
+
+# Execute the tool call
+tool_call = response.candidates[0].content.parts[0].function_call
+result = index.execute(tool_call.name, tool_call.args)
+print(f"Tool output: {result}")

stores-0.1.0/examples/quickstarts/langchain_w_tool_calling.py

@@ -0,0 +1,26 @@
+"""
+This example shows how to use stores with LangChain with native function calls.
+"""
+
+from dotenv import load_dotenv
+from langchain_google_genai import ChatGoogleGenerativeAI
+
+import stores
+
+# Load environment variables
+load_dotenv()
+
+# Load the Hacker News tool index
+index = stores.Index(["silanthro/hackernews"])
+
+# Initialize the model with tools
+model = ChatGoogleGenerativeAI(model="gemini-2.0-flash-001")
+model_with_tools = model.bind_tools(index.tools)
+
+# Get the response from the model
+response = model_with_tools.invoke("What are the top 10 posts on Hacker News today?")
+
+# Execute the tool call
+tool_call = response.tool_calls[0]
+result = index.execute(tool_call["name"], tool_call["args"])
+print(f"Tool output: {result}")

stores-0.1.0/examples/quickstarts/langgraph_agent.py

@@ -0,0 +1,31 @@
+"""
+This example shows how to use stores with LangChain and a LangGraph agent.
+"""
+
+from dotenv import load_dotenv
+from langchain_core.messages import HumanMessage
+from langchain_google_genai import ChatGoogleGenerativeAI
+from langgraph.prebuilt import create_react_agent
+
+import stores
+
+# Load environment variables
+load_dotenv()
+
+# Load the Hacker News tool index
+index = stores.Index(["silanthro/hackernews"])
+
+# Initialize the LangGraph agent
+agent_model = ChatGoogleGenerativeAI(model="gemini-2.0-flash-001")
+agent_executor = create_react_agent(agent_model, index.tools)
+
+# Get the response from the agent. The LangGraph agent will automatically execute
+# tool calls and generate a response.
+response = agent_executor.invoke(
+    {
+        "messages": [
+            HumanMessage(content="What are the top 10 posts on Hacker News today?")
+        ]
+    }
+)
+print(f"Assistant response: {response['messages'][-1].content}")

stores-0.1.0/examples/quickstarts/litellm_w_tool_calling.py

@@ -0,0 +1,32 @@
+"""
+This example shows how to use stores with LiteLLM with native function calls.
+"""
+
+import json
+
+from litellm import completion
+
+import stores
+
+# Load the Hacker News tool index
+index = stores.Index(["silanthro/hackernews"])
+
+# Get the response from the model
+response = completion(
+    model="gemini/gemini-2.0-flash-001",
+    messages=[
+        {
+            "role": "user",
+            "content": "What are the top 10 posts on Hacker News today?",
+        }
+    ],
+    tools=index.format_tools("google-gemini"),  # Format tools for Google Gemini
+)
+
+# Execute the tool call
+tool_call = response.choices[0].message.tool_calls[0]
+result = index.execute(
+    tool_call.function.name,
+    json.loads(tool_call.function.arguments),
+)
+print(f"Tool output: {result}")

stores-0.1.0/examples/quickstarts/llamaindex_agent.py

@@ -0,0 +1,28 @@
+"""
+This example shows how to use stores with a LlamaIndex agent.
+"""
+
+from dotenv import load_dotenv
+from llama_index.core.agent import AgentRunner
+from llama_index.core.tools import FunctionTool
+from llama_index.llms.google_genai import GoogleGenAI
+
+import stores
+
+# Load environment variables
+load_dotenv()
+
+# Load the Hacker News tool index
+index = stores.Index(["silanthro/hackernews"])
+
+# Initialize the LlamaIndex agent with tools
+llm = GoogleGenAI(model="models/gemini-2.0-flash-001")
+tools = [
+    FunctionTool.from_defaults(fn=fn) for fn in index.tools
+]  # Use LlamaIndex FunctionTool
+agent = AgentRunner.from_llm(tools, llm=llm, verbose=True)
+
+# Get the response from the agent. The LlamaIndex agent will automatically execute
+# tool calls and generate a response.
+response = agent.chat("What are the top 10 posts on Hacker News today?")
+print(f"Assistant response: {response}")

stores-0.1.0/examples/quickstarts/openai_agent.py

@@ -0,0 +1,33 @@
+"""
+This example shows how to use stores with OpenAI's Agent SDK.
+"""
+
+from agents import Agent, Runner, function_tool
+from dotenv import load_dotenv
+
+import stores
+
+# Load environment variables
+load_dotenv()
+
+# Load the Hacker News tool index
+index = stores.Index(["silanthro/hackernews"])
+
+# Set up the tools with Agents SDK's function_tool
+formatted_tools = [
+    # OpenAI only supports ^[a-zA-Z0-9_-]{1,64}$
+    function_tool(name_override=fn.__name__.replace(".", "_"))(fn)
+    for fn in index.tools
+]
+
+# Initialize OpenAI agent
+agent = Agent(
+    name="Hacker News Agent",
+    model="gpt-4o-mini-2024-07-18",
+    tools=formatted_tools,
+)
+
+# Get the response from the agent. The OpenAI agent will automatically execute
+# tool calls and generate a response.
+result = Runner.run_sync(agent, "What are the top 10 posts on Hacker News today?")
+print(f"Agent output: {result.final_output}")