Build applications that make decisions (chatbots, agents, simulations, etc...). Monitor, trace, persist, and execute on your own infrastructure.
Python aiburrchatbot-frameworkdagsgenerative-aigraphshacktoberfestllmopsllmsmlopspersistent-data-structurestate-machinestate-managementvisibility
Adaptive CRAG example
Hamza Farhan44e58b4ea1c2
diff --git a/examples/adaptive_crag/README.md b/examples/adaptive_crag/README.mdnew file mode 100644index 00000000..250cf384--- /dev/null+++ b/examples/adaptive_crag/README.md@@ -0,0 +1,22 @@+#### [Adaptive-RAG](https://arxiv.org/pdf/2403.14403) is a strategy for dynamically selecting the most suitable route for a given user query. A route could be vector database retrieval, web search, direct answer, or any other viable route.++#### [Corrective-RAG (CRAG)](https://arxiv.org/pdf/2401.15884) is a strategy for RAG that incorporates self-reflection / self-grading on retrieved documents.++So if we combine the two, we get a system that can dynamically select the most suitable route for a given user query and then self-reflect on the retrieved documents to improve the quality of the response. This is a powerful combination that can lead to more accurate and relevant responses to user queries.++We will use [LanceDB](https://lancedb.github.io/lancedb/) as our vector database and [Exa](https://exa.ai/) as our web search engine.++The possible routes that are guaranteed using `Instructor`:+1. names of all available `LanceDB` tables.+2. web_search+3. assistant+4. terminate (if the `query` is in ["exit", "quit", "q"])++So the `transitions` check for routes 2-4 and we assume that it must be _one_ of the tables otherwise.+`ask_assistant` will combine all `lancedb_results` and `exa_search_results` for context if they exist in the `state`, and then reset them to `[]`+We stop after `ask_assistant` to get the next `query` for `router`.++## Adaptive-CRAG 🧪+++We have some of the core concepts from the [Burr Docs](https://burr.dagworks.io/concepts/) in a folder and we will add that to a `LanceDB` table for Hybrid Search. You can add as many tables as you want. Each table will be a different route for the `router`.\ No newline at end of filediff --git a/examples/adaptive_crag/__init__.py b/examples/adaptive_crag/__init__.pynew file mode 100644index 00000000..e69de29bdiff --git a/examples/adaptive_crag/application.py b/examples/adaptive_crag/application.pynew file mode 100644index 00000000..18cbc1d6--- /dev/null+++ b/examples/adaptive_crag/application.py@@ -0,0 +1,537 @@+from pathlib import Path+from typing import Iterable, Literal++import google.generativeai as genai+import instructor+import lancedb+from burr.core import Application, ApplicationBuilder, State, expr, when+from burr.core.action import action+from burr.tracking import LocalTrackingClient+from dotenv import load_dotenv+from exa_py.api import Exa+from lancedb.db import DBConnection+from lancedb.embeddings import get_registry+from lancedb.pydantic import LanceModel, Vector+from lancedb.table import Table+from pydantic import BaseModel, Field++load_dotenv() # load your GOOGLE_API_KEY and EXA_API_KEY from a .env file+++ask_gemini = instructor.from_gemini(+ client=genai.GenerativeModel(model_name="gemini-1.5-flash-latest")+)+exa = Exa(api_key=None)++BURR_DOCS_DIR = Path("burr_docs")+DOC_THRESH = 512+LANCE_URI = "lance/rag"+EMS_MODEL = "BAAI/bge-small-en-v1.5" # for the embeddings in LanceDB+DEVICE = "cuda" # or "cpu"+DOCS_LIMIT = 5 # number of documents to retrieve from the database or search engine+ATTEMPTS = 3 # ask_gemini will try to call `create` this many times before giving up+++def chat_message(role: str, content: str) -> dict[str, str]:+ return {"role": role, "content": content}+++def system_message(content: str) -> dict[str, str]:+ return chat_message(role="system", content=content)+++def user_message(content: str) -> dict[str, str]:+ return chat_message(role="user", content=content)+++def assistant_message(content: str) -> dict[str, str]:+ return chat_message(role="assistant", content=content)+++def merge_short_docs(+ docs: list[str], file_name: str, doc_thresh: int = DOC_THRESH+) -> list[dict[str, str]]:+ """+ Merge short documents into longer ones for better performance.+ `file_name` is the name of the file the documents came from. It's just for metadata.+ """+ print(f"Merging {len(docs)} docs")+ merged_docs = [{"text": docs[0], "file_name": file_name}]+ for doc in docs[1:]:+ last_text = merged_docs[-1]["text"]+ if len(last_text) <= doc_thresh:+ merged_docs[-1]["text"] = last_text.strip() + "\n" + doc+ else:+ merged_docs.append({"text": doc, "file_name": file_name})+ print(f"Merged to {len(merged_docs)} docs\n")+ return merged_docs+++def load_burr_docs(+ file_names: list[str] | str | None = None,+ burr_docs_dir: Path = BURR_DOCS_DIR,+ doc_thresh: int = DOC_THRESH,+) -> list[dict[str, str]]:+ """+ Load strings from text files in `burr_docs_dir` and merge short documents.+ If `file_names` is None, load all files in the directory.+ """+ if file_names is None:+ files_iter = burr_docs_dir.glob("*.txt")+ elif isinstance(file_names, str):+ files_iter = [file_names]+ else:+ files_iter = file_names+ docs = []+ for file in files_iter:+ docs += merge_short_docs(+ docs=(burr_docs_dir / Path(file).name)+ .with_suffix(".txt")+ .read_text()+ .split("\n\n"),+ file_name=Path(file).stem,+ doc_thresh=doc_thresh,+ )+ return docs+++def add_table(+ db: DBConnection,+ table_name: str,+ data: list[dict[str, str]],+ schema: type[LanceModel],+) -> Table:+ """+ Drop the table if it exists, create a new table, add data, and create a Full-Text Search index.+ Semenaitc Search is enabled by default. So creating an FTS index makes the table Hybrid Search ready.+ Learn more about Hybrid Search in LanceDB: https://lancedb.github.io/lancedb/hybrid_search/hybrid_search/+ """+ db.drop_table(name=table_name, ignore_missing=True) # type: ignore+ table = db.create_table(name=table_name, schema=schema)+ table.add(data=data)+ table.create_fts_index(field_names="text") # type: ignore+ return table+++def route_template(+ table_names: Iterable[str],+ query: str,+ chat_history: list[dict[str, str]] | None = None,+) -> str:+ prompt = """\+<task>+You are a world-class router for user queries.+Given a user query, you may need some extra information for answering the query. So you need to select the best place to find the answer.+You have the following options:+1. You will have some vector database tables with information on specific topics. If the query is directly related to any of these topics, return the relevant table name.+2. If you can answer the query directly with your own knowledge, return "assistant".+3. If you don't have the answer to the query, you can search the internet for the answer. In this case, return "web_search".+</task>++<available_tables>+"""+ prompt += "\n".join(table_names)+ prompt += "\n</available_tables>"+ if chat_history:+ prompt += "\n\n<chat_history>\n"+ prompt += "\n".join(f"{msg['role']}: {msg['content']}" for msg in chat_history)+ prompt += "\n</chat_history>"+ prompt += f"\n\n<query>\n{query}\n</query>"+ return prompt+++# used to get a structured response from the assistant when rewriting a query+class LanceDBQuery(BaseModel):+ keywords: list[str] = Field(..., min_length=1, max_length=10)+ query: str = Field(..., min_length=10, max_length=300)++ def __str__(self) -> str:+ return ", ".join(self.keywords) + ", " + self.query+++def lancedb_query_template(query: str) -> str:+ return f"""\+<task>+You are a world-class researcher with access to a vector database that can be one of or similar to ChromaDB, Weaviate, LanceDB, VertexAI, etc.+Given a user query, rewrite the query to find the most relevant information in the vector database.+Remember that the vector database has hybrid search capability, which means it can do both full-text search and vector similarity search.+So make sure to not remove any important keywords from the query. You can even add more keywords if you think they are relevant.+Split the query into a list of keywords and a string query.+</task>++<query>+{query}+</query>+"""+++# used to get a structured response from the assistant when extracting keywords for a web search+class ExaSearchKeywords(BaseModel):+ keywords: list[str] = Field(..., min_length=2, max_length=5)++ def __str__(self) -> str:+ return ", ".join(self.keywords)+++def exa_search_query_template(query: str) -> str:+ return f"""\+<task>+You are a world-class internet researcher.+Given a user query, extract 2-5 keywords as queries for the web search. Including the topic background and main intent.+</task>++<examples>++<query>+What is Henry Feilden’s occupation?+</query>+<keywords>+Henry Feilden, occupation+</keywords>++<query>+In what city was Billy Carlson born?+</query>+<keywords>+city, Billy Carlson, born+</keywords>++<query>+What is the religion of John Gwynn?+</query>+<keywords>+religion, John Gwynn+</keywords>++<query>+What sport does Kiribati men’s national basketball team play?+</query>+<keywords>+sport, Kiribati men’s national basketball team play+</keywords>++</examples>++<query>+{query}+</query>+"""+++def evaluator_template(query: str, document: str) -> str:+ return f"""\+<task>+You are a world-class document relevance evaluator.+Given a user query, does the following document have the exact information to answer the question? Answer True or False.+</task>++<query>+{query}+</query>++<document>+{document}+</document>+"""+++def get_user_query() -> str:+ query = ""+ while not query:+ query = input("(exit, quit, q to exit) > ").strip()+ return query+++@action(reads=["db", "chat_history"], writes=["query", "route"])+def router(+ state: State, query: str, attempts: int = ATTEMPTS+) -> tuple[dict[str, str], State]:+ """+ Route the user `query` to the appropriate place for an answer.+ If the `query` is directly related to a table in the database, return the table name.+ If a web search is needed, return "web_search".+ If the `query` can be directly answered by the assistant, return "assistant".+ If the `query` contains "exit", "quit", or "q", return "terminate".+ If there is a `chat_history`, it will also be used as context for the routing.+ If it fails to route after `attempts`, it will return "assistant".+ We use `Instructor` to ensure that the router only returns valid routes.+ """+ if query.lower() in ["exit", "quit", "q"]:+ route = "terminate"+ return {"route": route}, state.update(query=query, route=route)+ db: DBConnection = state["db"]+ table_names = db.table_names()+ chat_history = state["chat_history"]+ # using this as a `response_model` to ensure the route is valid+ routes = Literal[*table_names, "web_search", "assistant"] # type: ignore+ try:+ route = ask_gemini.create(+ messages=[+ user_message(+ route_template(+ table_names=table_names, query=query, chat_history=chat_history+ )+ ) # type: ignore+ ],+ response_model=routes, # type: ignore+ max_retries=attempts,+ )+ except Exception as e:+ print(f"Error in router: {e}")+ route = "assistant"+ return {"route": route}, state.update(query=query, route=route) # type: ignore+++@action(reads=["query"], writes=["lancedb_query"])+def rewrite_query_for_lancedb(+ state: State, rewrite_attempts: int = ATTEMPTS+) -> tuple[dict[str, str], State]:+ """+ Rewrite the user `query` to find the most relevant information in the LanceDB vector database.+ """+ query = state["query"]+ try:+ query = str(+ ask_gemini.create(+ messages=[user_message(lancedb_query_template(query=query))], # type: ignore+ response_model=LanceDBQuery,+ max_retries=rewrite_attempts,+ )+ )+ except Exception as e:+ print(f"Error in rewrite_query_for_lancedb: {e}")+ return {"lancedb_query": query}, state.update(lancedb_query=query)+++@action(+ reads=["db", "route", "lancedb_query", "docs_limit"], writes=["lancedb_results"]+)+def search_lancedb(state: State) -> tuple[dict[str, list[str]], State]:+ db: DBConnection = state["db"]+ try:+ lancedb_results = (+ db.open_table(name=state["route"])+ .search(query=state["lancedb_query"], query_type="hybrid")+ .limit(limit=state["docs_limit"])+ .to_pandas()["text"]+ .tolist()+ )+ except Exception as e:+ print(f"Error in search_lancedb: {e}")+ lancedb_results = []+ return {"lancedb_results": lancedb_results}, state.update(+ lancedb_results=lancedb_results+ )+++@action(reads=["query", "lancedb_results"], writes=["lancedb_results"])+def remove_irrelevant_lancedb_results(+ state: State,+) -> tuple[dict[str, list[str]], State]:+ """+ Ask the assistant to evaluate the relevance of each retrieved document with the user `query`.+ If the assistant thinks the document is relevant, keep it in the `lancedb_results`.+ """+ lancedb_results = state["lancedb_results"]+ if not lancedb_results:+ return {"lancedb_results": lancedb_results}, state+ filtered_results = []+ for lancedb_result in lancedb_results:+ try:+ is_relevant = ask_gemini.create(+ messages=[+ user_message(+ evaluator_template(+ query=state["query"], document=lancedb_result+ )+ ) # type: ignore+ ],+ response_model=bool, # type: ignore+ max_retries=ATTEMPTS,+ )+ except Exception as e:+ print(f"Error in remove_irrelevant_lancedb_results: {e}")+ is_relevant = True+ if is_relevant:+ filtered_results.append(lancedb_result)+ return {"lancedb_results": filtered_results}, state.update(+ lancedb_results=filtered_results+ )+++@action(reads=["query"], writes=["exa_search_keywords"])+def extract_keywords_for_exa_search(+ state: State, extraction_attempts: int = ATTEMPTS+) -> tuple[dict[str, str], State]:+ """+ Extract 2-5 keywords from the user `query` for a web search.+ These keywords will be used to search the internet for the answer. Instead of the full query.+ """+ query = state["query"]+ try:+ query = str(+ ask_gemini.create(+ messages=[user_message(exa_search_query_template(query=query))], # type: ignore+ response_model=ExaSearchKeywords,+ max_retries=extraction_attempts,+ )+ )+ except Exception as e:+ print(f"Error in extract_keywords_for_web_search: {e}")+ return {"exa_search_keywords": query}, state.update(exa_search_keywords=query)+++@action(reads=["exa_search_keywords", "docs_limit"], writes=["exa_search_results"])+def search_exa(state: State) -> tuple[dict[str, list[str]], State]:+ """+ More details about the Exa API:+ - https://docs.exa.ai/reference/getting-started+ - https://github.com/exa-labs/exa-py+ """+ try:+ exa_search_results = exa.search_and_contents(+ query=state["exa_search_keywords"],+ num_results=state["docs_limit"],+ highlights=True,+ )+ exa_search_results = [res.highlights[0] for res in exa_search_results.results]+ except Exception as e:+ print(f"Error in search_exa: {e}")+ exa_search_results = []+ return {"exa_search_results": exa_search_results}, state.update(+ exa_search_results=exa_search_results+ )+++@action(+ reads=["query", "lancedb_results", "exa_search_results", "chat_history"],+ writes=["chat_history", "lancedb_results", "exa_search_results"],+)+def ask_assistant(+ state: State, attempts: int = ATTEMPTS+) -> tuple[dict[str, str], State]:+ """+ Combine the `chat_history`, `query`, `lancedb_results`, and `exa_search_results` to ask the assistant for an answer.+ `chat_history`, `lancedb_results`, and `exa_search_results` are used as context for the assistant and can be empty lists.+ """+ query = state["query"]+ lancedb_results = state.get("lancedb_results", [])+ exa_search_results = state.get("exa_search_results", [])+ messages = state["chat_history"]+ context = lancedb_results + exa_search_results+ if context:+ context = "\n".join(context)+ query = (+ query.strip()+ + "\n<additional_context>\n"+ + context+ + "\n</additional_context>"+ )+ messages.append({"role": "user", "content": query.strip()})+ try:+ response = ask_gemini.create(+ messages=messages, response_model=str, max_retries=attempts+ )+ except Exception as e:+ print(f"Error in ask_assistant: {e}")+ response = "Sorry, please try again."+ return (+ {"assistant_response": response}, # type: ignore+ state.append(chat_history=user_message(query))+ .append(+ chat_history=assistant_message(response) # type: ignore+ )+ .update(lancedb_results=[], exa_search_results=[]),+ )+++@action(reads=["chat_history"], writes=[])+def terminate(state: State) -> tuple[dict[str, list[dict[str, str]]], State]:+ return {"chat_history": state["chat_history"]}, state+++def application(+ db: DBConnection,+ app_id: str | None = None,+ username: str | None = None,+ project: str = "AdaptiveCRAG",+) -> Application:+ tracker = LocalTrackingClient(project=project)+ builder = (+ ApplicationBuilder()+ .with_actions(+ router.bind(attempts=ATTEMPTS),+ rewrite_query_for_lancedb.bind(rewrite_attempts=ATTEMPTS),+ search_lancedb,+ remove_irrelevant_lancedb_results,+ extract_keywords_for_exa_search.bind(extraction_attempts=ATTEMPTS),+ search_exa,+ ask_assistant.bind(attempts=ATTEMPTS),+ terminate,+ )+ .with_transitions(+ # if the user wants to exit the conversation+ ("router", "terminate", when(route="terminate")), # type: ignore+ # if the `query` can be directly answered by the assistant+ ("router", "ask_assistant", when(route="assistant")), # type: ignore+ # if a web search is needed+ ("router", "extract_keywords_for_exa_search", when(route="web_search")), # type: ignore+ # the database can have multiple tables for different topics+ # so it makes sense to have `when` conditions for all other routes and consider this as the default route+ # otherwise we would have to add a `when` condition for each table name+ ("router", "rewrite_query_for_lancedb"),+ ("rewrite_query_for_lancedb", "search_lancedb"),+ ("search_lancedb", "remove_irrelevant_lancedb_results"),+ # if there aren't enough relevant documents left after filtering+ # use web search to find more information+ (+ "remove_irrelevant_lancedb_results",+ "extract_keywords_for_exa_search",+ expr("len(lancedb_results) < docs_limit"), # type: ignore+ ),+ # if there are enough relevant documents even after filtering, ask the assistant for an answer+ ("remove_irrelevant_lancedb_results", "ask_assistant"),+ ("extract_keywords_for_exa_search", "search_exa"),+ ("search_exa", "ask_assistant"),+ # go back to the router every time the assistant is done answering+ ("ask_assistant", "router"),+ )+ .with_tracker("local", project=project)+ .with_identifiers(app_id=app_id, partition_key=username) # type: ignore+ .initialize_from(+ tracker,+ resume_at_next_action=True,+ default_entrypoint="router",+ default_state=dict(db=db, chat_history=[], docs_limit=DOCS_LIMIT),+ )+ )+ return builder.build()+++if __name__ == "__main__":+ lance_model = (+ get_registry()+ .get("sentence-transformers")+ .create(name=EMS_MODEL, device=DEVICE)+ )++ # define the schema of your data using Pydantic+ class LanceDoc(LanceModel):+ text: str = lance_model.SourceField()+ vector: Vector(dim=lance_model.ndims()) = lance_model.VectorField() # type: ignore+ file_name: str++ lance_db = lancedb.connect(LANCE_URI)++ burr_docs = load_burr_docs(burr_docs_dir=BURR_DOCS_DIR)+ burr_table = add_table(+ db=lance_db, table_name="burr_docs", data=burr_docs, schema=LanceDoc+ )++ app = application(db=lance_db)+ app.visualize(+ output_file_path="statemachine",+ include_conditions=True,+ include_state=False,+ format="png",+ )diff --git a/examples/adaptive_crag/burr_docs/actions.txt b/examples/adaptive_crag/burr_docs/actions.txtnew file mode 100644index 00000000..468e65a1--- /dev/null+++ b/examples/adaptive_crag/burr_docs/actions.txt@@ -0,0 +1,166 @@+Actions+Note++Actions are the core building block of Burr. They read from state and write to state. They can be synchronous and asynchonous, and have both a sync and async API. There are both function and class-based APIs.++Actions do the heavy-lifting in a workflow. They should contain all complex compute. You can define actions either through a class-based or function-based API. If actions implement async def run then will be run in an asynchronous context (and thus require one of the async application functions).++Actions have two primary responsibilities:++run – compute a result++update – modify the state++The run method should return a dictionary of the result and the update method should return the updated state, given the results of the run method. They declare their dependencies so the framework knows which state variables they read and write. This allows the framework to optimize the execution of the workflow. We call (1) a Function and (2) a Reducer (similar to Redux, if you’re familiar with frontend UI technology).++There are two APIs for defining actions: class-based and function-based. They are largely equivalent, but differ in use.++use the function-based API when you want to write something quick and terse that reads from a fixed set of state variables++use the class-based API when you want to leverage inheritance or parameterize the action in more powerful ways++Function-based actions+You can define actions by decorating a function with the @action decorator. These can return either just the updated state or a tuple of the result and the state. For example:++from burr.core import action, State++@action(reads=["var_from_state"], writes=["var_to_update"])+def custom_action(state: State) -> State:+ return state.update(var_to_update=state["var_from_state"] + 1)++app = ApplicationBuilder().with_actions(+ custom_action=custom_action+)...+Conceptually, these combine the update and run methods into a single function, and they’re both executed at the same time. You also have the option of returning the intermediate results, which is useful for tracking/debugging. The code above is equivalent to returning an empty dictionary instead of the results.++from burr.core import action, State++@action(reads=["var_from_state"], writes=["var_to_update"])+def custom_action(state: State) -> State+ return results, state.update(var_to_update=var_from_state + 1)++app = ApplicationBuilder().with_actions(+ custom_action=custom_action+)...+Function-based actions can take in parameters which are akin to passing in constructor parameters. This is done through the bind method:++@action(reads=["var_from_state"], writes=["var_to_update"])+def custom_action(state: State, increment_by: int) -> State:+ return state.update(var_to_update=state["var_from_state"] + increment_by)++app = ApplicationBuilder().with_actions(+ custom_action=custom_action.bind(increment_by=2)+)...+This is the same as functools.partial, but it is more explicit and easier to read. If an action has parameters that are not bound, they will be referred to as inputs. For example:++@action(reads=["var_from_state"], writes=["var_to_update"])+def custom_action(state: State, increment_by: int) -> State:+ return state.update(var_to_update=state["var_from_state"] + increment_by)++app = ApplicationBuilder().with_actions(+ custom_action=custom_action+)...+Will require the inputs to be passed in at runtime. See below for how to do that. You can use default values to set optional inputs as well:++@action(reads=["var_from_state"], writes=["var_to_update"])+def custom_action(state: State, increment_by: int = 1) -> State:+ result = {"var_to_update": state["var_from_state"] + increment_by}+ return state.update(var_to_update=state["var_from_state"] + increment_by)++app = ApplicationBuilder().with_actions(+ custom_action=custom_action+)...+This means that the application does not need the inputs to be set.++Class-Based Actions+You can define an action by implementing the Action class:++from burr.core import Action, State++class CustomAction(Action):+ @property+ def reads(self) -> list[str]:+ return ["var_from_state"]++ def run(self, state: State) -> dict:+ return {"var_to_update": state["var_from_state"] + 1}++ @property+ def writes(self) -> list[str]:+ return ["var_to_update"]++ def update(self, result: dict, state: State) -> State:+ return state.update(**result)+You then pass the action to the ApplicationBuilder:++from burr.core import ApplicationBuilder++app = ApplicationBuilder().with_actions(+ custom_action=CustomAction()+)...+Note that if the action has inputs, you have to define the optional inputs property:++from burr.core import Action, State++class CustomAction(Action):+ @property+ def reads(self) -> list[str]:+ return ["var_from_state"]++ def run(self, state: State, increment_by: int) -> dict:+ return {"var_to_update": state["var_from_state"] + increment_by}++ @property+ def writes(self) -> list[str]:+ return ["var_to_update"]++ def update(self, result: dict, state: State) -> State:+ return state.update(**result)++ @property+ def inputs(self) -> list[str]:+ return ["increment_by"]+See below for how to pass in inputs at runtime. If you want to use optional inputs with the class-based API, inputs will return a tuple of (required, optional) inputs. For example:++from burr.core import Action, State++class CustomAction(Action):+ ...+ def inputs(self) -> Tuple[list[str], list[str]]:+ return ["increment_by"], ["optional_input"]+Note your code will have to handle the case where optional_input is not passed in (e.g. by setting the appropriate kwargs to the run(…) method.++Refer to actions for more documentation.++Runtime Inputs+Actions can declare parameters that are not part of the state. Use this to:++Provide variables that can be bound to an action. E.g. API clients, DB clients, etc.++Provide inputs that are required as part of the application to function, e.g. human input, configuration, etc.++For example using the function based API, consider the following action:++@action(reads=["..."], writes=["..."])+def my_action(state: State, client: Client, prompt: str) -> State:+ """client & `prompt` here are something we need to pass in."""+ context = client.get_data(state["..."])+ result = llm_call(prompt, context) # some LLM call...+ return state.update(**result)+We need to pass in client and prompt somehow. Here are the ways to do that:++# (1) bind values+app = (+ ApplicationBuilder()+ # we can "bind" values to an action+ .with_actions(my_action=my_action.bind(client=client))+ ...+ .build()+)++# (2) pass them in at runtime+app.run( # or app.step, app.iterate, app.astep, etc.\n"+ halt_..., # your halt logic\n"+ inputs={"prompt": "this will be passed into `prompt`"} # <-- we pass in values here+)+For instance, say you have a chatbot. The first step will likely declare the input parameter prompt – it will take that, process it, and put the result in state. The subsequent steps will read the result of that from state.\ No newline at end of filediff --git a/examples/adaptive_crag/burr_docs/applications.txt b/examples/adaptive_crag/burr_docs/applications.txtnew file mode 100644index 00000000..60afe9c4--- /dev/null+++ b/examples/adaptive_crag/burr_docs/applications.txt@@ -0,0 +1,98 @@+Applications+Note++Applications tie everything in Burr together. They specify which actions should be included, how they connect (including conditional edges), and how to run.++Applications form the core representation of the state machine. You build them with the ApplicationBuilder. Here is the minimum that is required:++A **kwargs of actions passed to with_actions(...)++Any relevant transitions (with conditions)++An entry point – this is the first action to execute++This is shown in the example from getting started++from burr.core import ApplicationBuilder, default, expr+app = (+ ApplicationBuilder()+ .with_actions(human_input, ai_response)+ .with_transitions(+ ("human_input", "ai_response"),+ ("ai_response", "human_input")+ ).with_state(chat_history=[])+ .with_entrypoint("human_input")+ .build()+)+Running+There are four APIs for executing an application.++step/astep+Returns the tuple of the action, the result of that action, and the new state. Call this if you want to run the application step-by-step.++action, result, state = application.step()+If you’re in an async context, you can run astep instead:++action, result, state = await application.astep()+Step can also take in inputs as a dictionary, which will be passed to the action’s run function as keyword arguments. This is specifically meant for a “human in the loop” scenario, where the action needs to ask for input from a user. In this case, the control flow is meant to be interrupted to allow for the user to provide input. See inputs for more information.++action, result, state = application.step(inputs={"prompt": input()})+iterate/aiterate+Iterate just runs step in a row, functioning as a generator:++for action, result, state in application.iterate(halt_after=["final_action_1", "final_action_2"]):+ print(action.name, result)+You can also run aiterate in an async context:++async for action, result, state in application.aiterate():+ print(action.name, result)+In the synchronous context this also has a return value of a tuple of:++the action that was specified in halt_after or halt_before. In the after case the action will have already run. In the before case the action will not have run.++The result of that action, in the halt_after case, else None in the halt_before case.++The state of the application at the time of halting.++You can access this by looking at the value variable of the StopIteration exception that is thrown at the end of the loop, as is standard for python generators. See the function implementation of run to show how this is done.++In the async context, this does not return anything (asynchronous generators are not allowed a return value).++If you want it to (attempt to) run forever, you can pass empty lists to halt_after and halt_before.++Note++You can add inputs to iterate/aiterate by passing in a dictionary of inputs through the inputs parameter. This will only apply to the first action. Actions that are not the first but require inputs are considered undefined behavior.++Warning++The state machine has the capability of halting even if it does not reach one of the specified conditions – if there are no more transitions to take. This, however, is not a supported feature (and will log a warning). This is considered undefined behavior – use at your own risk, and consider adding a halting condition, or a default transition to a terminal.++run/arun+Run just calls out to iterate and returns the final state.++The halt_after and halt_before keyword arguments specify when to break out of running the state machine and return control back. halt_after will stop after the specified action(s) has run, and halt_before will stop before the specified action(s) has run. If multiple are specified, it will stop after the first one encountered, and the return values will be for that action.++action, result, state = application.run(+ halt_after=["final_action_1", "final_action_2"]+)+In the async context, you can run arun:++action, result, state = await application.arun(+ halt_after=["final_action_1", "final_action_2"]+)+Note++You can add inputs to run/arun in the same way as you can with iterate – it will only apply to the first action.++run and arun largely have the same behavior as iterate and aiterate.++stream_result/astream_result+These allow you to stream responses back. Note they work best with streaming actions. Read about them in the streaming section.++Inspection+You can ask various questions of the state machine using publicly-supported APIs:++application.graph will give you a static representation of the state machine with enough information to visualize++application.state will give you the current state of the state machine. Note that if you modify it the results will not show up – state is immutable! Modify the state through actions.\ No newline at end of filediff --git a/examples/adaptive_crag/burr_docs/cheat_sheet.txt b/examples/adaptive_crag/burr_docs/cheat_sheet.txtnew file mode 100644index 00000000..d3bf63df--- /dev/null+++ b/examples/adaptive_crag/burr_docs/cheat_sheet.txt@@ -0,0 +1,14 @@+Cheat Sheet+This is a quick overview of Burr’s design – the concepts are explored in more detail in the following sections. Read over this for a very high-level overview, or use this as a cheat sheet later.++With Burr you write an Application – this manages control flow (allowing for automated or user-blocking workflows), persistence to DBs, logs telemetry, and delegates to a variety of plugins/integrations.++Applications are composed of actions (functions that write to/read from state), and transitions (functions that determine the next action to execute based on state).++State is immutable and uses the special Burr State API. You write to it by applying a state operation (e.g. state = state.update(key=value), which returns a new state instance with the updated value.++All other production/debugging concerns are implemented as hooks, which are simple callbacks that are called at various points in the application lifecycle (store/retrieve state, log information, etc…).++Note that we did not mention LLMs above at all! That’s good – you want your LLM frameworks to be ever-so-slightly decoupled from them for the best experience (all of AI is just software, plain and simple, after all…).++And that’s the basics! Let’s dive into the details.\ No newline at end of filediff --git a/examples/adaptive_crag/burr_docs/state.txt b/examples/adaptive_crag/burr_docs/state.txtnew file mode 100644index 00000000..914242c6--- /dev/null+++ b/examples/adaptive_crag/burr_docs/state.txt@@ -0,0 +1,34 @@+State+Note++Burr’s State API enables actions to talk to each other, and enables you to persist data. Burr has a State API that allows you to manipulate state in a functional way.++The State class provides the ability to manipulate state for a given action. It is entirely immutable, meaning that you can only create new states from old ones, not modify them in place.++State manipulation is done through calling methods on the State class. The most common write are:++state.update(foo=bar) # update the state with the key "foo" set to "bar"+state.append(foo=bar) # append "bar" to the list at "foo"+state.increment(foo=1) # increment the value at "foo" by 1+state.wipe(keep=["foo", "bar"]) # remove all keys except "foo" and "bar"+state.wipe(delete=["foo", "bar"]) # remove "foo" and "bar" from the state+Warning++The State object can only be treated immutably! Calling state.update(foo=bar) will do nothing if you don’t use the value returned by the call.++The read operations extend from those in the Mapping interface, but there are a few extra:++state.subset(["foo", "bar"]) # return a new state with only the keys "foo" and "bar"+state.get_all() # return a dictionary with every key/value of the state+When an update action is run, the state is first subsetted to get just the keys that are being read from, then the action is run, and a new state is written to. This state is merged back into the original state after the action is complete. Pseudocode:++current_state = ...+read_state = current_state.subset(action.reads)+result = action.run(new_state)+write_state = current_state.subset(action.writes)+new_state = action.update(result, new_state)+current_state = current_state.merge(new_state)+If you’re used to thinking about version control, this is a bit like a commit/checkout/merge mechanism.++Reloading Prior State+Note, if state is serializable, it means that if stored, it can be reloaded. This is useful for reloading state from a previous invocation (for debugging or as part of the application), or for storing state in a database. We have capabilities here, see the state-persistence section.\ No newline at end of filediff --git a/examples/adaptive_crag/burr_docs/transitions.txt b/examples/adaptive_crag/burr_docs/transitions.txtnew file mode 100644index 00000000..08c32c5e--- /dev/null+++ b/examples/adaptive_crag/burr_docs/transitions.txt@@ -0,0 +1,35 @@+Transitions+Note++While actions form the steps taken in an application, transitions decide which one to do next. They make decisions based on state. You can use them to specify which model to call, whether a conversation is over, or any other decision that needs to be made based on the current state.++Transitions define explicitly how actions are connected and which action is available next for any given state. You can think of them as edges in a graph.++They have three main components: - The from state - The to state - The condition that must be met to move from the from state to the to++Conditions+Conditions have a few APIs, but the most common are the three convenience functions:++from burr.core import when, expr, default+with_transitions(+ ("from", "to", when(foo="bar"), # will evaluate when the state has the variable "foo" set to the value "bar"+ ("from", "to", expr('epochs>100')) # will evaluate to True when epochs is greater than 100+ ("from", "to", default) # will always evaluate to True+ ("from", "to") # leaving out a third conditions we allow defaults+)+Conditions are evaluated in the order they are specified, and the first one that evaluates to True will be the transition that is selected when determining which action to run next. If no condition evaluates to True, the application execution will stop early.++The ~ operator will invert a condition. For instance:++from burr.core import when, expr+with_transitions(+ ("from", "to", ~when(foo="baz"), # will evaluate to True when foo != baz+ ("from", "to", ~expr('epochs<=100')) # will evaluate to True when epochs hits 101+)+All keys present in the condition (E.G. foo and epochs above) must be present in the state for the condition to work. It will error otherwise.++Note++The default condition is a special case, and will always evaluate to True. It is useful for defining a “catch-all” transition that will be selected if no other condition is met. If you pass a tuple of length 2 to with_transitions, the default condition will be used.++See the transition docs for more information on the transition API.\ No newline at end of filediff --git a/examples/adaptive_crag/notebook.ipynb b/examples/adaptive_crag/notebook.ipynbnew file mode 100644index 00000000..99c4838d--- /dev/null+++ b/examples/adaptive_crag/notebook.ipynb@@ -0,0 +1,603 @@+{+ "cells": [+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "# Imports"+ ]+ },+ {+ "cell_type": "code",+ "execution_count": 15,+ "metadata": {},+ "outputs": [+ {+ "name": "stdout",+ "output_type": "stream",+ "text": [+ "The autoreload extension is already loaded. To reload it, use:\n",+ " %reload_ext autoreload\n"+ ]+ }+ ],+ "source": [+ "import time\n",+ "\n",+ "import lancedb\n",+ "from lancedb.embeddings import get_registry\n",+ "from lancedb.pydantic import LanceModel, Vector\n",+ "\n",+ "from application import (\n",+ " BURR_DOCS_DIR,\n",+ " DEVICE,\n",+ " DOCS_LIMIT,\n",+ " EMS_MODEL,\n",+ " LANCE_URI,\n",+ " add_table,\n",+ " assistant_message,\n",+ " evaluator_template,\n",+ " exa_search_query_template,\n",+ " get_user_query,\n",+ " lancedb_query_template,\n",+ " load_burr_docs,\n",+ " route_template,\n",+ " user_message,\n",+ ")\n",+ "from application import application as adaptive_crag_app\n",+ "\n",+ "%load_ext autoreload\n",+ "%autoreload 2\n",+ "%reload_ext autoreload"+ ]+ },+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "# Add Burr Docs to LanceDB "+ ]+ },+ {+ "cell_type": "code",+ "execution_count": null,+ "metadata": {},+ "outputs": [],+ "source": [+ "# sentence-transformers model for embeddings\n",+ "lance_model = (\n",+ " get_registry().get(\"sentence-transformers\").create(name=EMS_MODEL, device=DEVICE)\n",+ ")\n",+ "\n",+ "\n",+ "# define the schema of your data using Pydantic\n",+ "class LanceDoc(LanceModel):\n",+ " text: str = lance_model.SourceField()\n",+ " vector: Vector(dim=lance_model.ndims()) = lance_model.VectorField() # type: ignore\n",+ " file_name: str\n",+ "\n",+ "\n",+ "lance_db = lancedb.connect(LANCE_URI)"+ ]+ },+ {+ "cell_type": "code",+ "execution_count": 3,+ "metadata": {},+ "outputs": [+ {+ "name": "stdout",+ "output_type": "stream",+ "text": [+ "Merging 11 docs\n",+ "Merged to 4 docs\n",+ "\n",+ "Merging 47 docs\n",+ "Merged to 12 docs\n",+ "\n",+ "Merging 7 docs\n",+ "Merged to 3 docs\n",+ "\n",+ "Merging 10 docs\n",+ "Merged to 3 docs\n",+ "\n",+ "Merging 34 docs\n",+ "Merged to 9 docs\n",+ "\n"+ ]+ }+ ],+ "source": [+ "burr_docs = load_burr_docs(burr_docs_dir=BURR_DOCS_DIR)"+ ]+ },+ {+ "cell_type": "code",+ "execution_count": 4,+ "metadata": {},+ "outputs": [],+ "source": [+ "burr_table = add_table(\n",+ " db=lance_db, table_name=\"burr_docs\", data=burr_docs, schema=LanceDoc\n",+ ")"+ ]+ },+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "## Run Hybrid Search"+ ]+ },+ {+ "cell_type": "code",+ "execution_count": 5,+ "metadata": {},+ "outputs": [+ {+ "data": {+ "text/plain": [+ "['The ~ operator will invert a condition. For instance:\\nfrom burr.core import when, expr\\nwith_transitions(\\n (\"from\", \"to\", ~when(foo=\"baz\"), # will evaluate to True when foo != baz\\n (\"from\", \"to\", ~expr(\\'epochs<=100\\')) # will evaluate to True when epochs hits 101\\n)\\nAll keys present in the condition (E.G. foo and epochs above) must be present in the state for the condition to work. It will error otherwise.\\nNote\\nThe default condition is a special case, and will always evaluate to True. It is useful for defining a “catch-all” transition that will be selected if no other condition is met. If you pass a tuple of length 2 to with_transitions, the default condition will be used.',\n",+ " 'Conditions\\nConditions have a few APIs, but the most common are the three convenience functions:\\nfrom burr.core import when, expr, default\\nwith_transitions(\\n (\"from\", \"to\", when(foo=\"bar\"), # will evaluate when the state has the variable \"foo\" set to the value \"bar\"\\n (\"from\", \"to\", expr(\\'epochs>100\\')) # will evaluate to True when epochs is greater than 100\\n (\"from\", \"to\", default) # will always evaluate to True\\n (\"from\", \"to\") # leaving out a third conditions we allow defaults\\n)\\nConditions are evaluated in the order they are specified, and the first one that evaluates to True will be the transition that is selected when determining which action to run next. If no condition evaluates to True, the application execution will stop early.',\n",+ " 'from burr.core import ApplicationBuilder, default, expr\\napp = (\\n ApplicationBuilder()\\n .with_actions(human_input, ai_response)\\n .with_transitions(\\n (\"human_input\", \"ai_response\"),\\n (\"ai_response\", \"human_input\")\\n ).with_state(chat_history=[])\\n .with_entrypoint(\"human_input\")\\n .build()\\n)\\nRunning\\nThere are four APIs for executing an application.\\nstep/astep\\nReturns the tuple of the action, the result of that action, and the new state. Call this if you want to run the application step-by-step.',\n",+ " '@action(reads=[\"var_from_state\"], writes=[\"var_to_update\"])\\ndef custom_action(state: State, increment_by: int = 1) -> State:\\n result = {\"var_to_update\": state[\"var_from_state\"] + increment_by}\\n return state.update(var_to_update=state[\"var_from_state\"] + increment_by)\\napp = ApplicationBuilder().with_actions(\\n custom_action=custom_action\\n)...\\nThis means that the application does not need the inputs to be set.\\nClass-Based Actions\\nYou can define an action by implementing the Action class:\\nfrom burr.core import Action, State',\n",+ " 'action, result, state = application.step()\\nIf you’re in an async context, you can run astep instead:\\naction, result, state = await application.astep()\\nStep can also take in inputs as a dictionary, which will be passed to the action’s run function as keyword arguments. This is specifically meant for a “human in the loop” scenario, where the action needs to ask for input from a user. In this case, the control flow is meant to be interrupted to allow for the user to provide input. See inputs for more information.']"+ ]+ },+ "execution_count": 5,+ "metadata": {},+ "output_type": "execute_result"+ }+ ],+ "source": [+ "res = (\n",+ " burr_table.search(query=\"expr\", query_type=\"hybrid\")\n",+ " .limit(limit=DOCS_LIMIT)\n",+ " .to_pandas()\n",+ ")\n",+ "res.text.tolist()"+ ]+ },+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "# Prompts"+ ]+ },+ {+ "cell_type": "code",+ "execution_count": 8,+ "metadata": {},+ "outputs": [],+ "source": [+ "query = \"What are actions in Burr?\""+ ]+ },+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "## Router"+ ]+ },+ {+ "cell_type": "code",+ "execution_count": 9,+ "metadata": {},+ "outputs": [+ {+ "name": "stdout",+ "output_type": "stream",+ "text": [+ "<task>\n",+ "You are a world-class router for user queries.\n",+ "Given a user query, you may need some extra information for answering the query. So you need to select the best place to find the answer.\n",+ "You have the following options:\n",+ "1. You will have some vectorstore tables with information on specific topics. If the query is directly related to any of these topics, return the relevant table name.\n",+ "2. If you can answer the query directly with your own knowledge, return \"assistant\".\n",+ "3. If you don't have the answer to the query, you can search the internet for the answer. In this case, return \"web_search\".\n",+ "</task>\n",+ "\n",+ "<available_tables>\n",+ "burr_docs\n",+ "</available_tables>\n",+ "\n",+ "<chat_history>\n",+ "user: hello\n",+ "assistant: hi\n",+ "</chat_history>\n",+ "\n",+ "<query>\n",+ "What are actions in Burr?\n",+ "</query>\n"+ ]+ }+ ],+ "source": [+ "print(\n",+ " route_template(\n",+ " table_names=lance_db.table_names(),\n",+ " query=query,\n",+ " chat_history=[user_message(\"hello\"), assistant_message(\"hi\")],\n",+ " )\n",+ ")"+ ]+ },+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "## Rewrite Query\n",+ "Our AI will return an object of this in response:\n",+ "```python\n",+ "class LanceDBQuery(BaseModel):\n",+ " keywords: list[str] = Field(..., min_length=1, max_length=10)\n",+ " query: str = Field(..., min_length=10, max_length=300)\n",+ "\n",+ " def __str__(self) -> str:\n",+ " return \", \".join(self.keywords) + \", \" + self.query\n",+ "```"+ ]+ },+ {+ "cell_type": "code",+ "execution_count": 11,+ "metadata": {},+ "outputs": [+ {+ "name": "stdout",+ "output_type": "stream",+ "text": [+ "<task>\n",+ "You are a world-class researcher with access to a vectorstore that can be one of or similar to ChromaDB, Weaviate, LanceDB, VertexAI, etc.\n",+ "Given a user query, rewrite the query to find the most relevant information in the vectorstore.\n",+ "Remember that the vectorstore has hybrid search capability, which means it can do both full-text search and vector similarity search.\n",+ "So make sure to not remove any important keywords from the query. You can even add more keywords if you think they are relevant.\n",+ "Split the query into a list of keywords and a string query.\n",+ "</task>\n",+ "\n",+ "<query>\n",+ "What are actions in Burr?\n",+ "</query>\n",+ "\n"+ ]+ }+ ],+ "source": [+ "print(lancedb_query_template(query=query))"+ ]+ },+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "## Extract Web Search Keywords\n",+ "Our AI will return an object of this in response:\n",+ "```python\n",+ "class ExaSearchKeywords(BaseModel):\n",+ " keywords: list[str] = Field(..., min_length=2, max_length=5)\n",+ "\n",+ " def __str__(self) -> str:\n",+ " return \", \".join(self.keywords)\n",+ "```\n"+ ]+ },+ {+ "cell_type": "code",+ "execution_count": 14,+ "metadata": {},+ "outputs": [+ {+ "name": "stdout",+ "output_type": "stream",+ "text": [+ "<task>\n",+ "You are a world-class internet researcher.\n",+ "Given a user query, extract 2-5 keywords as queries for the web search. Including the topic background and main intent.\n",+ "</task>\n",+ "\n",+ "<examples>\n",+ "\n",+ "<query>\n",+ "What is Henry Feilden’s occupation?\n",+ "</query>\n",+ "<keywords>\n",+ "Henry Feilden, occupation\n",+ "</keywords>\n",+ "\n",+ "<query>\n",+ "In what city was Billy Carlson born?\n",+ "</query>\n",+ "<keywords>\n",+ "city, Billy Carlson, born\n",+ "</keywords>\n",+ "\n",+ "<query>\n",+ "What is the religion of John Gwynn?\n",+ "</query>\n",+ "<keywords>\n",+ "religion, John Gwynn\n",+ "</keywords>\n",+ "\n",+ "<query>\n",+ "What sport does Kiribati men’s national basketball team play?\n",+ "</query>\n",+ "<keywords>\n",+ "sport, Kiribati men’s national basketball team play\n",+ "</keywords>\n",+ "\n",+ "</examples>\n",+ "\n",+ "<query>\n",+ "What are actions in Burr?\n",+ "</query>\n",+ "\n"+ ]+ }+ ],+ "source": [+ "print(exa_search_query_template(query=query))"+ ]+ },+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "## Evaluate Document Relevance"+ ]+ },+ {+ "cell_type": "code",+ "execution_count": 16,+ "metadata": {},+ "outputs": [+ {+ "name": "stdout",+ "output_type": "stream",+ "text": [+ "<task>\n",+ "You are a world-class document relevance evaluator.\n",+ "Given a user query, does the following document have the exact information to answer the question? Answer True or False.\n",+ "</task>\n",+ "\n",+ "<query>\n",+ "What are actions in Burr?\n",+ "</query>\n",+ "\n",+ "<document>\n",+ "Actions are when things go burrr\n",+ "</document>\n",+ "\n"+ ]+ }+ ],+ "source": [+ "print(evaluator_template(query=query, document=\"Actions are when things go burrr\"))"+ ]+ },+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "# Application"+ ]+ },+ {+ "cell_type": "code",+ "execution_count": 6,+ "metadata": {},+ "outputs": [+ {+ "data": {+ "image/svg+xml": [+ "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"no\"?>\n",+ "<!DOCTYPE svg PUBLIC \"-//W3C//DTD SVG 1.1//EN\"\n",+ " \"http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd\">\n",+ "<!-- Generated by graphviz version 2.43.0 (0)\n",+ " -->\n",+ "<!-- Title: %3 Pages: 1 -->\n",+ "<svg width=\"726pt\" height=\"541pt\"\n",+ " viewBox=\"0.00 0.00 725.51 541.00\" xmlns=\"http://www.w3.org/2000/svg\" xmlns:xlink=\"http://www.w3.org/1999/xlink\">\n",+ "<g id=\"graph0\" class=\"graph\" transform=\"scale(1 1) rotate(0) translate(4 537)\">\n",+ "<title>%3</title>\n",+ "<polygon fill=\"white\" stroke=\"transparent\" points=\"-4,4 -4,-537 721.51,-537 721.51,4 -4,4\"/>\n",+ "<!-- router -->\n",+ "<g id=\"node1\" class=\"node\">\n",+ "<title>router</title>\n",+ "<path fill=\"none\" stroke=\"black\" d=\"M567,-466C567,-466 529,-466 529,-466 523,-466 517,-460 517,-454 517,-454 517,-442 517,-442 517,-436 523,-430 529,-430 529,-430 567,-430 567,-430 573,-430 579,-436 579,-442 579,-442 579,-454 579,-454 579,-460 573,-466 567,-466\"/>\n",+ "<text text-anchor=\"middle\" x=\"548\" y=\"-444.3\" font-family=\"Times,serif\" font-size=\"14.00\">router</text>\n",+ "</g>\n",+ "<!-- rewrite_query_for_lancedb -->\n",+ "<g id=\"node3\" class=\"node\">\n",+ "<title>rewrite_query_for_lancedb</title>\n",+ "<path fill=\"none\" stroke=\"black\" d=\"M338,-385C338,-385 156,-385 156,-385 150,-385 144,-379 144,-373 144,-373 144,-361 144,-361 144,-355 150,-349 156,-349 156,-349 338,-349 338,-349 344,-349 350,-355 350,-361 350,-361 350,-373 350,-373 350,-379 344,-385 338,-385\"/>\n",+ "<text text-anchor=\"middle\" x=\"247\" y=\"-363.3\" font-family=\"Times,serif\" font-size=\"14.00\">rewrite_query_for_lancedb</text>\n",+ "</g>\n",+ "<!-- router->rewrite_query_for_lancedb -->\n",+ "<g id=\"edge5\" class=\"edge\">\n",+ "<title>router->rewrite_query_for_lancedb</title>\n",+ "<path fill=\"none\" stroke=\"black\" d=\"M516.78,-443.05C481.3,-438.17 421.84,-428.78 372,-415 346.58,-407.97 319.07,-397.91 296.35,-388.9\"/>\n",+ "<polygon fill=\"black\" stroke=\"black\" points=\"297.51,-385.59 286.92,-385.11 294.9,-392.09 297.51,-385.59\"/>\n",+ "</g>\n",+ "<!-- extract_keywords_for_exa_search -->\n",+ "<g id=\"node6\" class=\"node\">\n",+ "<title>extract_keywords_for_exa_search</title>\n",+ "<path fill=\"none\" stroke=\"black\" d=\"M501.5,-170C501.5,-170 270.5,-170 270.5,-170 264.5,-170 258.5,-164 258.5,-158 258.5,-158 258.5,-146 258.5,-146 258.5,-140 264.5,-134 270.5,-134 270.5,-134 501.5,-134 501.5,-134 507.5,-134 513.5,-140 513.5,-146 513.5,-146 513.5,-158 513.5,-158 513.5,-164 507.5,-170 501.5,-170\"/>\n",+ "<text text-anchor=\"middle\" x=\"386\" y=\"-148.3\" font-family=\"Times,serif\" font-size=\"14.00\">extract_keywords_for_exa_search</text>\n",+ "</g>\n",+ "<!-- router->extract_keywords_for_exa_search -->\n",+ "<g id=\"edge4\" class=\"edge\">\n",+ "<title>router->extract_keywords_for_exa_search</title>\n",+ "<path fill=\"none\" stroke=\"black\" stroke-dasharray=\"5,2\" d=\"M516.76,-445.43C469.69,-441.2 386,-425.58 386,-368 386,-368 386,-368 386,-232 386,-214.89 386,-195.7 386,-180.52\"/>\n",+ "<polygon fill=\"black\" stroke=\"black\" points=\"389.5,-180.26 386,-170.26 382.5,-180.26 389.5,-180.26\"/>\n",+ "<text text-anchor=\"middle\" x=\"453\" y=\"-296.3\" font-family=\"Times,serif\" font-size=\"14.00\">route=web_search</text>\n",+ "</g>\n",+ "<!-- ask_assistant -->\n",+ "<g id=\"node8\" class=\"node\">\n",+ "<title>ask_assistant</title>\n",+ "<path fill=\"none\" stroke=\"black\" d=\"M581,-36C581,-36 493,-36 493,-36 487,-36 481,-30 481,-24 481,-24 481,-12 481,-12 481,-6 487,0 493,0 493,0 581,0 581,0 587,0 593,-6 593,-12 593,-12 593,-24 593,-24 593,-30 587,-36 581,-36\"/>\n",+ "<text text-anchor=\"middle\" x=\"537\" y=\"-14.3\" font-family=\"Times,serif\" font-size=\"14.00\">ask_assistant</text>\n",+ "</g>\n",+ "<!-- router->ask_assistant -->\n",+ "<g id=\"edge3\" class=\"edge\">\n",+ "<title>router->ask_assistant</title>\n",+ "<path fill=\"none\" stroke=\"black\" stroke-dasharray=\"5,2\" d=\"M548,-429.74C548,-413.74 548,-389.26 548,-368 548,-368 548,-368 548,-84 548,-71.47 545.99,-57.77 543.69,-46.19\"/>\n",+ "<polygon fill=\"black\" stroke=\"black\" points=\"547.07,-45.28 541.54,-36.25 540.23,-46.76 547.07,-45.28\"/>\n",+ "<text text-anchor=\"middle\" x=\"605.5\" y=\"-229.3\" font-family=\"Times,serif\" font-size=\"14.00\">route=assistant</text>\n",+ "</g>\n",+ "<!-- terminate -->\n",+ "<g id=\"node9\" class=\"node\">\n",+ "<title>terminate</title>\n",+ "<path fill=\"none\" stroke=\"black\" d=\"M651.5,-385C651.5,-385 588.5,-385 588.5,-385 582.5,-385 576.5,-379 576.5,-373 576.5,-373 576.5,-361 576.5,-361 576.5,-355 582.5,-349 588.5,-349 588.5,-349 651.5,-349 651.5,-349 657.5,-349 663.5,-355 663.5,-361 663.5,-361 663.5,-373 663.5,-373 663.5,-379 657.5,-385 651.5,-385\"/>\n",+ "<text text-anchor=\"middle\" x=\"620\" y=\"-363.3\" font-family=\"Times,serif\" font-size=\"14.00\">terminate</text>\n",+ "</g>\n",+ "<!-- router->terminate -->\n",+ "<g id=\"edge2\" class=\"edge\">\n",+ "<title>router->terminate</title>\n",+ "<path fill=\"none\" stroke=\"black\" stroke-dasharray=\"5,2\" d=\"M559.02,-429.7C565.26,-420.46 573.5,-409.15 582,-400 584.56,-397.25 587.34,-394.5 590.21,-391.85\"/>\n",+ "<polygon fill=\"black\" stroke=\"black\" points=\"592.7,-394.32 597.87,-385.07 588.06,-389.08 592.7,-394.32\"/>\n",+ "<text text-anchor=\"middle\" x=\"642.5\" y=\"-403.8\" font-family=\"Times,serif\" font-size=\"14.00\">route=terminate</text>\n",+ "</g>\n",+ "<!-- input__query -->\n",+ "<g id=\"node2\" class=\"node\">\n",+ "<title>input__query</title>\n",+ "<ellipse fill=\"none\" stroke=\"black\" stroke-dasharray=\"5,2\" cx=\"548\" cy=\"-515\" rx=\"67.69\" ry=\"18\"/>\n",+ "<text text-anchor=\"middle\" x=\"548\" y=\"-511.3\" font-family=\"Times,serif\" font-size=\"14.00\">input: query</text>\n",+ "</g>\n",+ "<!-- input__query->router -->\n",+ "<g id=\"edge1\" class=\"edge\">\n",+ "<title>input__query->router</title>\n",+ "<path fill=\"none\" stroke=\"black\" d=\"M548,-496.92C548,-490.7 548,-483.5 548,-476.6\"/>\n",+ "<polygon fill=\"black\" stroke=\"black\" points=\"551.5,-476.19 548,-466.19 544.5,-476.19 551.5,-476.19\"/>\n",+ "</g>\n",+ "<!-- search_lancedb -->\n",+ "<g id=\"node4\" class=\"node\">\n",+ "<title>search_lancedb</title>\n",+ "<path fill=\"none\" stroke=\"black\" d=\"M229,-318C229,-318 127,-318 127,-318 121,-318 115,-312 115,-306 115,-306 115,-294 115,-294 115,-288 121,-282 127,-282 127,-282 229,-282 229,-282 235,-282 241,-288 241,-294 241,-294 241,-306 241,-306 241,-312 235,-318 229,-318\"/>\n",+ "<text text-anchor=\"middle\" x=\"178\" y=\"-296.3\" font-family=\"Times,serif\" font-size=\"14.00\">search_lancedb</text>\n",+ "</g>\n",+ "<!-- rewrite_query_for_lancedb->search_lancedb -->\n",+ "<g id=\"edge6\" class=\"edge\">\n",+ "<title>rewrite_query_for_lancedb->search_lancedb</title>\n",+ "<path fill=\"none\" stroke=\"black\" d=\"M228.87,-348.92C221.17,-341.66 212.05,-333.07 203.67,-325.18\"/>\n",+ "<polygon fill=\"black\" stroke=\"black\" points=\"205.93,-322.5 196.25,-318.19 201.13,-327.59 205.93,-322.5\"/>\n",+ "</g>\n",+ "<!-- remove_irrelevant_lancedb_results -->\n",+ "<g id=\"node5\" class=\"node\">\n",+ "<title>remove_irrelevant_lancedb_results</title>\n",+ "<path fill=\"none\" stroke=\"black\" d=\"M254,-251C254,-251 12,-251 12,-251 6,-251 0,-245 0,-239 0,-239 0,-227 0,-227 0,-221 6,-215 12,-215 12,-215 254,-215 254,-215 260,-215 266,-221 266,-227 266,-227 266,-239 266,-239 266,-245 260,-251 254,-251\"/>\n",+ "<text text-anchor=\"middle\" x=\"133\" y=\"-229.3\" font-family=\"Times,serif\" font-size=\"14.00\">remove_irrelevant_lancedb_results</text>\n",+ "</g>\n",+ "<!-- search_lancedb->remove_irrelevant_lancedb_results -->\n",+ "<g id=\"edge7\" class=\"edge\">\n",+ "<title>search_lancedb->remove_irrelevant_lancedb_results</title>\n",+ "<path fill=\"none\" stroke=\"black\" d=\"M166.18,-281.92C161.46,-275.11 155.93,-267.12 150.75,-259.64\"/>\n",+ "<polygon fill=\"black\" stroke=\"black\" points=\"153.47,-257.42 144.9,-251.19 147.71,-261.4 153.47,-257.42\"/>\n",+ "</g>\n",+ "<!-- remove_irrelevant_lancedb_results->extract_keywords_for_exa_search -->\n",+ "<g id=\"edge8\" class=\"edge\">\n",+ "<title>remove_irrelevant_lancedb_results->extract_keywords_for_exa_search</title>\n",+ "<path fill=\"none\" stroke=\"black\" stroke-dasharray=\"5,2\" d=\"M128.33,-214.78C126.75,-204.88 126.9,-192.89 134,-185 142.45,-175.61 193.85,-168.21 248.05,-162.91\"/>\n",+ "<polygon fill=\"black\" stroke=\"black\" points=\"248.56,-166.37 258.19,-161.94 247.9,-159.4 248.56,-166.37\"/>\n",+ "<text text-anchor=\"middle\" x=\"253\" y=\"-188.8\" font-family=\"Times,serif\" font-size=\"14.00\">len(lancedb_results) < docs_limit</text>\n",+ "</g>\n",+ "<!-- remove_irrelevant_lancedb_results->ask_assistant -->\n",+ "<g id=\"edge9\" class=\"edge\">\n",+ "<title>remove_irrelevant_lancedb_results->ask_assistant</title>\n",+ "<path fill=\"none\" stroke=\"black\" d=\"M123.98,-214.74C120.39,-205.3 118.3,-193.78 124,-185 194.22,-76.87 268.63,-113.17 389,-67 415.61,-56.79 445.43,-46.84 471.29,-38.68\"/>\n",+ "<polygon fill=\"black\" stroke=\"black\" points=\"472.5,-41.97 480.99,-35.64 470.4,-35.29 472.5,-41.97\"/>\n",+ "</g>\n",+ "<!-- search_exa -->\n",+ "<g id=\"node7\" class=\"node\">\n",+ "<title>search_exa</title>\n",+ "<path fill=\"none\" stroke=\"black\" d=\"M481.5,-103C481.5,-103 410.5,-103 410.5,-103 404.5,-103 398.5,-97 398.5,-91 398.5,-91 398.5,-79 398.5,-79 398.5,-73 404.5,-67 410.5,-67 410.5,-67 481.5,-67 481.5,-67 487.5,-67 493.5,-73 493.5,-79 493.5,-79 493.5,-91 493.5,-91 493.5,-97 487.5,-103 481.5,-103\"/>\n",+ "<text text-anchor=\"middle\" x=\"446\" y=\"-81.3\" font-family=\"Times,serif\" font-size=\"14.00\">search_exa</text>\n",+ "</g>\n",+ "<!-- extract_keywords_for_exa_search->search_exa -->\n",+ "<g id=\"edge10\" class=\"edge\">\n",+ "<title>extract_keywords_for_exa_search->search_exa</title>\n",+ "<path fill=\"none\" stroke=\"black\" d=\"M401.76,-133.92C408.33,-126.81 416.07,-118.42 423.23,-110.66\"/>\n",+ "<polygon fill=\"black\" stroke=\"black\" points=\"425.92,-112.91 430.13,-103.19 420.78,-108.16 425.92,-112.91\"/>\n",+ "</g>\n",+ "<!-- search_exa->ask_assistant -->\n",+ "<g id=\"edge11\" class=\"edge\">\n",+ "<title>search_exa->ask_assistant</title>\n",+ "<path fill=\"none\" stroke=\"black\" d=\"M469.91,-66.92C480.48,-59.37 493.08,-50.37 504.49,-42.22\"/>\n",+ "<polygon fill=\"black\" stroke=\"black\" points=\"506.83,-44.85 512.93,-36.19 502.76,-39.15 506.83,-44.85\"/>\n",+ "</g>\n",+ "<!-- ask_assistant->router -->\n",+ "<g id=\"edge12\" class=\"edge\">\n",+ "<title>ask_assistant->router</title>\n",+ "<path fill=\"none\" stroke=\"black\" d=\"M593.46,-28.26C646.25,-38.56 717,-57.34 717,-84 717,-368 717,-368 717,-368 717,-389.8 719.06,-400.26 703,-415 686.66,-430 629.28,-438.8 589.13,-443.27\"/>\n",+ "<polygon fill=\"black\" stroke=\"black\" points=\"588.65,-439.8 579.07,-444.33 589.38,-446.76 588.65,-439.8\"/>\n",+ "</g>\n",+ "</g>\n",+ "</svg>\n"+ ],+ "text/plain": [+ "<graphviz.graphs.Digraph at 0x7f85adb3c4d0>"+ ]+ },+ "execution_count": 6,+ "metadata": {},+ "output_type": "execute_result"+ }+ ],+ "source": [+ "app = adaptive_crag_app(db=lance_db)\n",+ "app.visualize(\n",+ " output_file_path=\"statemachine\",\n",+ " include_conditions=True,\n",+ " include_state=False,\n",+ " format=\"png\",\n",+ ")"+ ]+ },+ {+ "cell_type": "code",+ "execution_count": null,+ "metadata": {},+ "outputs": [],+ "source": [+ "inputs = {\"query\": get_user_query()}\n",+ "while True:\n",+ " action, result, state = app.step(inputs=inputs) # type:ignore\n",+ " print(f\"\\nRESULT: {result}\\n\")\n",+ " if action.name == \"terminate\":\n",+ " break\n",+ " elif action.name == \"ask_assistant\":\n",+ " time.sleep(1.5)\n",+ " inputs = {\"query\": get_user_query()}"+ ]+ },+ {+ "cell_type": "code",+ "execution_count": null,+ "metadata": {},+ "outputs": [],+ "source": []+ }+ ],+ "metadata": {+ "kernelspec": {+ "display_name": ".venv",+ "language": "python",+ "name": "python3"+ },+ "language_info": {+ "codemirror_mode": {+ "name": "ipython",+ "version": 3+ },+ "file_extension": ".py",+ "mimetype": "text/x-python",+ "name": "python",+ "nbconvert_exporter": "python",+ "pygments_lexer": "ipython3",+ "version": "3.11.9"+ }+ },+ "nbformat": 4,+ "nbformat_minor": 2+}diff --git a/examples/adaptive_crag/requirements.txt b/examples/adaptive_crag/requirements.txtnew file mode 100644index 00000000..37ba1e12--- /dev/null+++ b/examples/adaptive_crag/requirements.txt@@ -0,0 +1,7 @@+burr[start]+google-generativeai+instructor+pydantic+python-dotenv+lancedb+exa_pydiff --git a/examples/adaptive_crag/statemachine.png b/examples/adaptive_crag/statemachine.pngnew file mode 100644index 00000000..3de5c9b9Binary files /dev/null and b/examples/adaptive_crag/statemachine.png differ