Keep in touch - Substack - Medium - Bluesky - Docs - Youtube - Percolation Labs
Percolate is a relational-vector-graph/key-value database for building agentic systems. It provides a foundation for you to manage tools, models and agents in one place and build applications that scale in complexity.
Percolate pushes agentic workflows into the data tier, leading to a simpler application tier.
- Get set up in a fe 8000 w minutes by launching the Percolate instance on docker.
- Use the cli from source to initialize data within your local instance (see notes below).
- Use Percolate with your preferred Postgres client, without any other programming language.
-- quick ping/test
select * from percolate('What is the capital of ireland?')
--select * from percolate('What is the capital of ireland?', 'claude-3-5-sonnet-20241022')
--select * from percolate('what is percolate', 'gemini-2.0-flash')
--select * from percolate('what is percolate', 'gemini-2.0-flash-thinking-exp-01-21')-- in my testing deep seek may be slow at times, especially with large content (via their api at least)
select * from percolate('how can percolate help me with creating agentic systems',
'deepseek-chat')
--cerebras model (lower context window but good for quick questions)
select * from percolate('briefly describe percolate',
'cerebras-llama3.1-8b')
--
select * from percolate('briefly describe percolate',
'gemini-1.5-flash')When you interact with language models in Percolate, conversations are logged in your instance for audit, analysis and optimization.
We create new Session records with user questions and track each AIResponse, which may include tool calls and evaluations. One of the ways Percolate is useful is for resuming and replaying sessions or getting a better understanding of the payloads that are sent to LLM Apis.
Outside the database, use your preferred language
Percolate focuses on building agents from the data tier. But you can use Python too. To create a Python agent (and also register it in the database) follow the example below.
Below you will see an example of adding an agent that uses the get_pet_findByStatus function - (we show how to register functions and apis below) -
import percolate as p8
from pydantic import BaseModel,Field
import typing
from percolate.models import DefaultEmbeddingField
import uuid
class MyFirstAgent(BaseModel):
"""You are an agent that provides the information you are asked and a second random fact"""
id: str | uuid.UUID
name: str = Field(description="Task name")
#the default embedding field is just settings json_schema_extra.embedding_provider, so you can do that yourself
description:str = DefaultEmbeddingField(description="Task description")
@classmethod
def get_model_functions(cls):
"""i return a list of functions by key stored in the database"""
return {
'get_pet_findByStatus': "a function i use to look up pets based on their status"
}
#register creates tables to save data of this type and search for agents
#you do not not need to register the agent to use the Python examples.
p8.repository(MyFirstAgent).register()The easiest way to get started is simply to launch the docker instance and connect to postgres using your preferred client on port 5438 using postgres:postgres to login
- Note that ollama is added to the docker image by default to play with open source embeddings and it takes a minute to fetch the first time. But you can comment this out if you are not interested in this
docker compose up -dYou can run the client directly from the python project directory clients/python/percolate
- You can use the poetry project
Use the cli to apply data to your test database.
- This assumes you have launched the docker instance or you have connected to another instance of Percolate.
The command below will apply settings from a default 'project' under /studio/projects/default.
- Projects in percolate manage configurations of data such as models, agents and apis. You can also version control your projects and re-apply them later.
cd clients/python/percolate
#the default project syncs env, indexes docs in codebase and adds the test api(s) as illustrated in the next step
poetry install #the first time for deps
poetry run p8 init #this will run the init scriptUse the cli to add apis at any time - supply an optional bearer token
python percolate/cli.py add api https://petstore.swagger.io/v2/swagger.json --verbs get
#of if using percolate-db installation,
#p8 add api https://petstore.swagger.io/v2/swagger.json --verbs getAPI functions can be attached by name to entities (as shown in the example above) or searched once registered as below. This can be used by planning agents to find nd activate functions during reasoning chains.
select * from p8.query_entity('I am looking for a function to get pets that have a sold status', 'p8.Function')Because the function can be evaluated from the database, you can run an entire tool calling pipeline from the database.
- in practice we do not do this synchronously and this is just used to illustrate. If the models are not overloaded this can take about 5 seconds but if models are overloaded it could take up to 25 seconds
--this runs multiple turns to find a function, activate it, call the API that was registered above and then interpret the results
-- we use the run function which has an iteration limit that defaults to 3 turns
select * from run('please activate function get_pet_findByStatus and find two pets that are sold')Back in Python, ask questions of your agent using whatever model(s) you have API keys for - gpt-4o is the default model -
p8.Agent(MyFirstAgent).run("List some pets that are sold") #this is using the api we registered above
#p8.Agent(MyFirstAgent).run("List some pets that are sold", 'deepseek-chat')
#p8.Agent(MyFirstAgent).run("List some pets that are sold", 'claude-3-5-sonnet-20241022')
#p8.Agent(MyFirstAgent).run("List some pets that are sold", 'gemini-1.5-flash')Or talk to your agent via the database -
select * from percolate_with_agent('List some pets that are sold', 'MyAgent')When getting started you may find other cli utils useful too:
cd clients/python/percolate
#index the codebase (uses your open ai key for embeddings - in future we may pull this index down from somewhere)
python percolate/cli.py index
#now we can ask questions about what is in readmes, python or sql files in the repo
python percolate/cli.py ask 'are there SQL functions in Percolate for interacting with models like Claude?'
#and yaml...
python percolate/cli.py ask 'how do i connect to Percolate using docker compose'
# python percolate/cli.py ask 'what is our entire process of adding embeddings and flushing those embeddings to make sure entities are indexed fully'
# python percolate/cli.py ask 'how is minio used in percolate'As this repository is under heavy development and because we only run full tests on tagged releases you may want to fetch the latest tagged release. This pair of commands can help with that.
git config --global alias.latest '!git fetch --tags && git checkout $(git describe --tags `git rev-list --tags --max-count=1`)'
git latestTo install Percolate to your K8s cluster apply the manifest below to your cluster. See the documentation for more details.
#percolate-cluster.yaml
#kc apply -f percolate-cluster.yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: percolate
spec:
#the operator needs to use 16 as a postgres version
imageName: percolationlabs/postgres-base:16
instances: 1
storage:
size: 10GiTo use this you need the Cloud Native PG Operator on your cluster
kubectl apply --server-side -f \
https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/main/releases/cnpg-1.24.0.yaml
To connect to a dedicated Percolate cloud instance, you will be able request a Percolate API KEY and use the percolate client to setup and connect to a new instance.
The main reason we created Percolate is to work on a new type of query plan that involves both agents and data. We wanted to push Agentic AI down into the data tier because we think it is natural to do so. Importantly data are multi-modal and rather than using multiple stores for key-value, relational, graph and vector, we want this all in the same place, first for convenience and then for optimization. Building this optimizer is of course non trivial.
We have some things to work out regarding database background workers to achieve a great user experience for agentic workflows that use the database during multi-hop reasoning.
Another exciting avenue is an SQL coding environment that uses AI and the data and schema stored in Percolate. In the new database paradigm, it should be possible to interact with databases using natural language. We are building Percolate Studio for query composition and data visualization powered with AI.
Any issues or suggestions you add will hopefully make their way into our prioritized roadmap so feel free to suggest anything related to putting AI in the dAta tIer.
(WIP) We can map dev api to the same target as what the docker compose uses to test new endpoints. There are many ways to do this but its easiest to replace the service at the target. Stop the docker service and launch the local development instance of the API.
#ollama is included by default and it takes a moment to fetch the first time but you can comment out this service if you like
docker compose stop percolate-api
uvicorn percolate.api.main:app --port 5008 --reload Now we are running the dev server on the same location that the database etc expects e.g. if you look in the p8.ApiProxy in percolate you will see we have percolate at percolate-api:5008.
You must therefore add percolate-api mapped to localhost in your hosts files!
Building the api locally
docker buildx build --platform linux/amd64,linux/arm64 -t percolationlabs/percolate-api:latest --push .
#pull latest if needed for platform
docker pull percolationlabs/percolate-api:latest
#update docker compose service if needed
docker compose up -d --no-deps --build percolate-apiYou may in some cases want to update your /etc/hosts to resolve the server address so that your python client matches what is running in the docker for api uris.
127.0.0.1 percolate-apiTo learn more about or stay up to date on Percolate, check out the links below. Subscribe to the channels below and we look forward to hearing from you.
❤️ Please star this repo if you find it interesting ❤️
docker run -d
-p 3000:8080
-v open-webui:/app/backend/data
-e WEBUI_AUTH=false
-e OLLAMA_ENABLED=false
-e OPENAI_
73F4
API_BASE_URL=http://host.docker.internal:5009
-e DEFAULT_MODEL=gpt-40-mini
-e ENABLE_MODEL_SELECTOR=true
--name open-webui
ghcr.io/open-webui/open-webui:main
-e ALLOWED_MODELS=gpt-40-mini,gpt-4-0125-preview,claude-3-opus \
docker rm -f open-webui docker volume rm open-webui docker logs -f open-webui