feat(agents-api): Add support for reading setup args from metadata and Upgrade to python 3.12 (#525)

Signed-off-by: Diwank Singh Tomer <[email protected]>

<!-- ELLIPSIS_HIDDEN -->


----

> [!IMPORTANT]
> Upgrade to Python 3.12 and add support for reading setup arguments
from metadata in `agents-api`.
> 
>   - **Python Version Upgrade**:
> - Upgrade Python to 3.12 in `.tool-versions`, `Dockerfile`,
`Dockerfile.worker`, `pyproject.toml`, and `pytype.toml`.
>   - **Setup Arguments from Metadata**:
> - `execute_integration()` in `execute_integration.py` now reads setup
arguments from metadata.
> - `get_tool_args_from_metadata()` in `get_tool_args_from_metadata.py`
updated to handle `arg_type` for "args" and "setup".
>   - **CI and Documentation**:
>     - Delete `generate-docs.yml` workflow.
> - Update `lint-and-format.yml` to focus on `agents-api` and use Python
3.12.
>     - Update `pytype` version in `pyproject.toml`.
> - Change `x-tool-parameters` to `x-integration-args` in
`julep-concepts.md`.
>     - Adjust backup schedule in `docker-compose.yml` from 1h to 3h.
> 
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=julep-ai%2Fjulep&utm_source=github&utm_medium=referral)<sup>
for b1c0615. It will automatically
update as commits are pushed.</sup>


<!-- ELLIPSIS_HIDDEN -->

---------

Signed-off-by: Diwank Singh Tomer <[email protected]>

Author: creatorrr

Diff for: .github/workflows/generate-docs.yml

@@ -1,4 +1,4 @@
-name: Lint and typecheck APIs and SDKs
+name: Lint and typecheck agents-api
 run-name: ${{ github.actor }} is linting and typechecking the code
 
 # TODO: Fix CI github actions
@@ -10,99 +10,61 @@ jobs:
   Lint-And-Format:
     runs-on: ubuntu-latest
 
-    strategy:
-      matrix:
-        directory: [agents-api, sdks/python]
-
     steps:
       - uses: actions/checkout@v4
 
       - uses: actions/setup-python@v5
         with:
-          python-version: "3.10"
+          python-version: "3.12"
 
       - name: Install and configure Poetry
         uses: snok/install-poetry@v1
 
       - name: Configure Poetry to use .venv
         run: |
-          cd ${{ matrix.directory }}
+          cd agents-api
           poetry config virtualenvs.in-project true
 
       - name: Cache Poetry virtualenv
         uses: actions/cache@v4
         with:
-          path: ${{ matrix.directory }}/.venv
-          key: ${{ runner.os }}-${{ matrix.directory }}-poetry-${{ hashFiles(format('{0}/poetry.lock', matrix.directory)) }}
+          path: agents-api/.venv
+          key: ${{ runner.os }}-agents-api-poetry-${{ hashFiles('agents-api/poetry.lock') }}
           restore-keys: |
-            ${{ runner.os }}-${{ matrix.directory }}-poetry-
+            ${{ runner.os }}-agents-api-poetry-
 
       - name: Cache pytype
         uses: actions/cache@v4
         with:
-          path: ${{ matrix.directory }}/.pytype
-          key: ${{ runner.os }}-${{ matrix.directory }}-pytype-${{ hashFiles(format('{0}/**/*.py', matrix.directory)) }}
+          path: agents-api/.pytype
+          key: ${{ runner.os }}-agents-api-pytype-${{ hashFiles('agents-api/**/*.py') }}
           restore-keys: |
-            ${{ runner.os }}-${{ matrix.directory }}-pytype-
+            ${{ runner.os }}-agents-api-pytype-
 
       - name: Install dependencies
         run: |
-          cd ${{ matrix.directory }}
+          cd agents-api
           poetry install
 
-      - name: Lint and format
-        run: |
-          cd ${{ matrix.directory }}
-          poetry run poe format
-          poetry run poe lint
-
       - name: Typecheck
         run: |
-          cd ${{ matrix.directory }}
+          cd agents-api
           poetry run poe typecheck
 
-      - uses: stefanzweifel/git-auto-commit-action@v4
-        with:
-          commit_message: "refactor: Lint ${{ matrix.directory }} (CI)"
-          branch: ${{ github.head_ref }}
-
-  Lint-And-Format-TS-SDK:
-    runs-on: ubuntu-latest
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Use Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: "20.x"
-
-      - name: Cache npm dependencies
-        uses: actions/cache@v4
-        with:
-          path: sdks/ts/node_modules
-          key: ${{ runner.os }}-sdks-ts-npm-${{ hashFiles('sdks/ts/package-lock.json') }}
-          restore-keys: |
-            ${{ runner.os }}-sdks-ts-npm-
-
-      - name: Install npm dependencies
-        run: |
-          cd sdks/ts
-          npm ci
-
-      - name: Lint and format TypeScript SDK
+      - name: Lint and format
         run: |
-          cd sdks/ts
-          npm run format
+          cd agents-api
+          poetry run poe format
+          poetry run poe lint
 
-      - name: Build TypeScript SDK
+      - name: Run tests
         run: |
-          cd sdks/ts
-          npm run build
+          cd agents-api
+          poetry run poe test
 
       - uses: stefanzweifel/git-auto-commit-action@v4
         with:
-          commit_message: "refactor: Lint sdks/ts (CI)"
+          commit_message: "refactor: Lint agents-api (CI)"
           branch: ${{ github.head_ref }}
 
 concurrency:

Diff for: .github/workflows/lint-and-format.yml

@@ -1 +1 @@
-python 3.11.9
+python 3.12.5

Diff for: agents-api/.tool-versions

@@ -1,4 +1,4 @@
-FROM python:3.11-slim
+FROM python:3.12-slim
 
 ENV PYTHONUNBUFFERED True
 ENV POETRY_CACHE_DIR=/tmp/poetry_cache

Diff for: agents-api/Dockerfile

@@ -1,4 +1,4 @@
-FROM python:3.11-slim
+FROM python:3.12-slim
 
 ENV PYTHONUNBUFFERED True
 ENV POETRY_CACHE_DIR=/tmp/poetry_cache

Diff for: agents-api/Dockerfile.worker

@@ -16,26 +16,33 @@ async def execute_integration(
     tool_name: str,
     integration: IntegrationDef,
     arguments: dict[str, Any],
+    setup: dict[str, Any] = {},
 ) -> Any:
     developer_id = context.execution_input.developer_id
     agent_id = context.execution_input.agent.id
     task_id = context.execution_input.task.id
 
     merged_tool_args = get_tool_args_from_metadata(
-        developer_id=developer_id, agent_id=agent_id, task_id=task_id
+        developer_id=developer_id, agent_id=agent_id, task_id=task_id, arg_type="args"
+    )
+
+    merged_tool_setup = get_tool_args_from_metadata(
+        developer_id=developer_id, agent_id=agent_id, task_id=task_id, arg_type="setup"
     )
 
     arguments = (
         merged_tool_args.get(tool_name, {}) | (integration.arguments or {}) | arguments
     )
 
+    setup = merged_tool_setup.get(tool_name, {}) | (integration.setup or {}) | setup
+
     try:
         if integration.provider == "dummy":
             return arguments
 
         return await integrations.run_integration_service(
             provider=integration.provider,
-            setup=integration.setup,
+            setup=setup,
             method=integration.method,
             arguments=arguments,
         )

Diff for: agents-api/agents_api/activities/execute_integration.py

@@ -1,3 +1,4 @@
+from typing import Literal
 from uuid import UUID
 
 from beartype import beartype
@@ -20,29 +21,31 @@ def tool_args_for_task(
     developer_id: UUID,
     agent_id: UUID,
     task_id: UUID,
+    tool_type: Literal["integration", "api_call"] = "integration",
+    arg_type: Literal["args", "setup"] = "args",
 ) -> tuple[list[str], dict]:
     agent_id = str(agent_id)
     task_id = str(task_id)
 
-    get_query = """
+    get_query = f"""
         input[agent_id, task_id] <- [[to_uuid($agent_id), to_uuid($task_id)]]
 
-        ?[args] :=
+        ?[values] :=
             input[agent_id, task_id],
-            *tasks {
+            *tasks {{
                 task_id,
                 metadata: task_metadata,
-            },
-            *agents {
+            }},
+            *agents {{
                 agent_id,
                 metadata: agent_metadata,
-            },
-            task_args = get(task_metadata, "x-tool-args", {}),
-            agent_args = get(agent_metadata, "x-tool-args", {}),
+            }},
+            task_{arg_type} = get(task_metadata, "x-{tool_type}-{arg_type}", {{}}),
+            agent_{arg_type} = get(agent_metadata, "x-{tool_type}-{arg_type}", {{}}),
 
             # Right values overwrite left values
             # See: https://docs.cozodb.org/en/latest/functions.html#Func.Vector.concat
-            args = concat(agent_args, task_args),
+            values = concat(agent_{arg_type}, task_{arg_type}),
     """
 
     queries = [
@@ -61,28 +64,30 @@ def tool_args_for_session(
     developer_id: UUID,
     session_id: UUID,
     agent_id: UUID,
+    arg_type: Literal["args", "setup"] = "args",
+    tool_type: Literal["integration", "api_call"] = "integration",
 ) -> tuple[list[str], dict]:
     session_id = str(session_id)
 
-    get_query = """
+    get_query = f"""
         input[session_id, agent_id] <- [[to_uuid($session_id), to_uuid($agent_id)]]
 
-        ?[args] :=
+        ?[values] :=
             input[session_id, agent_id],
-            *sessions {
+            *sessions {{
                 session_id,
                 metadata: session_metadata,
-            },
-            *agents {
+            }},
+            *agents {{
                 agent_id,
                 metadata: agent_metadata,
-            },
-            session_args = get(session_metadata, "x-tool-args"),
-            agent_args = get(agent_metadata, "x-tool-args"),
+            }},
+            session_{arg_type} = get(session_metadata, "x-{tool_type}-{arg_type}", {{}}),
+            agent_{arg_type} = get(agent_metadata, "x-{tool_type}-{arg_type}", {{}}),
 
             # Right values overwrite left values
             # See: https://docs.cozodb.org/en/latest/functions.html#Func.Vector.concat
-            args = concat(agent_args, session_args),  
+            values = concat(agent_{arg_type}, session_{arg_type}),
     """
 
     queries = [
@@ -103,7 +108,7 @@ def tool_args_for_session(
         TypeError: partialclass(HTTPException, status_code=400),
     }
 )
-@wrap_in_class(dict, transform=lambda x: x["args"], one=True)
+@wrap_in_class(dict, transform=lambda x: x["values"], one=True)
 @cozo_query
 @beartype
 def get_tool_args_from_metadata(
@@ -112,15 +117,28 @@ def get_tool_args_from_metadata(
     agent_id: UUID,
     session_id: UUID | None = None,
     task_id: UUID | None = None,
+    tool_type: Literal["integration", "api_call"] = "integration",
+    arg_type: Literal["args", "setup", "headers"] = "args",
 ) -> tuple[list[str], dict]:
+    common: dict = dict(
+        developer_id=developer_id,
+        agent_id=agent_id,
+        tool_type=tool_type,
+        arg_type=arg_type,
+    )
+
     match session_id, task_id:
         case (None, task_id) if task_id is not None:
             return tool_args_for_task(
-                developer_id=developer_id, agent_id=agent_id, task_id=task_id
+                **common,
+                task_id=task_id,
             )
+
         case (session_id, None) if session_id is not None:
             return tool_args_for_session(
-                developer_id=developer_id, agent_id=agent_id, session_id=session_id
+                **common,
+                session_id=session_id,
             )
+
         case (_, _):
             raise ValueError("Either session_id or task_id must be provided")