Update feature branch with master (#64)

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"

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!
-   <br/>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.

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).

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 <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.
 
    .. 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 <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.
+
+   .. code-block:: bash
+
+       make dev-local-poetry env_name=agentcenv
+       conda activate agentcenv
 
 Verifying Your Installation
 ---------------------------

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,23 +439,32 @@ 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,
             click_runner=runner,
             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
-        ############################################################################################################

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)
             )

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

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

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

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;

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,

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