Knowledge Stores

What is a Knowledge Store?

A Knowledge Store is a permissioned collection that turns raw content into searchable, citeable context for your agents:

ingest files (PDF, DOCX, TXT, MD), URLs, or raw text
auto‑chunk + embed each item for fast semantic retrieval
tag with metadata (e.g., topic, team, cik, ticker)
enforce read/edit roles per store or per document

Browse stores at here.

Prerequisites

You need	Why it matters	How to provide it
Python 3.11+	Fairo SDK requires 3.11 or newer.	`python --version`
Virtual environment	Isolate SDK dependencies.	`python -m venv fairo_env && source fairo_env/bin/activate`

1 · Install the SDK

The package is avialable on PyPI:

pip install fairo

2 · Authenticate

Generate your API key and secret here.

Then export them in your environment:

export FAIRO_API_ACCESS_KEY_ID=<your-key>
export FAIRO_API_SECRET=<your-secret>

3 · Create a knowledge store with sdk

EMBEDDING_MODEL = <your-embedding-model-id>
vector_store = FairoVectorStore(
    collection_name="faq",
    embedding_model_id=EMBEDDING_MODEL,
    collection_metadata={
        "name": "FAQ and Documentation",
        "ai_instructions": "These are FAQ, refund policy, and setup documentation chunks for Best CRM Inc.",
        "metadata_include": ["document_type", "file_name", "chunk_index", "doc_category"],
        "created_by": "faq_processor"
    },
    create_if_not_exists=True
)

You can also create stores in the UI.

4 · How to use a knowledge store in the SDK

You can create a tool to use the knowledge store to run a similarity search between the embedded documents and the query string.

Create faq_agent.py:

from fairo.core.chat.chat import ChatFairo
from langchain.tools import tool
from pydantic import BaseModel, Field
from langchain.agents import create_json_chat_agent
from langchain.prompts import ChatPromptTemplate
from fairo.core.workflow.dependency import FairoVectorStore

class InputSchema(BaseModel):
    input: str = Field(description="The user input question")

def faq_agent():
    prompt = """
	You are a helpful support agent for Best CRM Inc.

	You MUST always follow this format:
	- You must remember user data provided by the user
	- If you need to look something up, output a JSON with the key "action" set to one of the provided tools, and "action_input" with the query.
	- If you are ready to answer, output a JSON with the key "action" set to "Final Answer" and the key "action_input" with your answer text.
	- You may ONLY use the provided tool names. Do not invent new ones.

	Available tools: {tools}
	Tool names: {tool_names}
	""".strip()
    llm = ChatFairo()
    knowledge_store = FairoVectorStore(
        collection_name="faq",
    )

    class FaqQueryArgs(BaseModel):
        query: str = Field(
            ...,
            description="Query to search for information about Best CRM Inc., including FAQs, policies, and setup instructions",
        )

    @tool(args_schema=FaqQueryArgs)
    def search_faq_knowledge_store(query: str) -> str:
        """
        Search the Best CRM Inc. knowledge base for information about the CRM software,
        policies, setup instructions, and frequently asked questions.
        """
        docs = knowledge_store.similarity_search(query, k=5)
        if not docs:
            return "I don't have information about that topic in my knowledge base."
        return "\n\n".join(doc.page_content for doc in docs)

    tools = [search_faq_knowledge_store]

    prompt = ChatPromptTemplate.from_messages(
        [
            (
                "system", prompt
            ),
            ("human", "{input}"),
            ("ai", "{agent_scratchpad}"),
        ]
    )

    agent = create_json_chat_agent(
        llm=llm,
        tools=tools,
        prompt=prompt,
    )

    return agent

5 · Run with `FairoExecutor`

Create execute.py:

from fairo.core.execution.executor import FairoExecutor
from faq_agent import faq_agent

FairoExecutor(
    agents=[faq_agent],
    input_fields=["input"]
).run({"input": "What's the return policy?"})

The input_fields list must contain the keys your agent expects.

Run your agent:

python execute.py

When the run completes, view the trace trace.