From 8e45aa571e497fd5cdd36babbc9c797cda92c5e0 Mon Sep 17 00:00:00 2001 From: Thejas N U <77475353+ThejasNU@users.noreply.github.com> Date: Tue, 28 Jan 2025 15:42:25 +0530 Subject: [PATCH 1/2] Update feature branch with master (#64) --- Makefile | 38 +++ README.md | 43 ++- docs/source/guide.rst | 17 +- docs/source/install.rst | 45 ++- libs/agentc_cli/tests/test_click.py | 42 ++- .../agentc_core/analytics/create.py | 3 +- .../analytics/ddls/all_sessions.sqlpp | 2 +- .../analytics/ddls/exchanges.sqlpp | 2 +- .../analytics/ddls/last_session.sqlpp | 4 +- .../analytics/ddls/llm_generations.sqlpp | 11 + .../analytics/ddls/tool_calls.sqlpp | 2 +- .../analytics/ddls/trajectories.sqlpp | 2 +- templates/agents/with_controlflow/Makefile | 38 +++ templates/agents/with_controlflow/README.md | 49 +++- .../agents/with_controlflow/requirements.txt | 273 ++++++++++++++++++ templates/agents/with_langgraph/Makefile | 36 +++ templates/agents/with_langgraph/README.md | 44 ++- 17 files changed, 589 insertions(+), 62 deletions(-) create mode 100644 Makefile create mode 100644 libs/agentc_core/agentc_core/analytics/ddls/llm_generations.sqlpp create mode 100644 templates/agents/with_controlflow/Makefile create mode 100644 templates/agents/with_controlflow/requirements.txt create mode 100644 templates/agents/with_langgraph/Makefile diff --git a/Makefile b/Makefile new file mode 100644 index 00000000..59c589ca --- /dev/null +++ b/Makefile @@ -0,0 +1,38 @@ +dev-local-pip: init-env install-agentc-pip post-install +dev-local-poetry: init-env install-agentc-poetry post-install + +# To install agentc in any project, given that the clone +# of agent-catalog and project directory have common parent +AGENT_CATALOG_LIBS = ../agent-catalog/libs + +init-env: + @echo "----Creating Conda Environment----" + conda create -n $(or $(env_name),agentc_env) python=3.12 -y + +install-agentc-pip: + @echo "----Installing Agentc----" + @echo "This may take some time..." + conda run -n $(or $(env_name),agentc_env) bash -c "\ + pip install $(AGENT_CATALOG_LIBS)/agentc && \ + pip install $(AGENT_CATALOG_LIBS)/agentc_langchain && \ + echo '' && \ + echo '----Verifying Installation----' && \ + pip list | grep agentc && \ + echo '' && \ + echo '----agentc Usage----' && \ + agentc --help" + +install-agentc-poetry: + @echo "----Installing Agentc----" + @echo "This may take some time..." + conda run -n $(or $(env_name),agentc_env) bash -c "\ + poetry install && \ + echo '' && \ + echo '----Verifying Installation----' && \ + pip list | grep agentc && \ + echo '' && \ + echo '----agentc Usage----' && \ + agentc --help" + +post-install: + @echo "Note: Please run 'conda deactivate', followed by 'conda activate $(or $(env_name),agentc_env)' to activate your python env and run agentc commands" \ No newline at end of file diff --git a/README.md b/README.md index 55ab4f8f..58a13d4d 100644 --- a/README.md +++ b/README.md @@ -34,27 +34,40 @@ The mono-repo for the Couchbase Agent Catalog project. git clone https://github.com/couchbaselabs/agent-catalog ``` -3. You are now ready to install the Agent Catalog package! -
We recommend using Anaconda to create a virtual environment for your project to ensure no global dependencies interfere with the project. +3. Installation using Makefile + + To run the following `make` commands, you must have Anaconda and Make installed (`make` for [MacOS](https://formulae.brew.sh/formula/make), [Windows](https://gnuwin32.sourceforge.net/packages/make.htm), [Ubuntu](https://www.geeksforgeeks.org/how-to-install-make-on-ubuntu/)). + + + We recommend using Anaconda to create a virtual environment for your project to ensure no global dependencies interfere with the project. [Click here](https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html) for Anaconda installation steps. - Once anaconda or any of its distribution is installed, execute the following commands to activate the environment. + Once anaconda or any of its distribution is installed, run the following commands to create and activate a virtual environment using Anaconda and install Agentc. + Replace `agentcenv` with any other suitable environment name. + ```bash + make dev-local-pip env_name=agentcenv + conda activate agentcenv + ``` + You are now ready to explore Agentc! + +4. Manual Installation + + Alternatively, you can choose to manually install Agentc by first creating a virtual environment either using Anaconda or any other Python virtual environment manager. ```bash + # create venv using Anaconda conda create -n agentcenv python=3.12 - conda activate agentcenv ``` - Alternatively, you can use any Python virtual environment manager. Once environment is set up, execute the following command to install a local package with `pip`: ```bash cd agent-catalog - # Install the agentc package. pip install libs/agentc ``` + If you are interested in developing with langchain, also install `agentc_langchain` by running the following: ```bash @@ -95,6 +108,24 @@ The mono-repo for the Couchbase Agent Catalog project. poetry update ``` +5. Install using Makefile + + You can install Agentc without adding to your pyproject if you wish to explore first. Simply run the following make commands to create and activate a virtual environment and install the requirements. + + To run the following `make` commands, you must have Anaconda and Make installed (`make` for [MacOS](https://formulae.brew.sh/formula/make), [Windows](https://gnuwin32.sourceforge.net/packages/make.htm), [Ubuntu](https://www.geeksforgeeks.org/how-to-install-make-on-ubuntu/)). + + We recommend using Anaconda to create a virtual environment for your project to ensure no global dependencies interfere with the project. + + [Click here](https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html) for Anaconda installation steps. + + Once anaconda or any of its distribution is installed, run the following commands to create and activate a virtual environment using Anaconda and install Agentc. + Replace `agentcenv` with any other suitable environment name. + + ```bash + make dev-local-poetry env_name=agentcenv + conda activate agentcenv + ``` + ### Verifying Your Installation If you've followed the steps above, you should now have the `agentc` command line tool. diff --git a/docs/source/guide.rst b/docs/source/guide.rst index bb5c772b..06c48813 100644 --- a/docs/source/guide.rst +++ b/docs/source/guide.rst @@ -137,9 +137,9 @@ Agent analysts will follow this workflow: For logs stored locally, you can find them in the :file:`./agent-activity` directory. *We recommend the former, as it allows for easy ad-hoc analysis through Couchbase Query and/or Couchbase Analytics.* -2. **Log Transformations**: For users with Couchbase Analytics enabled, we provide four views (expressed as - Couchbase Analytics UDFs) to help you get started with conversational-based agents. - All UDFs below belong to the scope :file:`agent_activity`. +2. **Log Transformations**: For users with Couchbase Analytics enabled, we provide the following views (expressed as + Couchbase Analytics Views) to help you get started with conversational-based agents. + All Views below belong to the scope :file:`agent_activity`. .. admonition:: Sessions ``(sid, start_t, vid, msgs)`` @@ -178,6 +178,17 @@ Agent analysts will follow this workflow: This view is commonly used as input into frameworks like Ragas. + .. admonition:: LLMGenerations ``(session, llm_generations)`` + + The ``LLMGenerations`` view provides each group of messages generated by the LLM per session. + Each llm generations record contains: + + i) the session ID ``session`` and + + ii) list of llm generated messages with common grouping id per session ``llm_generations``. + + This view is commonly used to dive deeper into the LLM workings and though process. + .. admonition:: ToolCalls ``(sid, vid, tool_calls)`` The ``ToolCalls`` view provides one record per session (alt. conversation). diff --git a/docs/source/install.rst b/docs/source/install.rst index c5fe2e3e..21cc587a 100644 --- a/docs/source/install.rst +++ b/docs/source/install.rst @@ -23,39 +23,48 @@ Building From Source (with pip) git clone https://github.com/couchbaselabs/agent-catalog -3. You are now ready to install the Agent Catalog package! +3. Installation using Makefile + + To run the following ``make`` commands, you must have Anaconda and Make installed (``make`` for `MacOS `_, `Windows `_, `Ubuntu `_). We recommend using Anaconda to create a virtual environment for your project to ensure no global dependencies interfere with the project. `Click here `_ for Anaconda installation steps. - Once anaconda or any of its distribution is installed, execute the following commands to activate the environment. + Once anaconda or any of its distribution is installed, run the following commands to create and activate a virtual environment using Anaconda and install Agentc. + Replace ``agentcenv`` with any other suitable environment name. .. code-block:: bash + make dev-local-pip env_name=agentcenv + conda activate agentcenv - conda create -n agentcenv python=3.12 + You are now ready to explore Agentc! - conda activate agentcenv +4. Manual Installation - Alternatively, you can use any Python virtual environment manager. + Alternatively, you can choose to manually install Agentc by first creating a virtual environment either using Anaconda or any other Python virtual environment manager. - Once environment is set up, execute the following command to install a local package with :command:`pip`: + .. code-block:: bash + + conda create -n agentcenv python=3.12 + conda activate agentcenv + + Once environment is set up, execute the following command to install a local package with ``pip``: .. code-block:: bash cd agent-catalog - # Install the agentc package. pip install libs/agentc - If you are interested in building a ``.whl`` file (for later use in ``.whl``-based installs), use :command:`poetry` - directly: + If you are interested in developing with langchain, also install ``agentc_langchain`` by running the following: .. code-block:: bash cd libs/agentc poetry build + Building From Source (with Poetry) ---------------------------------- @@ -83,6 +92,24 @@ Building From Source (with Poetry) cd agent-catalog poetry update +5. Install using Makefile + + You can install Agentc without adding to your pyproject if you wish to explore first. Simply run the following make commands to create and activate a virtual environment and install the requirements. + + To run the following ``make`` commands, you must have Anaconda and Make installed (``make`` for `MacOS `_, `Windows `_, `Ubuntu `_). + + We recommend using Anaconda to create a virtual environment for your project to ensure no global dependencies interfere with the project. + + `Click here `_ for Anaconda installation steps. + + Once anaconda or any of its distribution is installed, run the following commands to create and activate a virtual environment using Anaconda and install Agentc. + + Replace ``agentcenv`` with any other suitable environment name. + + .. code-block:: bash + + make dev-local-poetry env_name=agentcenv + conda activate agentcenv Verifying Your Installation --------------------------- diff --git a/libs/agentc_cli/tests/test_click.py b/libs/agentc_cli/tests/test_click.py index 18fe5286..6d59f24c 100644 --- a/libs/agentc_cli/tests/test_click.py +++ b/libs/agentc_cli/tests/test_click.py @@ -408,15 +408,14 @@ def test_publish_different_versions(tmp_path, isolated_server_factory): assert row == 2 -@pytest.mark.regression -def test_ls_local(tmp_path): +@pytest.mark.smoke +def test_ls_local_empty_notindexed(tmp_path): runner = click.testing.CliRunner() with runner.isolated_filesystem(temp_dir=tmp_path) as td: - ############################################################################################################ # when the repo is empty output = runner.invoke(click_main, ["ls", "-local"]).stdout assert "Searching" not in output - ############################################################################################################ + # when there are tools and prompts, but are not indexed initialize_repo( directory=pathlib.Path(td), @@ -426,7 +425,12 @@ def test_ls_local(tmp_path): ) output = runner.invoke(click_main, ["ls", "-local"]).stdout assert "Searching" not in output - ############################################################################################################ + + +@pytest.mark.smoke +def test_ls_local_only_tools(tmp_path): + runner = click.testing.CliRunner() + with runner.isolated_filesystem(temp_dir=tmp_path) as td: # when only tools are indexed initialize_repo( directory=pathlib.Path(td), @@ -435,12 +439,16 @@ def test_ls_local(tmp_path): click_command=click_main, ) output = runner.invoke(click_main, ["ls", "tool", "-local"]).stdout - assert "TOOL" in output and "1" in output + assert "TOOL" in output and len(re.findall(r"\b1\.\s.+", output)) == 1 output = runner.invoke(click_main, ["ls", "prompt", "-local"]).stdout - assert "PROMPT" in output and "1" not in output - ############################################################################################################ + assert "PROMPT" in output and len(re.findall(r"\b1\.\s.+", output)) == 0 + + +@pytest.mark.smoke +def test_ls_local_only_prompts(tmp_path): + runner = click.testing.CliRunner() + with runner.isolated_filesystem(temp_dir=tmp_path) as td: # when only prompts are indexed - runner.invoke(click_main, ["clean", "local", "--kind", "tool", "-y"]) initialize_repo( directory=pathlib.Path(td), repo_kind=ExampleRepoKind.INDEXED_CLEAN_PROMPTS_TRAVEL, @@ -448,10 +456,15 @@ def test_ls_local(tmp_path): click_command=click_main, ) output = runner.invoke(click_main, ["ls", "prompt", "-local"]).stdout - assert "PROMPT" in output and "1" in output + assert "PROMPT" in output and len(re.findall(r"\b1\.\s.+", output)) == 1 output = runner.invoke(click_main, ["ls", "tool", "-local"]).stdout - assert "TOOL" in output and "1" not in output - ############################################################################################################ + assert "TOOL" in output and len(re.findall(r"\b1\.\s.+", output)) == 0 + + +@pytest.mark.smoke +def test_ls_local_both_tools_prompts(tmp_path): + runner = click.testing.CliRunner() + with runner.isolated_filesystem(temp_dir=tmp_path) as td: # when there are both tools and prompts initialize_repo( directory=pathlib.Path(td), @@ -460,9 +473,8 @@ def test_ls_local(tmp_path): click_command=click_main, ) output = runner.invoke(click_main, ["ls", "prompt", "-local"]).stdout - assert "PROMPT" in output and "1" in output + assert "PROMPT" in output and len(re.findall(r"\b1\.\s.+", output)) == 1 output = runner.invoke(click_main, ["ls", "tool", "-local"]).stdout - assert "TOOL" in output and "1" in output + assert "TOOL" in output and len(re.findall(r"\b1\.\s.+", output)) == 1 output = runner.invoke(click_main, ["ls", "-local"]).stdout assert "PROMPT" in output and "TOOL" in output and len(re.findall(r"\b1\.\s.+", output)) == 2 - ############################################################################################################ diff --git a/libs/agentc_core/agentc_core/analytics/create.py b/libs/agentc_core/agentc_core/analytics/create.py index 87f93164..4b7f8b58 100644 --- a/libs/agentc_core/agentc_core/analytics/create.py +++ b/libs/agentc_core/agentc_core/analytics/create.py @@ -54,8 +54,7 @@ def create_analytics_udfs(cluster: couchbase.cluster.Cluster, bucket: str) -> No with open(ddl_file, "r") as fp: raw_ddl_string = fp.read() ddl_string = ( - raw_ddl_string.replace("[ANALYTICS?]", "ANALYTICS") - .replace("[BUCKET_NAME]", bucket) + raw_ddl_string.replace("[BUCKET_NAME]", bucket) .replace("[SCOPE_NAME]", DEFAULT_AUDIT_SCOPE) .replace("[LOG_COLLECTION_NAME]", DEFAULT_AUDIT_COLLECTION) ) diff --git a/libs/agentc_core/agentc_core/analytics/ddls/all_sessions.sqlpp b/libs/agentc_core/agentc_core/analytics/ddls/all_sessions.sqlpp index ad99beb6..472ae1df 100644 --- a/libs/agentc_core/agentc_core/analytics/ddls/all_sessions.sqlpp +++ b/libs/agentc_core/agentc_core/analytics/ddls/all_sessions.sqlpp @@ -1,4 +1,4 @@ -CREATE OR REPLACE ANALYTICS VIEW Sessions AS +CREATE OR REPLACE ANALYTICS VIEW `[BUCKET_NAME]`.`[SCOPE_NAME]`.Sessions AS WITH DeDuplicatedLogs AS ( FROM diff --git a/libs/agentc_core/agentc_core/analytics/ddls/exchanges.sqlpp b/libs/agentc_core/agentc_core/analytics/ddls/exchanges.sqlpp index 164a2fad..e0d1388e 100644 --- a/libs/agentc_core/agentc_core/analytics/ddls/exchanges.sqlpp +++ b/libs/agentc_core/agentc_core/analytics/ddls/exchanges.sqlpp @@ -1,6 +1,6 @@ -- Note: all_sessions.sqlpp should be run before this script. -- TODO (GLENN): The purpose of this view is to aid in using Ragas, but we should use the raw_logs instead. -CREATE OR REPLACE ANALYTICS VIEW LatestMessages AS +CREATE OR REPLACE ANALYTICS VIEW `[BUCKET_NAME]`.`[SCOPE_NAME]`.LatestMessages AS WITH LatestGenerations AS ( FROM `[BUCKET_NAME]`.`[SCOPE_NAME]`.`[LOG_COLLECTION_NAME]` AS s diff --git a/libs/agentc_core/agentc_core/analytics/ddls/last_session.sqlpp b/libs/agentc_core/agentc_core/analytics/ddls/last_session.sqlpp index c7fe5a83..d9a2d881 100644 --- a/libs/agentc_core/agentc_core/analytics/ddls/last_session.sqlpp +++ b/libs/agentc_core/agentc_core/analytics/ddls/last_session.sqlpp @@ -1,9 +1,9 @@ -- Note: all_sessions.sqlpp should be run before this script. -CREATE OR REPLACE [ANALYTICS?] FUNCTION +CREATE OR REPLACE ANALYTICS FUNCTION `[BUCKET_NAME]`.`[SCOPE_NAME]`.LastSession () { ( FROM - `[BUCKET_NAME]`.`[SCOPE_NAME]`.Sessions() AS s + `[BUCKET_NAME]`.`[SCOPE_NAME]`.Sessions AS s SELECT VALUE s.sid ORDER BY diff --git a/libs/agentc_core/agentc_core/analytics/ddls/llm_generations.sqlpp b/libs/agentc_core/agentc_core/analytics/ddls/llm_generations.sqlpp new file mode 100644 index 00000000..f22be59e --- /dev/null +++ b/libs/agentc_core/agentc_core/analytics/ddls/llm_generations.sqlpp @@ -0,0 +1,11 @@ +CREATE OR REPLACE ANALYTICS VIEW `[BUCKET_NAME]`.`[SCOPE_NAME]`.LLMGenerations AS + SELECT + session, + grouping_id, + ( FROM g gi SELECT VALUE gi.rl ) AS generation + FROM + `[BUCKET_NAME]`.`[SCOPE_NAME]`.`[LOG_COLLECTION_NAME]` AS rl + GROUP BY + rl.session AS session, + rl.`grouping` AS grouping_id + GROUP AS g; \ No newline at end of file diff --git a/libs/agentc_core/agentc_core/analytics/ddls/tool_calls.sqlpp b/libs/agentc_core/agentc_core/analytics/ddls/tool_calls.sqlpp index e86993e5..95315640 100644 --- a/libs/agentc_core/agentc_core/analytics/ddls/tool_calls.sqlpp +++ b/libs/agentc_core/agentc_core/analytics/ddls/tool_calls.sqlpp @@ -1,5 +1,5 @@ -- Note: all_sessions.sqlpp should be run before this script. -CREATE OR REPLACE ANALYTICS VIEW ToolCalls AS +CREATE OR REPLACE ANALYTICS VIEW `[BUCKET_NAME]`.`[SCOPE_NAME]`.ToolCalls AS FROM -- The tool calls our LLM has authored. Sessions AS s1, diff --git a/libs/agentc_core/agentc_core/analytics/ddls/trajectories.sqlpp b/libs/agentc_core/agentc_core/analytics/ddls/trajectories.sqlpp index 6cdb5c1d..27b9a08d 100644 --- a/libs/agentc_core/agentc_core/analytics/ddls/trajectories.sqlpp +++ b/libs/agentc_core/agentc_core/analytics/ddls/trajectories.sqlpp @@ -1,5 +1,5 @@ -- Note: all_sessions.sqlpp should be run before this script. -CREATE OR REPLACE ANALYTICS VIEW Walks AS +CREATE OR REPLACE ANALYTICS VIEW `[BUCKET_NAME]`.`[SCOPE_NAME]`.Walks AS FROM Sessions AS s, s.msgs AS msg diff --git a/templates/agents/with_controlflow/Makefile b/templates/agents/with_controlflow/Makefile new file mode 100644 index 00000000..f889b15e --- /dev/null +++ b/templates/agents/with_controlflow/Makefile @@ -0,0 +1,38 @@ +cf-pip: init-env install-with-pip post-install +cf-poetry: init-env install-with-poetry post-install + +AGENT_CATALOG_LIBS = ../../../libs + +init-env: + @echo "----Creating Conda Environment----" + conda create -n $(or $(env_name),agentc_env) python=3.12 -y + +install-with-poetry: + @echo "----Installing Requirements----" + @echo "This may take some time..." + conda run -n $(or $(env_name),agentc_env) bash -c "\ + poetry install --with analysis && \ + echo '' && \ + echo '----Verifying Installation----' && \ + pip list | grep agentc && \ + echo '' && \ + echo '----agentc Usage----' && \ + agentc --help" + +install-with-pip: + @echo "----Installing Requirements----" + @echo "This may take some time..." + conda run -n $(or $(env_name),agentc_env) bash -c "\ + pip install $(AGENT_CATALOG_LIBS)/agentc && \ + pip install $(AGENT_CATALOG_LIBS)/agentc_langchain && \ + pip install -r requirements.txt && \ + echo '' && \ + echo '----Verifying Installation----' && \ + pip list | grep agentc && \ + controlflow version && \ + echo '' && \ + echo '----agentc Usage----' && \ + agentc --help" + +post-install: + @echo "Note: Please run 'conda deactivate', followed by 'conda activate $(or $(env_name),agentc_env)' to activate your python env and run agentc commands" \ No newline at end of file diff --git a/templates/agents/with_controlflow/README.md b/templates/agents/with_controlflow/README.md index 43fc52b9..9d1e9c93 100644 --- a/templates/agents/with_controlflow/README.md +++ b/templates/agents/with_controlflow/README.md @@ -15,6 +15,7 @@ This directory contains a starter project for building agents with Couchbase, Co ``` 3. Agent Catalog uses Git for its versioning. + Run the command below to initialize a new Git repository within the `templates/agents/with_controlflow` directory. ```bash @@ -24,25 +25,51 @@ This directory contains a starter project for building agents with Couchbase, Co ``` 4. Installing anaconda. + We recommend using Anaconda to create a virtual environment for your project to ensure no global dependencies interfere with the project. [Click here](https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html) for Anaconda installation steps. - Once anaconda or any of its distribution is installed, execute the following commands to activate the environment. +5. Install this project with Poetry from Makefile. + + Ensure you have Anaconda and Make installed (`make` for [MacOS](https://formulae.brew.sh/formula/make), [Windows](https://gnuwin32.sourceforge.net/packages/make.htm), [Ubuntu](https://www.geeksforgeeks.org/how-to-install-make-on-ubuntu/)). + Run the following commands to create and activate a virtual environment using Anaconda and install all the requirements required to run this example. + + Replace `travel_agent` with any other suitable environment name. ```bash - conda create -n travel-agent python=3.12 + make cf-poetry env_name=travel_agent + conda activate travel_agent + ``` - conda activate travel-agent + Alternatively, you can install the project with `pip` with the following commands. + ```bash + make cf-pip env_name=travel_agent + conda activate travel_agent ``` -5. Install this project with Poetry (with the `analysis` group dependencies). We recommend using Anaconda to create a virtual environment for your project to ensure no global dependencies interfere with the project. +6. Manually install this project. + Create a virtual environment either using Anaconda or any other Python environment manager. + ```bash + # create venv using Anaconda + conda create -n travel_agent python=3.12 + conda activate travel_agent + ``` + + Install the example using Poetry ```bash poetry install --with analysis ``` -6. Run `agentc` to make sure this project has installed correctly (note that your first run will take a couple of + Alternatively, install the example using `pip` + ```bash + pip install ../../../libs/agentc + pip install ../../../libs/agentc_langchain + pip install -r requirements.txt + ``` + +7. Run `agentc` to make sure this project has installed correctly (note that your first run will take a couple of seconds as certain packages need to be compiled, subsequent runs will be faster). ```bash @@ -72,7 +99,7 @@ This directory contains a starter project for building agents with Couchbase, Co See: https://docs.couchbase.com or https://couchbaselabs.github.io/agent-catalog/index.html# for more information. ``` -7. Make sure your Git repo is clean, and run `agentc index` to index your tools and prompts. +8. Make sure your Git repo is clean, and run `agentc index` to index your tools and prompts. Note that `tools` and `prompts` are _relative paths_ to the `tools` and `prompts` folder. ```bash @@ -85,7 +112,7 @@ This directory contains a starter project for building agents with Couchbase, Co _Hint: if you've made changes but want to keep the same commit ID for the later "publish" step, use `git add $MY_FILES` followed by `git commit --amend`!_ -8. Start up a Couchbase instance. +9. Start up a Couchbase instance. 1. For those interested in using a local Couchbase instance, see [here](https://docs.couchbase.com/server/current/install/install-intro.html). @@ -110,14 +137,14 @@ This directory contains a starter project for building agents with Couchbase, Co You'll need to navigate to your instance's UI (for local instances, this is on http://localhost:8091) to install this sample bucket. -9. Create a `.env` file from the `.env.example` file and tweak this to your environment. +10. Create a `.env` file from the `.env.example` file and tweak this to your environment. ```bash cp .env.example .env vi .env ``` -10. Publish your local agent catalog to your Couchbase instance with `agentc publish`. +11. Publish your local agent catalog to your Couchbase instance with `agentc publish`. Your Couchbase instance details in the `.env` file will be used for authentication. Again, this specific starter agent uses the `travel-sample` bucket. @@ -125,7 +152,7 @@ This directory contains a starter project for building agents with Couchbase, Co agentc publish tool prompt --bucket travel-sample ``` -11. Start a prefect server and run your agent! +12. Start a prefect server and run your agent! ```bash export PREFECT_API_URL=http://127.0.0.1:4200/api @@ -133,7 +160,7 @@ This directory contains a starter project for building agents with Couchbase, Co python agent.py ``` -12. Let's now talk with our agent! +13. Let's now talk with our agent! I initiated three conversations: two "positive" and one "negative". The first positive case is given below: diff --git a/templates/agents/with_controlflow/requirements.txt b/templates/agents/with_controlflow/requirements.txt new file mode 100644 index 00000000..9180dd1e --- /dev/null +++ b/templates/agents/with_controlflow/requirements.txt @@ -0,0 +1,273 @@ +aiohappyeyeballs==2.4.4 +aiohttp==3.11.11 +aiosignal==1.3.2 +aiosqlite==0.20.0 +alembic==1.14.1 +annotated-types==0.7.0 +anthropic==0.45.0 +anyio==4.8.0 +appdirs==1.4.4 +appnope==0.1.4 +apprise==1.9.2 +argcomplete==3.5.3 +argon2-cffi==23.1.0 +argon2-cffi-bindings==21.2.0 +arrow==1.3.0 +asgi-lifespan==2.1.0 +asttokens==3.0.0 +async-lru==2.0.4 +asyncpg==0.30.0 +attrs==25.1.0 +babel==2.16.0 +beautifulsoup4==4.12.3 +black==24.10.0 +bleach==6.2.0 +cachetools==5.5.1 +certifi==2024.12.14 +cffi==1.17.1 +cfgv==3.4.0 +chardet==5.2.0 +charset-normalizer==3.4.1 +click==8.1.8 +cloudpickle==3.1.1 +colorama==0.4.6 +comm==0.2.2 +controlflow @ git+https://github.com/PrefectHQ/ControlFlow@f259fa8144ed31b8bde5902a2de8548dd4601ce5 +coolname==2.2.0 +couchbase==4.3.4 +croniter==6.0.0 +cryptography==44.0.0 +dataclasses-json==0.6.7 +datamodel-code-generator==0.26.5 +datasets==2.14.4 +dateparser==1.2.0 +debugpy==1.8.12 +decorator==5.1.1 +defusedxml==0.7.1 +Deprecated==1.2.17 +dill==0.3.7 +dirtyjson==1.0.8 +diskcache==5.6.3 +distlib==0.3.9 +distro==1.9.0 +dnspython==2.7.0 +docker==7.1.0 +EditorConfig==0.17.0 +email_validator==2.2.0 +exceptiongroup==1.2.2 +executing==2.2.0 +fastapi==0.115.7 +fastjsonschema==2.21.1 +filelock==3.17.0 +filetype==1.2.0 +fqdn==1.5.1 +frozenlist==1.5.0 +fsspec==2024.12.0 +genson==1.3.0 +gitdb==4.0.12 +gitignore_parser==0.1.11 +GitPython==3.1.44 +graphviz==0.20.3 +greenlet==3.1.1 +griffe==1.5.5 +h11==0.14.0 +h2==4.1.0 +hpack==4.1.0 +httpcore==1.0.7 +httpx==0.28.1 +httpx-sse==0.4.0 +huggingface-hub==0.27.1 +humanize==4.11.0 +hyperframe==6.1.0 +identify==2.6.6 +idna==3.10 +importlib_metadata==8.5.0 +inflect==5.6.2 +iniconfig==2.0.0 +ipykernel==6.29.5 +ipython==8.31.0 +ipywidgets==8.1.5 +isoduration==20.11.0 +isort==5.13.2 +jedi==0.19.2 +Jinja2==3.1.5 +jinja2-humanize-extension==0.4.0 +jiter==0.8.2 +joblib==1.4.2 +jsbeautifier==1.15.1 +json5==0.10.0 +jsonpatch==1.33 +jsonpointer==3.0.0 +jsonschema==4.23.0 +jsonschema-spec==0.2.4 +jsonschema-specifications==2023.7.1 +jupyter-events==0.11.0 +jupyter-lsp==2.2.5 +jupyter_client==8.6.3 +jupyter_core==5.7.2 +jupyter_server==2.15.0 +jupyter_server_terminals==0.5.3 +jupyterlab==4.3.4 +jupyterlab_pygments==0.3.0 +jupyterlab_server==2.27.3 +jupyterlab_widgets==3.0.13 +langchain==0.3.15 +langchain-anthropic==0.3.4 +langchain-community==0.3.15 +langchain-core==0.3.31 +langchain-openai==0.2.14 +langchain-text-splitters==0.3.5 +langsmith==0.3.1 +lazy-object-proxy==1.10.0 +linkify-it-py==2.0.3 +llama-cloud==0.1.10 +llama-index==0.12.14 +llama-index-agent-openai==0.4.2 +llama-index-cli==0.4.0 +llama-index-core==0.12.14 +llama-index-embeddings-openai==0.3.1 +llama-index-indices-managed-llama-cloud==0.6.4 +llama-index-llms-openai==0.3.14 +llama-index-multi-modal-llms-openai==0.4.2 +llama-index-program-openai==0.3.1 +llama-index-question-gen-openai==0.3.0 +llama-index-readers-file==0.4.4 +llama-index-readers-llama-parse==0.4.0 +llama-parse==0.5.20 +Mako==1.3.8 +Markdown==3.7 +markdown-it-py==3.0.0 +markdownify==0.14.1 +MarkupSafe==3.0.2 +marshmallow==3.26.0 +matplotlib-inline==0.1.7 +mdit-py-plugins==0.4.2 +mdurl==0.1.2 +mistune==3.1.0 +mpmath==1.3.0 +multidict==6.1.0 +multiprocess==0.70.15 +mypy-extensions==1.0.0 +nbclient==0.10.2 +nbconvert==7.16.5 +nbformat==5.10.4 +nest-asyncio==1.6.0 +networkx==3.4.2 +nltk==3.9.1 +nodeenv==1.9.1 +notebook_shim==0.2.4 +numpy==2.2.2 +oauthlib==3.2.2 +openai==1.60.1 +openapi-schema-validator==0.6.3 +openapi-spec-validator==0.6.0 +openapi3-parser==1.1.19 +opentelemetry-api==1.29.0 +orjson==3.10.15 +overrides==7.7.0 +packaging==24.2 +pandas==2.2.3 +pandocfilters==1.5.1 +parso==0.8.4 +pathable==0.4.4 +pathspec==0.12.1 +pendulum==3.0.0 +pexpect==4.9.0 +pillow==11.1.0 +platformdirs==4.3.6 +pluggy==1.5.0 +prance==23.6.21.0 +pre-commit==3.8.0 +prefect==3.1.12 +prometheus_client==0.21.1 +prompt_toolkit==3.0.50 +propcache==0.2.1 +psutil==6.1.1 +ptyprocess==0.7.0 +pure_eval==0.2.3 +py-openapi-schema-to-json-schema==0.0.3 +pyarrow==19.0.0 +pycparser==2.22 +pydantic==2.8.2 +pydantic-extra-types==2.10.2 +pydantic-settings==2.7.1 +pydantic_core==2.20.1 +Pygments==2.19.1 +pypdf==5.2.0 +pytest==7.4.4 +python-dateutil==2.9.0.post0 +python-dotenv==1.0.1 +python-json-logger==3.2.1 +python-slugify==8.0.4 +python-socks==2.6.1 +pytz==2024.2 +PyYAML==6.0.2 +pyzmq==26.2.0 +ragas==0.2.12 +readchar==4.2.1 +referencing==0.30.2 +regex==2024.11.6 +requests==2.32.3 +requests-oauthlib==2.0.0 +requests-toolbelt==1.0.0 +rfc3339-validator==0.1.4 +rfc3986-validator==0.1.1 +rich==13.9.4 +rpds-py==0.22.3 +ruamel.yaml==0.18.10 +ruamel.yaml.clib==0.2.12 +safetensors==0.5.2 +scikit-learn==1.6.1 +scipy==1.15.1 +semantic-version==2.10.0 +Send2Trash==1.8.3 +sentence-transformers==3.4.0 +setuptools==75.8.0 +shellingham==1.5.4 +six==1.17.0 +smmap==5.0.2 +sniffio==1.3.1 +soupsieve==2.6 +SQLAlchemy==2.0.37 +stack-data==0.6.3 +starlette==0.45.3 +striprtf==0.0.26 +sympy==1.13.1 +tenacity==9.0.0 +terminado==0.18.1 +text-unidecode==1.3 +textual==1.0.0 +threadpoolctl==3.5.0 +tiktoken==0.8.0 +tinycss2==1.4.0 +tokenizers==0.21.0 +toml==0.10.2 +torch==2.5.1 +tornado==6.4.2 +tqdm==4.67.1 +traitlets==5.14.3 +transformers==4.48.1 +typer==0.13.1 +types-python-dateutil==2.9.0.20241206 +typing-inspect==0.9.0 +typing_extensions==4.12.2 +tzdata==2025.1 +tzlocal==5.2 +uc-micro-py==1.0.3 +ujson==5.10.0 +uri-template==1.3.0 +urllib3==2.3.0 +uvicorn==0.34.0 +virtualenv==20.29.1 +wcwidth==0.2.13 +webcolors==24.11.1 +webencodings==0.5.1 +websocket-client==1.8.0 +websockets==13.1 +wheel==0.44.0 +widgetsnbextension==4.0.13 +wrapt==1.17.2 +xxhash==3.5.0 +yarl==1.18.3 +zipp==3.21.0 +zstandard==0.23.0 diff --git a/templates/agents/with_langgraph/Makefile b/templates/agents/with_langgraph/Makefile new file mode 100644 index 00000000..663f295a --- /dev/null +++ b/templates/agents/with_langgraph/Makefile @@ -0,0 +1,36 @@ +lg-pip: init-env install-with-pip post-install +lg-poetry: init-env install-with-poetry post-install + +AGENT_CATALOG_LIBS = ../../../libs + +init-env: + @echo "----Creating Conda Environment----" + conda create -n $(or $(env_name),agentc_env) python=3.12 -y + +install-with-poetry: + @echo "----Installing Requirements----" + @echo "This may take some time..." + conda run -n $(or $(env_name),agentc_env) bash -c "\ + poetry install && \ + echo '' && \ + echo '----Verifying Installation----' && \ + pip list | grep agentc && \ + echo '' && \ + echo '----agentc Usage----' && \ + agentc --help" + +install-with-pip: + @echo "----Installing Requirements----" + @echo "This may take some time..." + conda run -n $(or $(env_name),agentc_env) bash -c "\ + pip install $(AGENT_CATALOG_LIBS)/agentc && \ + pip install $(AGENT_CATALOG_LIBS)/agentc_langchain && \ + echo '' && \ + echo '----Verifying Installation----' && \ + pip list | grep agentc && \ + echo '' && \ + echo '----agentc Usage----' && \ + agentc --help" + +post-install: + @echo "Note: Please run 'conda deactivate', followed by 'conda activate $(or $(env_name),agentc_env)' to activate your python env and run agentc commands" \ No newline at end of file diff --git a/templates/agents/with_langgraph/README.md b/templates/agents/with_langgraph/README.md index 8aa3544b..94aa4db3 100644 --- a/templates/agents/with_langgraph/README.md +++ b/templates/agents/with_langgraph/README.md @@ -28,21 +28,45 @@ This directory contains a starter project for building agents with Couchbase, La [Click here](https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html) for Anaconda installation steps. - Once anaconda or any of its distribution is installed, execute the following commands to activate the environment. +5. Install this project with Poetry from Makefile. + Ensure you have Anaconda and Make installed (`make` for [MacOS](https://formulae.brew.sh/formula/make), [Windows](https://gnuwin32.sourceforge.net/packages/make.htm), [Ubuntu](https://www.geeksforgeeks.org/how-to-install-make-on-ubuntu/)). + + Run the following commands to create and activate a virtual environment using Anaconda and install all the requirements required to run this example. + + Replace `research_agent` with any other suitable environment name. ```bash - conda create -n research-agent python=3.12 + make lg-poetry env_name=research_agent + conda activate research_agent + ``` - conda activate research-agent + Alternatively, you can install the project with `pip` with the following commands. + ```bash + make lg-pip env_name=research_agent + conda activate research_agent ``` -5. Install this project with Poetry. We recommend using Anaconda to create a virtual environment for your project to ensure no global dependencies interfere with the project. +6. Manually install this project. + + Create a virtual environment either using Anaconda or any other Python environment manager. + ```bash + # create venv using Anaconda + conda create -n research_agent python=3.12 + conda activate research_agent + ``` + Install the example using Poetry ```bash poetry install ``` -6. Run `agentc` to make sure this project has installed correctly (note that your first run will take a couple of + Alternatively, install the example using `pip` + ```bash + pip install ../../../libs/agentc + pip install ../../../libs/agentc_langchain + ``` + +7. Run `agentc` to make sure this project has installed correctly (note that your first run will take a couple of seconds as certain packages need to be compiled, subsequent runs will be faster). ```bash @@ -72,7 +96,7 @@ This directory contains a starter project for building agents with Couchbase, La See: https://docs.couchbase.com or https://couchbaselabs.github.io/agent-catalog/index.html# for more information. ``` -7. Make sure your Git repo is clean, and run `agentc index` to index your tools and prompts. +8. Make sure your Git repo is clean, and run `agentc index` to index your tools and prompts. Note that `tools` and `prompts` are _relative paths_ to the `tools` and `prompts` folder. ```bash @@ -85,7 +109,7 @@ This directory contains a starter project for building agents with Couchbase, La _Hint: if you've made changes but want to keep the same commit ID for the later "publish" step, use `git add $MY_FILES` followed by `git commit --amend`!_ -8. Start up a Couchbase instance. +9. Start up a Couchbase instance. 1. For those interested in using a local Couchbase instance, see [here](https://docs.couchbase.com/server/current/install/install-intro.html). @@ -110,14 +134,14 @@ This directory contains a starter project for building agents with Couchbase, La You'll need to navigate to your instance's UI (for local instances, this is on http://localhost:8091) to import this sample bucket. -9. Create a `.env` file using `.env.example` as a reference and tweak it according to your environment. +10. Create a `.env` file using `.env.example` as a reference and tweak it according to your environment. ```bash cp .env.example .env vi .env ``` -10. Publish your local agent catalog to your Couchbase instance with `agentc publish`. +11. Publish your local agent catalog to your Couchbase instance with `agentc publish`. Your Couchbase instance details in the `.env` file will be used for authentication. Again, this specific starter agent uses the `travel-sample` bucket. @@ -125,7 +149,7 @@ This directory contains a starter project for building agents with Couchbase, La agentc publish tool prompt --bucket travel-sample ``` -11. Run your agent! +12. Run your agent! To start jupyter server, run the following command: From c660cc26eebc73fc9d504533859f068ed4e583b1 Mon Sep 17 00:00:00 2001 From: Thejas N U <77475353+ThejasNU@users.noreply.github.com> Date: Thu, 30 Jan 2025 22:11:01 +0530 Subject: [PATCH 2/2] ThejasNU/init command (#42) * add init command * move local init * refactor command * add db init * add exceptions in other cmds * fix cli tests * add init local test * update README files * update docs --- README.md | 1 + docs/source/guide.rst | 22 +++- docs/source/install.rst | 1 + libs/agentc/agentc/auditor.py | 8 +- libs/agentc_cli/agentc_cli/cmds/__init__.py | 2 + libs/agentc_cli/agentc_cli/cmds/index.py | 7 +- libs/agentc_cli/agentc_cli/cmds/init.py | 45 +++++++ libs/agentc_cli/agentc_cli/cmds/publish.py | 45 ++----- libs/agentc_cli/agentc_cli/cmds/util.py | 116 ++++++++++++++++-- libs/agentc_cli/agentc_cli/main.py | 77 ++++++++++++ libs/agentc_cli/tests/test_click.py | 28 +++++ .../agentc_core/activity/auditor/db.py | 19 ++- libs/agentc_core/agentc_core/util/ddl.py | 26 ++++ libs/agentc_testing/agentc_testing/repo.py | 6 + templates/agents/with_controlflow/README.md | 51 +++++--- templates/agents/with_langgraph/README.md | 34 +++-- 16 files changed, 401 insertions(+), 87 deletions(-) create mode 100644 libs/agentc_cli/agentc_cli/cmds/init.py diff --git a/README.md b/README.md index 58a13d4d..4693854f 100644 --- a/README.md +++ b/README.md @@ -152,6 +152,7 @@ Commands: execute Search and execute a specific tool. find Find items from the catalog based on a natural language QUERY string or by name. index Walk the source directory trees (SOURCE_DIRS) to index source files into the local catalog. + init Initialize the necessary files/collections for local/database catalog. ls List all indexed tools and/or prompts in the catalog. publish Upload the local catalog and/or logs to a Couchbase instance. status Show the status of the local catalog. diff --git a/docs/source/guide.rst b/docs/source/guide.rst index 06c48813..c07421de 100644 --- a/docs/source/guide.rst +++ b/docs/source/guide.rst @@ -73,7 +73,11 @@ Both tool builders and prompt builders (i.e., agent builders) will follow this w Agent Catalog currently integrates with Git (using the working Git SHA) to version each item. **You must be in a Git repository to use Agent Catalog.** -4. **Indexing**: Use the command below to index your tools/prompts: +4. **Indexing**: Use the command below to first initialize local catalog and later index your tools/prompts: + + .. code-block:: bash + + agentc init local catalog .. code-block:: bash @@ -112,16 +116,24 @@ Both tool builders and prompt builders (i.e., agent builders) will follow this w export AGENT_CATALOG_USERNAME=Administrator export AGENT_CATALOG_PASSWORD=password - 3. Use the command to publish your items to your Couchbase instance. + 3. Use the command to initialize database catalog. .. code-block:: bash - agentc publish [[tool|prompt]] --bucket [BUCKET_NAME] + agentc init db catalog --bucket [BUCKET_NAME] This will create a new scope in the specified bucket called ``agent_catalog``, which will contain all of your - items. + items. It also creates necessary collections and indexes for the catalog. + + 4. Use the command to publish your items to your Couchbase instance. + + .. code-block:: bash + + agentc publish [[tool|prompt]] --bucket [BUCKET_NAME] + + This will push all local catalog items to the scope ``agent_catalog`` in the specified bucket. - 4. Note that Agent Catalog isn't meant for the "publish once and forget" case. + 5. Note that Agent Catalog isn't meant for the "publish once and forget" case. You are encouraged to run the :command:`agentc publish` command as often as you like to keep your items up-to-date. diff --git a/docs/source/install.rst b/docs/source/install.rst index 21cc587a..33ec0482 100644 --- a/docs/source/install.rst +++ b/docs/source/install.rst @@ -138,6 +138,7 @@ some libraries like numpy need to be built, subsequent runs will be faster). execute Search and execute a specific tool. find Find items from the catalog based on a natural language QUERY string or by name. index Walk the source directory trees (SOURCE_DIRS) to index source files into the local catalog. + init Initialize the necessary files/collections for local/database catalog. ls List all indexed tools and/or prompts in the catalog. publish Upload the local catalog and/or logs to a Couchbase instance. status Show the status of the local catalog. diff --git a/libs/agentc/agentc/auditor.py b/libs/agentc/agentc/auditor.py index ac72e16a..092abdff 100644 --- a/libs/agentc/agentc/auditor.py +++ b/libs/agentc/agentc/auditor.py @@ -113,7 +113,13 @@ def _find_local_log(self) -> typing.Self: # We have reached the root. We cannot find the catalog folder. return self working_path = working_path.parent - (working_path / DEFAULT_ACTIVITY_FOLDER).mkdir(exist_ok=True) + + auditor_directory_path = working_path / DEFAULT_ACTIVITY_FOLDER + if not auditor_directory_path.exists(): + raise ValueError( + f"Could not find the {DEFAULT_ACTIVITY_FOLDER} folder!\nPlease use 'agentc init' command first.\nExecute 'agentc init --help' for more information." + ) + self.auditor_output = working_path / DEFAULT_ACTIVITY_FOLDER / DEFAULT_LLM_ACTIVITY_NAME return self diff --git a/libs/agentc_cli/agentc_cli/cmds/__init__.py b/libs/agentc_cli/agentc_cli/cmds/__init__.py index 58602e9d..8be7792b 100644 --- a/libs/agentc_cli/agentc_cli/cmds/__init__.py +++ b/libs/agentc_cli/agentc_cli/cmds/__init__.py @@ -4,6 +4,7 @@ from .execute import cmd_execute from .find import cmd_find from .index import cmd_index +from .init import cmd_init from .ls import cmd_ls from .publish import cmd_publish from .status import cmd_status @@ -22,4 +23,5 @@ "cmd_version", "cmd_web", "cmd_ls", + "cmd_init", ] diff --git a/libs/agentc_cli/agentc_cli/cmds/index.py b/libs/agentc_cli/agentc_cli/cmds/index.py index efea3d85..8463cd3b 100644 --- a/libs/agentc_cli/agentc_cli/cmds/index.py +++ b/libs/agentc_cli/agentc_cli/cmds/index.py @@ -10,7 +10,6 @@ from ..models.context import Context from .util import DASHES from .util import KIND_COLORS -from .util import init_local from agentc_core.catalog import __version__ as CATALOG_SCHEMA_VERSION from agentc_core.catalog.index import MetaVersion from agentc_core.catalog.index import index_catalog @@ -43,7 +42,11 @@ def cmd_index( # and on how to add .agent-activity/ to the .gitignore file? Or, should # we instead preemptively generate a .agent-activity/.gitiginore # file during init_local()? - init_local(ctx) + + if not os.path.exists(ctx.catalog): + raise RuntimeError( + "Local catalog directory does not exist!\nPlease use 'agentc init' command first.\nExecute 'agentc init --help' for more information." + ) # TODO: One day, maybe allow users to choose a different branch instead of assuming # the HEAD branch, as users currently would have to 'git checkout BRANCH_THEY_WANT' diff --git a/libs/agentc_cli/agentc_cli/cmds/init.py b/libs/agentc_cli/agentc_cli/cmds/init.py new file mode 100644 index 00000000..5c1188df --- /dev/null +++ b/libs/agentc_cli/agentc_cli/cmds/init.py @@ -0,0 +1,45 @@ +import typing + +from ..models import Context +from .util import init_db_auditor +from .util import init_db_catalog +from .util import init_local_activity +from .util import init_local_catalog +from agentc_core.util.models import CouchbaseConnect +from agentc_core.util.models import Keyspace +from agentc_core.util.publish import get_connection + +func_mappings = {"local": {"catalog": init_local_catalog, "auditor": init_local_activity}} + + +def cmd_init( + ctx: Context, + catalog_type: typing.List[typing.Literal["catalog", "auditor"]], + type_metadata: typing.List[typing.Literal["catalog", "auditor"]], + connection_details_env: typing.Optional[CouchbaseConnect] = None, + keyspace_details: typing.Optional[Keyspace] = None, +): + if ctx is None: + ctx = Context() + initialize_local = "local" in catalog_type + initialize_db = "db" in catalog_type + initialize_catalog = "catalog" in type_metadata + initialize_auditor = "auditor" in type_metadata + + if initialize_local: + if initialize_catalog: + init_local_catalog(ctx) + if initialize_auditor: + init_local_activity(ctx) + + if initialize_db: + # Get bucket ref + err, cluster = get_connection(conn=connection_details_env) + if err: + raise ValueError(f"Unable to connect to Couchbase!\n{err}") + + if initialize_catalog: + init_db_catalog(ctx, cluster, keyspace_details, connection_details_env) + + if initialize_auditor: + init_db_auditor(ctx, cluster, keyspace_details) diff --git a/libs/agentc_cli/agentc_cli/cmds/publish.py b/libs/agentc_cli/agentc_cli/cmds/publish.py index 4b19043e..ae6da537 100644 --- a/libs/agentc_cli/agentc_cli/cmds/publish.py +++ b/libs/agentc_cli/agentc_cli/cmds/publish.py @@ -17,12 +17,10 @@ from agentc_core.defaults import DEFAULT_CATALOG_SCOPE from agentc_core.defaults import DEFAULT_LLM_ACTIVITY_NAME from agentc_core.defaults import DEFAULT_META_COLLECTION_NAME -from agentc_core.util.ddl import create_gsi_indexes -from agentc_core.util.ddl import create_vector_index +from agentc_core.util.ddl import check_if_scope_collection_exist from agentc_core.util.models import CouchbaseConnect from agentc_core.util.models import CustomPublishEncoder from agentc_core.util.models import Keyspace -from agentc_core.util.publish import create_scope_and_collection from agentc_core.util.publish import get_connection from couchbase.exceptions import CouchbaseException from pydantic import ValidationError @@ -95,14 +93,12 @@ def cmd_publish( logger.debug(len(log_messages), "logs found..\n") - bucket_manager = cb.collections() - log_col = DEFAULT_AUDIT_COLLECTION log_scope = DEFAULT_AUDIT_SCOPE - try: - (msg, err) = create_scope_and_collection(bucket_manager, scope=log_scope, collection=log_col) - except: - raise ValueError(msg) from err + + bucket_manager = cb.collections() + + check_if_scope_collection_exist(bucket_manager, log_scope, log_col, True) # get collection ref cb_coll = cb.scope(log_scope).collection(log_col) @@ -149,9 +145,8 @@ def cmd_publish( # ---------------------------------------------------------------------------------------- # meta_col = k + DEFAULT_META_COLLECTION_NAME meta_scope = scope - (msg, err) = create_scope_and_collection(bucket_manager, scope=meta_scope, collection=meta_col) - if err is not None: - raise ValueError(msg) + + check_if_scope_collection_exist(bucket_manager, meta_scope, meta_col, True) # get collection ref cb_coll = cb.scope(meta_scope).collection(meta_col) @@ -178,9 +173,8 @@ def cmd_publish( # ---------------------------------------------------------------------------------------- # catalog_col = k + DEFAULT_CATALOG_COLLECTION_NAME catalog_scope = scope - (msg, err) = create_scope_and_collection(bucket_manager, scope=catalog_scope, collection=catalog_col) - if err is not None: - raise ValueError(msg) + + check_if_scope_collection_exist(bucket_manager, catalog_scope, catalog_col, True) # get collection ref cb_coll = cb.scope(catalog_scope).collection(catalog_col) @@ -206,24 +200,3 @@ def cmd_publish( click.secho(f"Couldn't insert catalog items!\n{e.message}", fg="red") return e click.secho(f"{k.capitalize()} catalog items successfully uploaded to Couchbase!\n", fg="green") - - # ---------------------------------------------------------------------------------------- # - # GSI and Vector Indexes # - # ---------------------------------------------------------------------------------------- # - click.secho(f"Now building the GSI indexes for the {k} catalog.", fg="yellow") - s, err = create_gsi_indexes(bucket, cluster, k, True) - if not s: - raise ValueError(f"GSI indexes could not be created \n{err}") - else: - click.secho(f"All GSI indexes for the {k} catalog have been successfully created!\n", fg="green") - logger.debug("Indexes created successfully!") - - click.secho(f"Now building the vector index for the {k} catalog.", fg="yellow") - dims = len(catalog_desc.items[0].embedding) - _, err = create_vector_index(bucket, k, connection_details_env, dims) - if err is not None: - raise ValueError(f"Vector index could not be created \n{err}") - else: - click.secho(f"Vector index for the {k} catalog has been successfully created!", fg="green") - logger.debug("Vector index created successfully!") - click.secho(DASHES, fg=KIND_COLORS[k]) diff --git a/libs/agentc_cli/agentc_cli/cmds/util.py b/libs/agentc_cli/agentc_cli/cmds/util.py index 94058695..dde9564a 100644 --- a/libs/agentc_cli/agentc_cli/cmds/util.py +++ b/libs/agentc_cli/agentc_cli/cmds/util.py @@ -10,20 +10,34 @@ import typing from ..models.context import Context +from agentc_core.analytics.create import create_analytics_udfs from agentc_core.catalog import CatalogChain from agentc_core.catalog import CatalogDB from agentc_core.catalog import CatalogMem from agentc_core.catalog import __version__ as CATALOG_SCHEMA_VERSION +from agentc_core.catalog.descriptor import CatalogDescriptor from agentc_core.catalog.index import MetaVersion from agentc_core.catalog.index import index_catalog from agentc_core.catalog.version import lib_version +from agentc_core.defaults import DEFAULT_AUDIT_COLLECTION +from agentc_core.defaults import DEFAULT_AUDIT_SCOPE +from agentc_core.defaults import DEFAULT_CATALOG_COLLECTION_NAME from agentc_core.defaults import DEFAULT_CATALOG_NAME from agentc_core.defaults import DEFAULT_MAX_ERRS +from agentc_core.defaults import DEFAULT_META_COLLECTION_NAME from agentc_core.defaults import DEFAULT_SCAN_DIRECTORY_OPTS from agentc_core.learned.embedding import EmbeddingModel +from agentc_core.util.ddl import create_gsi_indexes +from agentc_core.util.ddl import create_vector_index +from agentc_core.util.models import CouchbaseConnect +from agentc_core.util.models import Keyspace +from agentc_core.util.publish import create_scope_and_collection from agentc_core.version import VersionDescriptor +from couchbase.cluster import Cluster +from couchbase.exceptions import CouchbaseException # The following are used for colorizing output. +CATALOG_KINDS = ["prompt", "tool"] LEVEL_COLORS = {"good": "green", "warn": "yellow", "error": "red"} KIND_COLORS = {"tool": "bright_magenta", "prompt": "blue", "log": "cyan"} try: @@ -35,14 +49,6 @@ logger = logging.getLogger(__name__) -def init_local(ctx: Context): - # Init directories. - os.makedirs(ctx.catalog, exist_ok=True) - os.makedirs(ctx.activity, exist_ok=True) - - # (Note: the version checking logic has been moved into index). - - def load_repository(top_dir: pathlib.Path = None): # The repo is the user's application's repo and is NOT the repo # of agentc_core. The agentc CLI / library should be run in @@ -173,3 +179,97 @@ def logging_printer(content: str, *args, **kwargs): # the pattern similar to repo_load()'s searching for a .git/ directory # and scan up the parent directories to find the first .agent-catalog/ # subdirectory? + + +def init_local_catalog(ctx: Context): + # Init directories. + os.makedirs(ctx.catalog, exist_ok=True) + + +def init_local_activity(ctx: Context): + # Init directories. + os.makedirs(ctx.activity, exist_ok=True) + + +def init_db_catalog( + ctx: Context, cluster: Cluster, keyspace_details: Keyspace, connection_details_env: CouchbaseConnect +): + # Get the bucket manager + cb = cluster.bucket(keyspace_details.bucket) + bucket_manager = cb.collections() + + # ---------------------------------------------------------------------------------------- # + # SCOPES and COLLECTIONS # + # ---------------------------------------------------------------------------------------- # + for kind in CATALOG_KINDS: + # Create the metadata collection if it does not exist + click.secho(f"Now creating scope and collections for the {kind} catalog.", fg="yellow") + meta_col = kind + DEFAULT_META_COLLECTION_NAME + (msg, err) = create_scope_and_collection(bucket_manager, scope=keyspace_details.scope, collection=meta_col) + if err is not None: + raise ValueError(msg) + else: + click.secho(f"Metadata collection for the {kind} catalog has been successfully created!\n", fg="green") + + # Create the catalog collection if it does not exist + click.secho(f"Now creating the catalog collection for the {kind} catalog.", fg="yellow") + catalog_col = kind + DEFAULT_CATALOG_COLLECTION_NAME + (msg, err) = create_scope_and_collection(bucket_manager, scope=keyspace_details.scope, collection=catalog_col) + if err is not None: + raise ValueError(msg) + else: + click.secho(f"Catalog collection for the {kind} catalog has been successfully created!\n", fg="green") + + # ---------------------------------------------------------------------------------------- # + # GSI and Vector Indexes # + # ---------------------------------------------------------------------------------------- # + for kind in CATALOG_KINDS: + click.secho(f"Now building the GSI indexes for the {kind} catalog.", fg="yellow") + completion_status, err = create_gsi_indexes(keyspace_details.bucket, cluster, kind, True) + if not completion_status: + raise ValueError(f"GSI indexes could not be created \n{err}") + else: + click.secho(f"All GSI indexes for the {kind} catalog have been successfully created!\n", fg="green") + + click.secho(f"Now building the vector index for the {kind} catalog.", fg="yellow") + catalog_path = pathlib.Path(ctx.catalog) / (kind + DEFAULT_CATALOG_NAME) + + try: + with catalog_path.open("r") as fp: + catalog_desc = CatalogDescriptor.model_validate_json(fp.read()) + except FileNotFoundError: + click.secho( + f"Unable to create vector index for {kind} catalog because dimension of vector can't be determined!\nInitialize the local catalog first, index items and try initializing the db catalog again.\n", + fg="red", + ) + continue + + dims = len(catalog_desc.items[0].embedding) + _, err = create_vector_index(keyspace_details.bucket, kind, connection_details_env, dims) + if err is not None: + raise ValueError(f"Vector index could not be created \n{err}") + else: + click.secho(f"Vector index for the {kind} catalog has been successfully created!\n", fg="green") + + +def init_db_auditor(ctx: Context, cluster: Cluster, keyspace_details: Keyspace): + # Get the bucket manager + cb = cluster.bucket(keyspace_details.bucket) + bucket_manager = cb.collections() + + log_col = DEFAULT_AUDIT_COLLECTION + log_scope = DEFAULT_AUDIT_SCOPE + click.secho("Now creating scope and collections for the auditor.", fg="yellow") + (msg, err) = create_scope_and_collection(bucket_manager, scope=log_scope, collection=log_col) + if err is not None: + raise ValueError(msg) + else: + click.secho("Scope and collection for the auditor have been successfully created!\n", fg="green") + + click.secho("Now creating the analytics UDFs for the auditor.", fg="yellow") + try: + create_analytics_udfs(cluster, keyspace_details.bucket) + click.secho("All analytics UDFs for the auditor have been successfully created!\n", fg="green") + except CouchbaseException as e: + click.secho("Analytics views could not be created.", fg="red") + logger.warning("Analytics views could not be created: %s", e) diff --git a/libs/agentc_cli/agentc_cli/main.py b/libs/agentc_cli/agentc_cli/main.py index 54b8d084..c52ae0b8 100644 --- a/libs/agentc_cli/agentc_cli/main.py +++ b/libs/agentc_cli/agentc_cli/main.py @@ -13,6 +13,7 @@ from .cmds import cmd_execute from .cmds import cmd_find from .cmds import cmd_index +from .cmds import cmd_init from .cmds import cmd_ls from .cmds import cmd_publish from .cmds import cmd_status @@ -120,6 +121,82 @@ def click_main(ctx, catalog, activity, verbose, interactive): ctx.obj = Context(activity=activity, catalog=catalog, verbose=verbose, interactive=interactive) +@click_main.command() +@click.pass_context +@click.argument( + "catalog_type", + type=click.Choice(["local", "db"], case_sensitive=False), + nargs=-1, +) +@click.argument( + "type_metadata", + type=click.Choice(["catalog", "auditor", "all"], case_sensitive=False), +) +@click.option( + "--bucket", + default=None, + type=str, + help="Name of the Couchbase bucket to initialize in.", + show_default=False, +) +def init(ctx, catalog_type, type_metadata, bucket): + """Initialize the necessary files/collections for local/database catalog.""" + ctx_obj: Context = ctx.obj + + if not catalog_type: + catalog_type = ["local", "db"] + + type_metadata = ["catalog", "auditor"] if type_metadata == "all" else [type_metadata] + + connection_details_env = None + keyspace_details = None + + if "db" in catalog_type: + # Load all Couchbase connection related data from env + connection_details_env = CouchbaseConnect( + connection_url=os.getenv("AGENT_CATALOG_CONN_STRING"), + username=os.getenv("AGENT_CATALOG_USERNAME"), + password=os.getenv("AGENT_CATALOG_PASSWORD"), + host=get_host_name(os.getenv("AGENT_CATALOG_CONN_STRING")), + certificate=os.getenv("AGENT_CATALOG_CONN_ROOT_CERTIFICATE"), + ) + + # Establish a connection + err, cluster = get_connection(conn=connection_details_env) + if err: + raise ValueError(f"Unable to connect to Couchbase!\n{err}") + + # Determine the bucket. + buckets = get_buckets(cluster=cluster) + cluster.close() + if bucket is None and ctx_obj.interactive: + bucket = click.prompt("Bucket", type=click.Choice(buckets), show_choices=True) + + elif bucket is not None and bucket not in buckets: + raise ValueError( + "Bucket does not exist!\n" + f"Available buckets from cluster are: {','.join(buckets)}\n" + f"Run agentc publish --help for more information." + ) + + elif bucket is None and not ctx_obj.interactive: + raise ValueError( + "Bucket must be specified to publish to the database catalog." + "Add --bucket BUCKET_NAME to your command or run agentc clean in interactive mode." + ) + + # Get keyspace and connection details + keyspace_details = Keyspace(bucket=bucket, scope=DEFAULT_CATALOG_SCOPE) + + cmd_init( + ctx=ctx_obj, + catalog_type=catalog_type, + type_metadata=type_metadata, + connection_details_env=connection_details_env, + keyspace_details=keyspace_details, + ) + + @click_main.command() @click.option( "-o", diff --git a/libs/agentc_cli/tests/test_click.py b/libs/agentc_cli/tests/test_click.py index 6d59f24c..3a9705c1 100644 --- a/libs/agentc_cli/tests/test_click.py +++ b/libs/agentc_cli/tests/test_click.py @@ -478,3 +478,31 @@ def test_ls_local_both_tools_prompts(tmp_path): assert "TOOL" in output and len(re.findall(r"\b1\.\s.+", output)) == 1 output = runner.invoke(click_main, ["ls", "-local"]).stdout assert "PROMPT" in output and "TOOL" in output and len(re.findall(r"\b1\.\s.+", output)) == 2 + + +@pytest.mark.smoke +def test_init_local(tmp_path): + runner = click.testing.CliRunner() + with runner.isolated_filesystem(temp_dir=tmp_path): + files_present = os.listdir() + assert ".agent-catalog" not in files_present and ".agent-activity" not in files_present + + runner.invoke(click_main, ["init", "local", "catalog"]) + files_present = os.listdir() + assert ".agent-catalog" in files_present and ".agent-activity" not in files_present + + runner.invoke(click_main, ["init", "local", "auditor"]) + files_present = os.listdir() + assert ".agent-catalog" in files_present and ".agent-activity" in files_present + + +@pytest.mark.smoke +def test_init_local_all(tmp_path): + runner = click.testing.CliRunner() + with runner.isolated_filesystem(temp_dir=tmp_path): + files_present = os.listdir() + assert ".agent-catalog" not in files_present and ".agent-activity" not in files_present + + runner.invoke(click_main, ["init", "local", "all"]) + files_present = os.listdir() + assert ".agent-catalog" in files_present and ".agent-activity" in files_present diff --git a/libs/agentc_core/agentc_core/activity/auditor/db.py b/libs/agentc_core/agentc_core/activity/auditor/db.py index 6886a7b8..7c1307d0 100644 --- a/libs/agentc_core/agentc_core/activity/auditor/db.py +++ b/libs/agentc_core/agentc_core/activity/auditor/db.py @@ -7,14 +7,13 @@ import logging from ...analytics import Log -from ...analytics.create import create_analytics_udfs from ...defaults import DEFAULT_AUDIT_COLLECTION from ...defaults import DEFAULT_AUDIT_SCOPE +from ...util.ddl import check_if_scope_collection_exist from ...version import VersionDescriptor from .base import BaseAuditor from agentc_core.util.connection import get_host_name from agentc_core.util.models import CouchbaseConnect -from agentc_core.util.publish import create_scope_and_collection logger = logging.getLogger(__name__) @@ -59,16 +58,14 @@ def __init__( # Get the bucket manager bucket_manager = cb.collections() - msg, err = create_scope_and_collection(bucket_manager, DEFAULT_AUDIT_SCOPE, DEFAULT_AUDIT_COLLECTION) - if err is not None: - logger.error(err) - raise err - try: - create_analytics_udfs(cluster, bucket) - except couchbase.exceptions.CouchbaseException as e: - logger.warning("Analytics views could not be created: %s", e) - pass + scope_collection_exist = check_if_scope_collection_exist( + bucket_manager, DEFAULT_AUDIT_SCOPE, DEFAULT_AUDIT_COLLECTION, False + ) + if not scope_collection_exist: + raise ValueError( + f"Scope {DEFAULT_AUDIT_SCOPE} and collection {DEFAULT_AUDIT_COLLECTION} does not exist in bucket {bucket}.\nPlease use 'agentc init' command first to create keyspace.\nExecute 'agentc init --help' for more information." + ) # get collection ref cb_coll = cb.scope(DEFAULT_AUDIT_SCOPE).collection(DEFAULT_AUDIT_COLLECTION) diff --git a/libs/agentc_core/agentc_core/util/ddl.py b/libs/agentc_core/agentc_core/util/ddl.py index 74689f04..74ba235f 100644 --- a/libs/agentc_core/agentc_core/util/ddl.py +++ b/libs/agentc_core/agentc_core/util/ddl.py @@ -12,6 +12,7 @@ from agentc_core.defaults import DEFAULT_HTTP_FTS_PORT_NUMBER from agentc_core.defaults import DEFAULT_HTTPS_CLUSTER_ADMIN_PORT_NUMBER from agentc_core.defaults import DEFAULT_HTTPS_FTS_PORT_NUMBER +from couchbase.bucket import CollectionManager logger = logging.getLogger(__name__) @@ -384,3 +385,28 @@ def create_gsi_indexes(bucket, cluster, kind, print_progress): with contextlib.suppress(StopIteration): next(progress_bar_it) return completion_status, all_errs + + +def check_if_scope_collection_exist( + bucket_manager: CollectionManager, scope: str, collection: str, raise_exception: bool +) -> bool: + """Check if the given scope and collection exist in the bucket""" + scopes = bucket_manager.get_all_scopes() + scope_exists = any(s.name == scope for s in scopes) + if not scope_exists: + if raise_exception: + raise ValueError( + f"Scope {scope} not found in the given bucket!\nPlease use 'agentc init' command first.\nExecute 'agentc init --help' for more information." + ) + return False + + collections = [c.name for s in scopes if s.name == scope for c in s.collections] + collection_exists = collection in collections + if not collection_exists: + if raise_exception: + raise ValueError( + f"Collection {scope}.{collection} not found in the given bucket!\nPlease use 'agentc init' command first.\nExecute 'agentc init --help' for more information." + ) + return False + + return True diff --git a/libs/agentc_testing/agentc_testing/repo.py b/libs/agentc_testing/agentc_testing/repo.py index 42fbd761..c56d48c4 100644 --- a/libs/agentc_testing/agentc_testing/repo.py +++ b/libs/agentc_testing/agentc_testing/repo.py @@ -73,6 +73,9 @@ def initialize_repo( repo.index.commit("Initial commit") output = list() + # Initialize the local catalog. + click_runner.invoke(click_command, ["init", "local", "catalog"]) + # If we are not using the index command, we can return early... if repo_kind == ExampleRepoKind.EMPTY or repo_kind == ExampleRepoKind.NON_INDEXED_ALL_TRAVEL: return output @@ -90,6 +93,9 @@ def initialize_repo( ]: return output + # Initialize the DB catalog. + click_runner.invoke(click_command, ["init", "db", "catalog", "--bucket", "travel-sample"]) + # Call our publish command. Note that this assumes a container / CB instance is active! os.environ["AGENT_CATALOG_MAX_SOURCE_PARTITION"] = "1" os.environ["AGENT_CATALOG_INDEX_PARTITION"] = "1" diff --git a/templates/agents/with_controlflow/README.md b/templates/agents/with_controlflow/README.md index 9d1e9c93..707ee738 100644 --- a/templates/agents/with_controlflow/README.md +++ b/templates/agents/with_controlflow/README.md @@ -87,19 +87,29 @@ This directory contains a starter project for building agents with Couchbase, Co Commands: add Interactively create a new tool or prompt and save it to the filesystem (output). - clean Delete all agent catalog related files / collections. + clean Delete all or specific (catalog and/or activity) agent related files / collections. env Return all agentc related environment and configuration parameters as a JSON object. execute Search and execute a specific tool. find Find items from the catalog based on a natural language QUERY string or by name. index Walk the source directory trees (SOURCE_DIRS) to index source files into the local catalog. - publish Upload the local catalog to a Couchbase instance. + init Initialize the necessary files/collections for local/database catalog. + ls List all indexed tools and/or prompts in the catalog. + publish Upload the local catalog and/or logs to a Couchbase instance. status Show the status of the local catalog. version Show the current version of agentc. See: https://docs.couchbase.com or https://couchbaselabs.github.io/agent-catalog/index.html# for more information. ``` -8. Make sure your Git repo is clean, and run `agentc index` to index your tools and prompts. +8. Initialize the local catalog and auditor. + + ```bash + agentc init local all + ``` + + This command will create the necessary directories for the local catalog and auditor. + +9. Make sure your Git repo is clean, and run `agentc index` to index your tools and prompts. Note that `tools` and `prompts` are _relative paths_ to the `tools` and `prompts` folder. ```bash @@ -112,10 +122,11 @@ This directory contains a starter project for building agents with Couchbase, Co _Hint: if you've made changes but want to keep the same commit ID for the later "publish" step, use `git add $MY_FILES` followed by `git commit --amend`!_ -9. Start up a Couchbase instance. +10. Start up a Couchbase instance. 1. For those interested in using a local Couchbase instance, see - [here](https://docs.couchbase.com/server/current/install/install-intro.html). + [here](https://docs.couchbase.com/server/current/install/install-intro.html). + 2. For those interested in using Couchbase within a Docker container, run the command below: ```bash @@ -128,23 +139,31 @@ This directory contains a starter project for building agents with Couchbase, Co 3. For those interested in using Capella, see [here](https://cloud.couchbase.com/sign-up). - Once Couchbase instance is running, enable the following services on your Couchbase cluster: - - Data, Query, Index: For storing items and searching them. - - Search: For performing vector search on items. - - Analytics: For creating views on audit logs and to query the views for better insights on logs. + Once Couchbase instance is running, enable the following services on your Couchbase cluster: + - Data, Query, Index: For storing items and searching them. + - Search: For performing vector search on items. + - Analytics: For creating views on audit logs and to query the views for better insights on logs. - This specific agent also uses the `travel-sample` bucket. - You'll need to navigate to your instance's UI (for local instances, this is on http://localhost:8091) to install - this sample bucket. + This specific agent also uses the `travel-sample` bucket. + You'll need to navigate to your instance's UI (for local instances, this is on http://localhost:8091) to install + this sample bucket. -10. Create a `.env` file from the `.env.example` file and tweak this to your environment. +11. Create a `.env` file from the `.env.example` file and tweak this to your environment. ```bash cp .env.example .env vi .env ``` -11. Publish your local agent catalog to your Couchbase instance with `agentc publish`. +12. Initialize the database catalog and auditor. + + ```bash + agentc init db all --bucket travel-sample + ``` + + This command will create the necessary scopes, collections, secondary indexes, vector indexes and analytics views for the database catalog and auditor. + +13. Publish your local agent catalog to your Couchbase instance with `agentc publish`. Your Couchbase instance details in the `.env` file will be used for authentication. Again, this specific starter agent uses the `travel-sample` bucket. @@ -152,7 +171,7 @@ This directory contains a starter project for building agents with Couchbase, Co agentc publish tool prompt --bucket travel-sample ``` -12. Start a prefect server and run your agent! +14. Start a prefect server and run your agent! ```bash export PREFECT_API_URL=http://127.0.0.1:4200/api @@ -160,7 +179,7 @@ This directory contains a starter project for building agents with Couchbase, Co python agent.py ``` -13. Let's now talk with our agent! +15. Let's now talk with our agent! I initiated three conversations: two "positive" and one "negative". The first positive case is given below: diff --git a/templates/agents/with_langgraph/README.md b/templates/agents/with_langgraph/README.md index 94aa4db3..323c36b3 100644 --- a/templates/agents/with_langgraph/README.md +++ b/templates/agents/with_langgraph/README.md @@ -84,19 +84,29 @@ This directory contains a starter project for building agents with Couchbase, La Commands: add Interactively create a new tool or prompt and save it to the filesystem (output). - clean Delete all agent catalog related files / collections. + clean Delete all or specific (catalog and/or activity) agent related files / collections. env Return all agentc related environment and configuration parameters as a JSON object. execute Search and execute a specific tool. find Find items from the catalog based on a natural language QUERY string or by name. index Walk the source directory trees (SOURCE_DIRS) to index source files into the local catalog. - publish Upload the local catalog to a Couchbase instance. + init Initialize the necessary files/collections for local/database catalog. + ls List all indexed tools and/or prompts in the catalog. + publish Upload the local catalog and/or logs to a Couchbase instance. status Show the status of the local catalog. version Show the current version of agentc. See: https://docs.couchbase.com or https://couchbaselabs.github.io/agent-catalog/index.html# for more information. ``` -8. Make sure your Git repo is clean, and run `agentc index` to index your tools and prompts. +9. Initialize the local catalog and auditor. + + ```bash + agentc init local all + ``` + + This command will create the necessary directories for the local catalog and auditor. + +9. Make sure your Git repo is clean, and run `agentc index` to index your tools and prompts. Note that `tools` and `prompts` are _relative paths_ to the `tools` and `prompts` folder. ```bash @@ -109,7 +119,7 @@ This directory contains a starter project for building agents with Couchbase, La _Hint: if you've made changes but want to keep the same commit ID for the later "publish" step, use `git add $MY_FILES` followed by `git commit --amend`!_ -9. Start up a Couchbase instance. +10. Start up a Couchbase instance. 1. For those interested in using a local Couchbase instance, see [here](https://docs.couchbase.com/server/current/install/install-intro.html). @@ -125,7 +135,7 @@ This directory contains a starter project for building agents with Couchbase, La 3. For those interested in using Capella, see [here](https://cloud.couchbase.com/sign-up). - Once Couchbase instance is running, enable the following services on your Couchbase cluster: + Once Couchbase instance is running, enable the following services on your Couchbase cluster: - Data, Query, Index: For storing items and searching them. - Search: For performing vector search on items. - Analytics: For creating views on audit logs and to query the views for better insights on logs. @@ -134,14 +144,22 @@ This directory contains a starter project for building agents with Couchbase, La You'll need to navigate to your instance's UI (for local instances, this is on http://localhost:8091) to import this sample bucket. -10. Create a `.env` file using `.env.example` as a reference and tweak it according to your environment. +11. Create a `.env` file using `.env.example` as a reference and tweak it according to your environment. ```bash cp .env.example .env vi .env ``` -11. Publish your local agent catalog to your Couchbase instance with `agentc publish`. +12. Initialize the database catalog and auditor. + + ```bash + agentc init db all --bucket travel-sample + ``` + + This command will create the necessary scopes, collections, secondary indexes, vector indexes and analytics views for the database catalog and auditor. + +13. Publish your local agent catalog to your Couchbase instance with `agentc publish`. Your Couchbase instance details in the `.env` file will be used for authentication. Again, this specific starter agent uses the `travel-sample` bucket. @@ -149,7 +167,7 @@ This directory contains a starter project for building agents with Couchbase, La agentc publish tool prompt --bucket travel-sample ``` -12. Run your agent! +14. Run your agent! To start jupyter server, run the following command: