# Technical Guide

This guide provides technical documentation for setting up, understanding, and extending the **Digital Employee - Datasaur Project Manager**.

The application retrieves and stores information from Slack and Google Mail into Notion for Datasaur in response to user queries:

* **Knowledge Retrieval**: Search and retrieve stored information from Notion based on user queries
* **Information Ingestion**: Store information, messages, and threads from Slack and Gmail directly into Notion
* **Notifications**: Optionally post summaries to Slack channels or send email distributions via Google Mail

***

### How to Setup

#### **Prerequisites**

Before starting, ensure you have:

* **Python 3.11 or 3.12**
* **UV** package manager (**>= 0.6.15**)
* **Google Cloud SDK** (optional; used by `Makefile` to authenticate to internal repositories when available)
* **Access to AIP** (for deployment) and the required MCP services (Notion, Slack, and Google Mail MCPs)

#### **Installation Steps**

1. **Go to the module directory**:

   <pre class="language-bash" data-line-numbers><code class="lang-bash">cd common/applications/digital-employee-pm-datasaur
   </code></pre>
2. **Install dependencies**:

   <pre class="language-bash" data-line-numbers><code class="lang-bash">make install
   </code></pre>

   This runs `uv sync --extra dev`. If `gcloud` is installed, the Makefile also attempts to inject auth tokens for private package indexes.
3. **Configure environment variables**:

   Copy the example environment file and update with your MCP URLs, API keys, and project configurations. See Environment Variables for detailed descriptions.

   <pre class="language-bash" data-line-numbers><code class="lang-bash">cp .env.example .env
   </code></pre>
4. **Run an agent locally (optional, for testing)**:

   <pre data-line-numbers><code># Run the datasaur agent
   make run AGENT=datasaur
   </code></pre>

#### **Deployment**

1. **Agent deployment**\
   Agent deployment is handled by the Digital Employee team through Continuous Delivery (CD). This process registers the Digital Employee—along with its identity, tools, and configurations—on the AIP platform.
2. **Enable the agent in CATAPA Chat admin dashboard**

   1. Log in to the [CATAPA Chat](http://claudia.catapa.com/) admin dashboard
   2. Navigate to the [Application settings](https://claudia.catapa.com/admin/chatbot)
   3. Create or edit an application
   4. Add **DE Project Manager Datasaur** as a supported agent in the application
   5. Click **Next** to save the configuration
   6. Manage user access to this application

   <figure><img src="https://2914931754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXbRDlxflF58D1QG2tLmP%2Fuploads%2FyBPbEtU9L8JyAFABwoSn%2Fimage.png?alt=media&#x26;token=4d06e289-2163-472b-8921-7c5460692a26" alt=""><figcaption></figcaption></figure>
3. **Start using the agent**\
   You can now interact with the DE Project Manager Datasaur via [CATAPA Chat](http://claudia.catapa.com/).

   <figure><img src="https://2914931754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXbRDlxflF58D1QG2tLmP%2Fuploads%2FvqgvjYLPzucxeKg4ULw1%2Fimage.png?alt=media&#x26;token=5f55bb41-f331-471e-b0d3-9275cf04122b" alt=""><figcaption></figcaption></figure>

***

### Agent Architecture Diagram

The Digital Employee PM Datasaur uses a **single Digital Employee**. It does not use sub-agents and relies on direct MCP connectors and built-in tools.

* Custom tools for sending filtered emails, slack notifications, date/time operations.
* MCP connectors for **Notion**, **Slack**, and **Google Mail**.

```mermaid
flowchart TD
PM["Project Manager Datasaur"]

subgraph Tools["Tools"]
FilteredEmailTool["send_filtered_email_tool"]
SlackNotifTool["send_slack_notification_tool"]
TimeTool["time_tool"]
DateRangeTool["date_range_tool"]
EpochTool["iso8601_date_to_unix_epoch_tool"]
end

subgraph MCPs["GL Connectors"]
Notion["notion_mcp"]
Slack["slack_mcp"]
GMail["google_mail_mcp"]
end

PM --> MCPs
PM --> FilteredEmailTool
PM --> SlackNotifTool
PM --> TimeTool
PM --> DateRangeTool
PM --> EpochTool
```

The key idea is: **the “project” differences are configuration-only** (identity, email, environment suffix, and API keys).

### **Agent Description**

#### **Datasaur Project Manager Digital Employee**

* **Type**: Main deployed Digital Employee
* **Purpose**: Knowledge Aggregation system that retrieves and stores information from Slack and Google Mail into Notion in response to user queries.
* **Model**: `GPT_5_2_MODEL_NAME` (from `digital_employee_core`)
* **Identity**: `DE_NAME {full_project_name}` (from `digital_employee_pm_datasaur.agents.identity.constants`)
* **Tools:**
  * `send_filtered_email_tool`: Sends emails while optionally filtering recipients by suffix.
  * `send_slack_notification_tool`: Post messages to specific specified Slack channels.
  * `time_tool`: Provides time context if needed by user query.
  * `date_range_tool`: Provides time context if needed by user query.
  * `iso8601_date_to_unix_epoch_tool`: Converts time to Unix epoch seconds, required by the `slack_conversations_history` tool.
* **MCPs**:
  * `notion_mcp`
  * `slack_mcp`
  * `google_mail_mcp`

#### **Tools Reference**

This project **composes** tools provided by `digital_employee_core` and MCP connectors:

<table data-full-width="false"><thead><tr><th width="341.3203125">Component</th><th>Purpose</th></tr></thead><tbody><tr><td><code>send_filtered_email_tool</code></td><td>Sends emails while optionally filtering recipients by suffix</td></tr><tr><td><code>send_slack_notification_tool</code></td><td>Sends a Slack notification message to a specified channel using the Slack MCP</td></tr><tr><td><code>date_range_tool</code></td><td>Provides time context if needed by user query</td></tr><tr><td><code>time_tool</code></td><td>Provides time context if needed by user query</td></tr><tr><td><code>iso8601_date_to_unix_epoch_tool</code></td><td>Converts time to Unix epoch seconds, required by the <code>slack_conversations_history</code> tool</td></tr><tr><td><code>notion_mcp</code></td><td>Search, retrieve, and store information from/to Notion</td></tr><tr><td><code>slack_mcp</code></td><td>Fetch messages and threads from Slack</td></tr><tr><td><code>google_mail_mcp</code></td><td>Sends email via Gmail and fetches emails</td></tr></tbody></table>

***

#### **Code Snippet**

Below is the core function that creates a Project Manager Datasaur Digital Employee instance (identity, configs, MCPs).

See the [full source code on GitHub](https://github.com/GDP-ADMIN/digital-employee/blob/e/de-pm-datasaur-leads/common/applications/digital-employee-pm-datasaur/digital_employee_pm_datasaur/pm/agents/workflow.py).

```python
def create_digital_employee_pm(config: ProjectConfig) -> DigitalEmployee:
    pm_job_instructions = pm_job_instructions_file.read_text(encoding="utf-8")

    job = DigitalEmployeeJob(
        title=f"{DE_NAME} {config.full_project_name}",
        description=f"A digital employee that is a Project Manager {config.full_project_name}",
        instruction=instructions,
    )

    identity = DigitalEmployeeIdentity(name=config.identity_name,email=email,job=job,)

    configurations = [
        DigitalEmployeeConfiguration(key="NOTION_MCP_URL", value=NOTION_MCP_URL),
        DigitalEmployeeConfiguration(key="SLACK_MCP_URL", value=SLACK_MCP_URL),
        DigitalEmployeeConfiguration(key="GOOGLE_MAIL_MCP_URL", value=GOOGLE_MAIL_MCP_URL),
        *(DigitalEmployeeConfiguration(key=k, value=",".join(v)) for k, v in MCP_ALLOWED_TOOLS.items()),
        DigitalEmployeeConfiguration(key="NOTION_MCP_X_API_KEY",value=_get_required_env("NOTION_MCP_X_API_KEY", config.project_key)),
        DigitalEmployeeConfiguration(key="SLACK_MCP_X_API_KEY",value=_get_required_env("SLACK_MCP_X_API_KEY", config.project_key)),
        DigitalEmployeeConfiguration(key="GOOGLE_MCP_X_API_KEY",value=_get_required_env("GOOGLE_MCP_X_API_KEY", config.project_key)),
        DigitalEmployeeConfiguration(key="DEFAULT_RECIPIENT_FILTER",value=DEFAULT_RECIPIENT_FILTER),
    ]

    return DigitalEmployee(
        identity=identity,
        sub_agents=[],
        configurations=configurations,
        tools=[
            send_filtered_email_tool,
            send_slack_notification_tool,
            date_range_tool,
            time_tool,
            iso8601_date_to_unix_epoch_tool,
        ],
        mcps=[notion_mcp,slack_mcp,google_mail_mcp],
        model=GPT_5_2_MODEL_NAME,
        schedules=[],
        agent_config={
            "step_limit_config": StepLimitConfig(max_steps=AGENT_MAX_STEPS),
        },
    )
```

This function:

1. Validates required environment variables are set.
2. Loads job instructions from `pm_job.md` and dynamically formats it.
3. Builds a `DigitalEmployeeJob` and `DigitalEmployeeIdentity` (multi-language enabled).
4. Configures tool allowlists and attaches API keys to `DigitalEmployeeConfiguration`.
5. Attaches the built-in custom tools and MCPs (Notion, Slack, Google Mail).
6. Returns an **undeployed** `DigitalEmployee` instance constrained by step limits.

**Usage Example**

Run a project agent module:

```bash
uv run python -m digital_employee_pm_datasaur.pm.agents.datasaur
```

Or run via Makefile:

```bash
make run AGENT=datasaur
```

***

### Environment Variables

This section describes all environment variables required to configure the Digital Employee PM Datasaur.

**AIP Configuration**

GDP Labs [AI Agents Package (AIP)](https://gdplabs.gitbook.io/gl-aip/getting-started/quick-start-guide/local-vs-remote#remote-mode) is the platform where the Digital Employee is deployed.

| Variable      | Description                      |
| ------------- | -------------------------------- |
| `AIP_API_URL` | Base URL of the AIP platform API |
| `AIP_API_KEY` | API key for authenticating AIP   |

**MCP Base URLs (shared, no suffix)**

| Variable              | Description                  |
| --------------------- | ---------------------------- |
| `NOTION_MCP_URL`      | Base URL for Notion MCP      |
| `SLACK_MCP_URL`       | Base URL for Slack MCP       |
| `GOOGLE_MAIL_MCP_URL` | Base URL for Google Mail MCP |

**Project-Specific Keys (with suffix)**

`project_key` determines the suffix for env var names. For `project_key="DATASAUR"` → suffix is `_DATASAUR`.

| Variable pattern                 | Description                                                   |
| -------------------------------- | ------------------------------------------------------------- |
| `DEPM_EMAIL{_PROJECT}`           | Required: Employee email address (e.g. DEPM\_EMAIL\_DATASAUR) |
| `NOTION_MCP_X_API_KEY{_PROJECT}` | Notion API key for the project                                |
| `SLACK_MCP_X_API_KEY{_PROJECT}`  | Slack API key for the project                                 |
| `GOOGLE_MCP_X_API_KEY{_PROJECT}` | Google Mail API key for the project                           |

Concrete examples (from `.env.example`):

* `NOTION_MCP_X_API_KEY_DATASAUR`
* `SLACK_MCP_X_API_KEY_DATASAUR`
* `DEPM_EMAIL_DATASAUR`

**Tool Configs**

| Variable                   | Description                                           |
| -------------------------- | ----------------------------------------------------- |
| `DEFAULT_RECIPIENT_FILTER` | Default recipient filter for Send Filtered Email Tool |
| `AGENT_MAX_STEPS`          | Maximum steps allowed for the agent to execute        |

***

### References

* [DE Project Manager Datasaur User Guide](https://gdplabs.gitbook.io/catapa/digital-employee-de/list-of-de/pamela-de-project-manager/pamela-information-capturing-and-lookup/user-guide)
* [GitHub Repository](https://github.com/GDP-ADMIN/digital-employee/tree/e/de-pm-datasaur-leads/common/applications/digital-employee-pm-datasaur)