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:

   git clone https://github.com/GDP-ADMIN/CATAPA-API.git
   cd claudia/applications/digital-employee-payroll-analyst

2. Install dependencies:

   make install

   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 for detailed descriptions.

   cp .env.example .env

4. Run the application locally (optional, for testing):

   # Run locally with default message
   make run
   
   # Run with custom message
   make run MESSAGE="Check payroll compliance for November 2025"

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 admin dashboard

   • Navigate to the Application settings

   • 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

   
3. Start using the agent:

   You can now interact with the DE Payroll Analyst via CATAPA Chat.

---

Agent Architecture Diagram

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

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.

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

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

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)

---

Environment Variables

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

AIP Configuration

GDP Labs AI Agents Package (AIP) 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 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 and 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 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 page.

   • Note the password for the final step.

   
2. In Roles & Permissions, assign the Administrator role, or a role with full privileges for the following modules:

   • Master Data

   • Compensation & Benefits

   • Time Management

   • Organization

   
3. Create an OAuth 2.0 Client.

   • 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

   
4. Provide the username, password, Client ID, and Client Secret to the CATAPA infra team.

---

References

• DE Payroll Analyst User Guide

• GitHub Repository