# Technical Guide

This guide provides technical documentation for setting up, understanding, and extending the Digital Employee Payroll Analyst.

### How to Setup

#### Prerequisites

Before starting, ensure you have:

* **Python 3.11 or 3.12**
* **Poetry 2.1.3** or higher
* **Google Cloud SDK** (for accessing internal package repositories)
* **Access to CATAPA API** with valid credentials

#### Installation Steps

1. **Clone the repository**:

   <pre class="language-bash" data-line-numbers><code class="lang-bash">git clone https://github.com/GDP-ADMIN/CATAPA-API.git
   cd claudia/applications/digital-employee-payroll-analyst
   </code></pre>
2. **Install dependencies**:

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

   This command configures Poetry authentication for internal repositories and installs all project dependencies.
3. **Configure environment variables**:

   Copy the example environment file and update with your credentials. See [Environment Variables](#environment-variables) for detailed descriptions.

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

   <pre class="language-bash" data-line-numbers><code class="lang-bash"># Run locally with default message
   make run

   # Run with custom message
   make run MESSAGE="Check payroll compliance for November 2025"
   </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**:

   * Log in to the [CATAPA Chat](https://claudia.catapa.com/) admin dashboard
   * Navigate to the [Application settings](https://claudia.catapa.com/admin/chatbot)
   * Create or edit an application
   * Add **DE Payroll Analyst** as a supported agent in the application
   * Click **Next** to save the configuration
   * 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%2Fgit-blob-7b41b4cc199dfb82ea783c298d6f37fe6e2c0d61%2Fimage%20(99).png?alt=media" alt=""><figcaption></figcaption></figure>
3. **Start using the agent**:

   You can now interact with the DE Payroll Analyst via [CATAPA Chat](https://claudia.catapa.com/).

<figure><img src="https://2914931754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXbRDlxflF58D1QG2tLmP%2Fuploads%2Fgit-blob-6decdc650c10e81af8798e3fe01c420fb2e31c30%2Fimage%20(97).png?alt=media" alt=""><figcaption></figcaption></figure>

***

### Agent Architecture Diagram

The Digital Employee Payroll Analyst uses a single-agent architecture with specialized tools for different tasks.

{% @mermaid/diagram content="flowchart TB
subgraph Tools\["Tools"]
T1\["get\_company\_tool"]
T2\["check\_compliance\_tool"]
T3\["markdown\_to\_pdf\_and\_send\_as\_email\_attachment\_tool"]
T4\["time\_tool"]
end

Coordinator\["DE Payroll Analyst"] --> T1 & T2 & T3 & T4" %}

#### Agent Description

**DE Payroll Analyst** is the main agentic system responsible for:

* Reviewing payroll-related data
* Detecting potential compliance risks or data inconsistencies
* Producing actionable insights and recommendations for payroll teams

#### Tools Reference

| Tool                                                | Purpose                                       |
| --------------------------------------------------- | --------------------------------------------- |
| `get_company_tool`                                  | Retrieves company information from CATAPA API |
| `check_compliance_tool`                             | Executes compliance validation rules          |
| `markdown_to_pdf_and_send_as_email_attachment_tool` | Generates PDF reports and sends via email     |
| `time_tool`                                         | Gets current time for report generation       |

***

### Code Snippet

Below is a code snippet showing how the Payroll Analyst Digital Employee is created and configured. See the [full source code on GitHub](https://github.com/GDP-ADMIN/CATAPA-API/blob/master/claudia/applications/digital-employee-payroll-analyst/digital_employee_payroll_analyst/main.py).

{% code lineNumbers="true" %}

```python
def create_payroll_analyst(model: str = DEFAULT_MODEL_NAME) -> PayrollAnalystDigitalEmployee:
    digital_employee = PayrollAnalystDigitalEmployee(
        identity=create_identity(),
        tools=[
            Tool.from_langchain(GetCompanyTool),
            Tool.from_langchain(CheckComplianceTool),
            Tool.from_langchain(MarkdownToPdfAndSendAsEmailAttachment),
            time_tool,
        ],
        configurations=_create_configurations(),
        model=model,
    )
    return digital_employee
```

{% endcode %}

This function:

1. Creates the agent identity using `create_identity()`
2. Registers four specialized tools for company data, compliance checks, report generation, and time retrieval
3. Loads configurations from environment variables
4. Initializes the agent with the specified model

#### Usage Example

{% code lineNumbers="true" %}

```python
payroll_analyst = create_payroll_analyst(model="openai/gpt-5.2")
result = payroll_analyst.run(
    message="Check payroll compliance for November 2025",
    local=True
)
print(result)
```

{% endcode %}

***

### Environment Variables

This section describes all environment variables required to configure the Digital Employee Payroll Analyst.

#### 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 with the AIP platform |

#### OpenAI Configuration

The LLM provider used by the agent when running the Digital Employee locally.

| Variable         | Description                                   |
| ---------------- | --------------------------------------------- |
| `OPENAI_API_KEY` | API key for OpenAI services used by the agent |

#### GL Connector Configuration

[GL Connector](https://gdplabs.gitbook.io/sdk/tutorials/connectors/agentic-tools-and-model-context-protocol-mcp#pre-requisites) is a proxy service that simplifies integration with Connector-compatible APIs. In this case, it is used as a gateway to connect to Gmail API for sending email reports.

| Variable                  | Description                                 |
| ------------------------- | ------------------------------------------- |
| `GL_CONNECTOR_BASE_URL`   | Base URL of the GL Connector service        |
| `GL_CONNECTOR_API_KEY`    | API key for GL Connector authentication     |
| `GL_CONNECTOR_IDENTIFIER` | User identifier for GL Connector            |
| `GL_CONNECTOR_SECRET`     | User secret for GL Connector authentication |

#### CATAPA Configuration

CATAPA is the HRIS system where payroll data is retrieved.

| Variable                     | Description                                   |
| ---------------------------- | --------------------------------------------- |
| `CATAPA_BASE_URL`            | Base URL of the CATAPA API                    |
| `CATAPA_USERNAME`            | Username for CATAPA authentication            |
| `CATAPA_PASSWORD`            | Password for CATAPA authentication            |
| `CATAPA_TENANT_ID`           | Tenant ID to identify the company in CATAPA   |
| `CATAPA_OAUTH_CLIENT_ID`     | OAuth 2.0 client ID for CATAPA API access     |
| `CATAPA_OAUTH_CLIENT_SECRET` | OAuth 2.0 client secret for CATAPA API access |

> **Note:** The CATAPA [user](https://apps.catapa.com/dashboard/security/role-permission/privilege) and [OAuth client](https://apps.catapa.com/dashboard/setup/settings/oauth-client) must have full privileges for the following modules:
>
> * Payroll / Compensation & Benefits
> * Employee / Organization
> * Time Management
> * Master Data

#### Payroll Analyst Agent Configuration

Agent-specific settings for compliance validation rules and behavior.

| Variable                                       | Description                                                                                                                              | Default |
| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `PAYROLL_ANALYST_THP_MAX_DEDUCTION_PERCENTAGE` | Maximum allowed deduction percentage from Take Home Pay (THP).                                                                           | `30`    |
| `PAYROLL_ANALYST_RSP_MAX_DAY_OF_MONTH`         | Maximum day of month for Regular Salary Payment (RSP).                                                                                   | `28`    |
| `PAYROLL_ANALYST_THR_MIN_DAYS_BEFORE_HOLIDAY`  | Minimum days before holiday that THR must be paid.                                                                                       | `7`     |
| `PAYROLL_ANALYST_EMAIL_ADDRESS`                | Sender email address for compliance reports                                                                                              | -       |
| `PAYROLL_ANALYST_DEMO_LIMIT_MAX_ENTRY`         | Limits the number of employee records processed. Set to `0` for unlimited (production). Use a positive number for demo/testing purposes. | `0`     |

***

### CATAPA Setup

1. Add a [new employee](https://apps.catapa.com/dashboard/personnel-admin/employee-directory/active-employee/add) to represent the Digital Employee.

   * Employee name: preferably **“Claudia DE”**
   * Note the username for the final step
   * Complete the verification instructions sent to the user’s email to set the password.\
     Alternatively, if no email is provided, manually reset the user password from the [User List](https://development.catapa.com/dashboard/security/user/user-list/existing) page.
   * Note the password for the final step.

   <figure><img src="https://2914931754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXbRDlxflF58D1QG2tLmP%2Fuploads%2Fyspj6OVWRLC3dlGKzQeG%2Fimage.png?alt=media&#x26;token=5edfadff-c69b-43c6-86ed-7b6f00291e25" alt=""><figcaption></figcaption></figure>
2. In [Roles & Permissions](https://apps.catapa.com/dashboard/security/role-permission/privilege), assign the **Administrator** role, or a role with full privileges for the following modules:

   * Master Data
   * Compensation & Benefits
   * Time Management
   * Organization

   <figure><img src="https://2914931754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXbRDlxflF58D1QG2tLmP%2Fuploads%2FmLRNRzeYIEZerBW2n7Jc%2Fimage.png?alt=media&#x26;token=443dd18d-2b3c-4bf9-8a2e-934393b74e23" alt=""><figcaption></figcaption></figure>
3. Create an [OAuth 2.0 Client](https://apps.catapa.com/dashboard/setup/admin-panel/oauth-client/add).

   * Client ID: preferably **`de_payroll_analyst`**
   * Authorized Grant Type: **client\_credentials**
   * Client Access: grant full access to **Payroll**, **Employee**, and **Time Management**
   * Web Server Redirect URI: `https://catapa.com`
   * Click **Save**, then copy the generated **Client Secret**

   <div align="left"><figure><img src="https://2914931754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXbRDlxflF58D1QG2tLmP%2Fuploads%2Fb2T67Wevrz8vtmUVwNh1%2FScreenshot%20from%202026-02-10%2007-57-43.png?alt=media&#x26;token=d258bd57-b341-441c-9c15-48a8e7ac5229" alt=""><figcaption></figcaption></figure></div>
4. Provide the **username**, **password**, **Client ID**, and **Client Secret** to the CATAPA infra team.

***

### References

* [DE Payroll Analyst User Guide](https://gdplabs.gitbook.io/catapa/digital-employee-de/list-of-de/claudia-de-hr/claudia-de-payroll-analyst/user-guide)
* [GitHub Repository](https://github.com/GDP-ADMIN/CATAPA-API/tree/master/claudia/applications/digital-employee-payroll-analyst)