construct-labs-crm-env 0.1.1__py3-none-any.whl

construct_labs_crm_env/models.py

@@ -0,0 +1,260 @@
+"""Data models for the CRM Agent Environment.
+
+This module provides the core data types for interacting with the CRM Agent
+Environment, including actions, observations, and state representations.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from pydantic import ConfigDict, Field
+
+from ._vendored import Action, Observation, State
+
+
+class CRMActionType(str, Enum):
+    """Types of actions available in the CRM environment.
+
+    Actions are grouped by the CRM entity they operate on:
+    - Company: CRUD operations for company records
+    - Person: CRUD operations for contact/person records
+    - Opportunity: CRUD operations for sales opportunities
+    - Note: Create and list notes attached to records
+    - Task: CRUD operations for tasks
+    - Answer: Submit final answer for evaluation
+    """
+
+    # Company actions
+    CREATE_COMPANY = "create_company"
+    UPDATE_COMPANY = "update_company"
+    DELETE_COMPANY = "delete_company"
+    LIST_COMPANIES = "list_companies"
+    GET_COMPANY = "get_company"
+
+    # Person/Contact actions
+    CREATE_PERSON = "create_person"
+    UPDATE_PERSON = "update_person"
+    DELETE_PERSON = "delete_person"
+    LIST_PEOPLE = "list_people"
+    GET_PERSON = "get_person"
+
+    # Opportunity actions
+    CREATE_OPPORTUNITY = "create_opportunity"
+    UPDATE_OPPORTUNITY = "update_opportunity"
+    DELETE_OPPORTUNITY = "delete_opportunity"
+    LIST_OPPORTUNITIES = "list_opportunities"
+    GET_OPPORTUNITY = "get_opportunity"
+
+    # Note actions
+    CREATE_NOTE = "create_note"
+    LIST_NOTES = "list_notes"
+
+    # Task actions
+    CREATE_TASK = "create_task"
+    UPDATE_TASK = "update_task"
+    COMPLETE_TASK = "complete_task"
+    LIST_TASKS = "list_tasks"
+
+    # Final answer
+    SUBMIT_ANSWER = "submit_answer"
+
+
+class CrmAgentAction(Action):
+    """Action to execute in the CRM environment.
+
+    This model represents all possible actions an agent can take. The `action_type`
+    field determines which operation to perform, and the relevant fields for that
+    action type should be populated.
+
+    Example:
+        >>> # List companies
+        >>> action = CrmAgentAction(
+        ...     action_type=CRMActionType.LIST_COMPANIES,
+        ...     limit=10
+        ... )
+
+        >>> # Create a company
+        >>> action = CrmAgentAction(
+        ...     action_type=CRMActionType.CREATE_COMPANY,
+        ...     company_name="Acme Corp",
+        ...     company_domain="acme.com"
+        ... )
+
+        >>> # Submit final answer
+        >>> action = CrmAgentAction(
+        ...     action_type=CRMActionType.SUBMIT_ANSWER,
+        ...     answer="The total revenue is $1.5M"
+        ... )
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    action_type: CRMActionType = Field(..., description="Type of CRM action to perform")
+
+    # Common fields
+    record_id: str | None = Field(
+        default=None,
+        description="ID of the record to operate on (for get/update/delete)",
+    )
+
+    # Company fields
+    company_name: str | None = Field(default=None, description="Name of the company")
+    company_domain: str | None = Field(
+        default=None, description="Domain/website of the company"
+    )
+    company_address: str | None = Field(
+        default=None, description="Address of the company"
+    )
+    company_employees: int | None = Field(
+        default=None, description="Number of employees"
+    )
+
+    # Person fields
+    person_first_name: str | None = Field(
+        default=None, description="First name of the person"
+    )
+    person_last_name: str | None = Field(
+        default=None, description="Last name of the person"
+    )
+    person_email: str | None = Field(default=None, description="Email of the person")
+    person_phone: str | None = Field(
+        default=None, description="Phone number of the person"
+    )
+    person_company_id: str | None = Field(
+        default=None, description="ID of the company this person belongs to"
+    )
+    person_job_title: str | None = Field(
+        default=None, description="Job title of the person"
+    )
+
+    # Opportunity fields
+    opportunity_name: str | None = Field(
+        default=None, description="Name of the opportunity"
+    )
+    opportunity_amount: float | None = Field(default=None, description="Deal amount")
+    opportunity_stage: str | None = Field(
+        default=None,
+        description="Stage: 'NEW', 'MEETING', 'PROPOSAL', 'WON', or 'LOST'",
+    )
+    opportunity_close_date: str | None = Field(
+        default=None, description="Expected close date (ISO format)"
+    )
+    opportunity_company_id: str | None = Field(
+        default=None, description="ID of the company for this opportunity"
+    )
+    opportunity_person_id: str | None = Field(
+        default=None, description="ID of the contact person for this opportunity"
+    )
+
+    # Note fields
+    note_body: str | None = Field(default=None, description="Content of the note")
+    note_title: str | None = Field(default=None, description="Title of the note")
+    note_target_person_id: str | None = Field(
+        default=None, description="ID of the person to link this note to"
+    )
+    note_target_company_id: str | None = Field(
+        default=None, description="ID of the company to link this note to"
+    )
+    note_target_opportunity_id: str | None = Field(
+        default=None, description="ID of the opportunity to link this note to"
+    )
+
+    # Task fields
+    task_title: str | None = Field(default=None, description="Title of the task")
+    task_body: str | None = Field(default=None, description="Description of the task")
+    task_due_date: str | None = Field(default=None, description="Due date (ISO format)")
+    task_assignee_id: str | None = Field(
+        default=None, description="ID of the user to assign the task to"
+    )
+    task_status: str | None = Field(default=None, description="Status of the task")
+    task_target_person_id: str | None = Field(
+        default=None, description="ID of the person to link this task to"
+    )
+    task_target_company_id: str | None = Field(
+        default=None, description="ID of the company to link this task to"
+    )
+    task_target_opportunity_id: str | None = Field(
+        default=None, description="ID of the opportunity to link this task to"
+    )
+
+    # Final answer
+    answer: str | None = Field(default=None, description="The final answer to submit")
+
+    # Pagination and filtering
+    limit: int | None = Field(
+        default=60, description="Maximum number of results to return (max 200)"
+    )
+    cursor: str | None = Field(
+        default=None, description="Pagination cursor (legacy, use starting_after)"
+    )
+    starting_after: str | None = Field(
+        default=None, description="Returns objects starting after this cursor"
+    )
+    ending_before: str | None = Field(
+        default=None, description="Returns objects ending before this cursor"
+    )
+    order_by: str | None = Field(
+        default=None, description="Order by: field_name_1,field_name_2[DIRECTION]"
+    )
+    filter: str | None = Field(
+        default=None, description="Filter: field[COMPARATOR]:value"
+    )
+    depth: int | None = Field(
+        default=1, description="Nesting depth: 0=primary, 1=direct relations"
+    )
+
+
+class CrmAgentObservation(Observation):
+    """Observation returned after executing an action.
+
+    Contains the result of the action, including any data returned by the CRM
+    and error information if the action failed.
+
+    Attributes:
+        success: Whether the action completed successfully.
+        error: Error message if the action failed, None otherwise.
+        data: Raw response data from the CRM server.
+        done: Whether the episode has ended (inherited from Observation).
+        reward: Reward signal if applicable (inherited from Observation).
+    """
+
+    success: bool = Field(default=True, description="Whether the action succeeded")
+    error: str | None = Field(
+        default=None, description="Error message if action failed"
+    )
+    data: dict[str, Any] = Field(
+        default_factory=dict, description="Raw response data from server"
+    )
+
+
+class CrmAgentState(State):
+    """Internal state of the CRM environment session.
+
+    Tracks metadata about the current episode including entity counts
+    and session information.
+
+    Attributes:
+        env_name: Name of the environment.
+        done: Whether the episode has ended.
+        terminated: Whether the episode terminated normally.
+        truncated: Whether the episode was truncated (e.g., step limit).
+        success: Whether the task was completed successfully.
+        companies_count: Number of companies in the CRM.
+        people_count: Number of people/contacts in the CRM.
+        opportunities_count: Number of opportunities in the CRM.
+        last_action: String representation of the last action taken.
+        api_url: The CRM API endpoint URL.
+    """
+
+    env_name: str = "crm-agent"
+    done: bool = False
+    terminated: bool = False
+    truncated: bool = False
+    success: bool = False
+    companies_count: int = 0
+    people_count: int = 0
+    opportunities_count: int = 0
+    last_action: str | None = None
+    api_url: str = ""

construct_labs_crm_env/protocol.py

@@ -0,0 +1,25 @@
+"""Protocol types for CRM Agent Environment.
+
+This module provides the ParsedAction dataclass used for parsing
+tool calls from LLM outputs into environment actions.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class ParsedAction:
+    """Result of parsing a tool call into an environment action.
+
+    Attributes:
+        action: The parsed action object, or None if parsing failed.
+        is_valid: Whether the tool call was successfully parsed.
+        error_message: Human-readable error message if parsing failed.
+    """
+
+    action: Any | None
+    is_valid: bool
+    error_message: str | None = None

construct_labs_crm_env-0.1.1.dist-info/METADATA

@@ -0,0 +1,412 @@
+Metadata-Version: 2.4
+Name: construct-labs-crm-env
+Version: 0.1.1
+Summary: CRM Agent Environment SDK by Construct Labs - Train RL agents to interact with CRM systems
+Project-URL: Homepage, https://construct-labs.com
+Author-email: Construct Labs GmbH <hello@construct-labs.com>
+License: Proprietary
+License-File: LICENSE
+Keywords: agent,ai,crm,environment,machine-learning,reinforcement-learning
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Construct Labs CRM Agent Environment
+
+Python SDK for the Construct Labs CRM Agent Environment - a reinforcement learning environment for training AI agents to interact with CRM systems.
+
+## License
+
+This software requires a commercial license from Construct Labs GmbH. 
+Contact hello@construct-labs.com for licensing inquiries.
+
+## Installation
+
+```bash
+pip install construct-labs-crm-env
+```
+
+## Quick Start
+
+```python
+from construct_labs_crm_env import CrmAgentEnv, CrmAgentAction, CRMActionType
+
+# Connect to the CRM environment
+with CrmAgentEnv(
+    base_url="https://api.construct-labs.com",
+    api_key="your-api-key"  # Issued by Construct Labs
+) as env:
+    # Reset the environment
+    result = env.reset()
+    
+    # List companies
+    result = env.step(CrmAgentAction(
+        action_type=CRMActionType.LIST_COMPANIES,
+        limit=10
+    ))
+    print(result.observation.data)
+```
+
+## Environment Variables
+
+You can set your API key via environment variable:
+
+```bash
+export CRM_AGENT_API_KEY=your-api-key
+```
+
+```python
+# API key is read from environment
+env = CrmAgentEnv(base_url="https://api.construct-labs.com")
+```
+
+## LLM Integration Example
+
+The SDK is designed to work with LLM-based agents. Here's how to parse LLM tool calls:
+
+```python
+from construct_labs_crm_env import CrmAgentEnv
+
+with CrmAgentEnv(
+    base_url="https://api.construct-labs.com",
+    api_key="your-api-key"
+) as env:
+    result = env.reset()
+    
+    # Simulate an LLM generating a tool call
+    llm_tool_call = {
+        "name": "list_companies",
+        "arguments": {"limit": 5}
+    }
+    
+    # Parse the tool call into a CrmAgentAction
+    parsed = env.parse_tool_call(llm_tool_call)
+    
+    if parsed.is_valid:
+        result = env.step(parsed.action)
+        print(result.observation.model_dump_json(indent=2))
+    else:
+        print(f"Invalid tool call: {parsed.error_message}")
+```
+
+## Customization
+
+Subclass `CrmAgentEnv` to customize agent behavior:
+
+### Custom System Prompt
+
+```python
+class SalesAgent(CrmAgentEnv):
+    @property
+    def system_prompt(self) -> str:
+        return """You are a sales assistant AI.
+        
+Your goal is to help close deals by:
+1. Finding relevant companies and contacts
+2. Creating opportunities with accurate values
+3. Adding follow-up tasks
+
+Be concise. Focus on high-value opportunities."""
+```
+
+### Restricted Tool Set
+
+```python
+class ReadOnlyAgent(CrmAgentEnv):
+    """Agent that can only read data, not modify."""
+    
+    @property
+    def tools(self) -> list[dict]:
+        read_only = {'list_companies', 'get_company', 'list_people', 
+                     'get_person', 'list_opportunities', 'submit_answer'}
+        return [t for t in self._default_tools() 
+                if t['function']['name'] in read_only]
+```
+
+### Custom Observation Formatting
+
+```python
+class VerboseAgent(CrmAgentEnv):
+    def format_observation(self, observation):
+        base = super().format_observation(observation)
+        return f"=== CRM Response ===\n{base}\n=== End ==="
+```
+
+## Available Actions
+
+### Company Operations
+- `LIST_COMPANIES` - List all companies
+- `GET_COMPANY` - Get a specific company by ID
+- `CREATE_COMPANY` - Create a new company
+- `UPDATE_COMPANY` - Update an existing company
+- `DELETE_COMPANY` - Delete a company
+
+### Contact Operations
+- `LIST_PEOPLE` - List all contacts
+- `GET_PERSON` - Get a specific contact by ID
+- `CREATE_PERSON` - Create a new contact
+- `UPDATE_PERSON` - Update an existing contact
+- `DELETE_PERSON` - Delete a contact
+
+### Opportunity Operations
+- `LIST_OPPORTUNITIES` - List all opportunities
+- `GET_OPPORTUNITY` - Get a specific opportunity by ID
+- `CREATE_OPPORTUNITY` - Create a new opportunity
+- `UPDATE_OPPORTUNITY` - Update an existing opportunity
+- `DELETE_OPPORTUNITY` - Delete an opportunity
+
+### Note Operations
+- `LIST_NOTES` - List all notes
+- `CREATE_NOTE` - Create a note attached to a record
+
+### Task Operations
+- `LIST_TASKS` - List all tasks
+- `CREATE_TASK` - Create a new task
+- `UPDATE_TASK` - Update an existing task
+- `COMPLETE_TASK` - Mark a task as complete
+
+### Submit Answer
+- `SUBMIT_ANSWER` - Submit the final answer and end the session
+
+## Integration with Training Frameworks
+
+### Collecting Rollouts for RL Training
+
+The SDK is designed for reinforcement learning. Here's how to collect rollouts with rewards:
+
+```python
+from dataclasses import dataclass, field
+from construct_labs_crm_env import CrmAgentEnv, CrmAgentObservation
+
+@dataclass
+class Rollout:
+    """A single episode rollout for training."""
+    observations: list[CrmAgentObservation] = field(default_factory=list)
+    actions: list[dict] = field(default_factory=list)  # Raw tool calls
+    rewards: list[float] = field(default_factory=list)
+    done: bool = False
+    total_reward: float = 0.0
+
+def collect_rollout(env: CrmAgentEnv, agent, seed: int | None = None) -> Rollout:
+    """Collect a single rollout from the environment."""
+    rollout = Rollout()
+    
+    # Reset environment
+    result = env.reset(seed=seed)
+    rollout.observations.append(result.observation)
+    
+    while not result.done:
+        # Get action from agent (returns tool call dict)
+        tool_call = agent.get_action(
+            system_prompt=env.system_prompt,
+            tools=env.tools,
+            observation=result.observation,
+        )
+        
+        # Parse and execute
+        parsed = env.parse_tool_call(tool_call)
+        
+        if parsed.is_valid:
+            result = env.step(parsed.action)
+            reward = result.reward if result.reward is not None else 0.0
+        else:
+            # Invalid action penalty
+            reward = -1.0
+            result.done = True
+        
+        # Store transition
+        rollout.actions.append(tool_call)
+        rollout.rewards.append(reward)
+        rollout.observations.append(result.observation)
+    
+    rollout.done = True
+    rollout.total_reward = sum(rollout.rewards)
+    return rollout
+
+# Collect multiple rollouts for training
+def collect_rollouts(
+    env: CrmAgentEnv,
+    agent,
+    num_rollouts: int,
+    seed_offset: int = 0,
+) -> list[Rollout]:
+    """Collect multiple rollouts for batch training."""
+    rollouts = []
+    for i in range(num_rollouts):
+        rollout = collect_rollout(env, agent, seed=seed_offset + i)
+        rollouts.append(rollout)
+    return rollouts
+
+# Example usage
+with CrmAgentEnv(
+    base_url="https://api.construct-labs.com",
+    api_key="your-api-key"
+) as env:
+    # Collect 10 rollouts
+    rollouts = collect_rollouts(env, your_agent, num_rollouts=10)
+    
+    # Compute statistics
+    avg_reward = sum(r.total_reward for r in rollouts) / len(rollouts)
+    avg_length = sum(len(r.actions) for r in rollouts) / len(rollouts)
+    
+    print(f"Average reward: {avg_reward:.2f}")
+    print(f"Average episode length: {avg_length:.1f}")
+```
+
+### GRPO Training Integration
+
+For Group Relative Policy Optimization (GRPO) training:
+
+```python
+from construct_labs_crm_env import CrmAgentEnv
+
+def collect_grpo_group(
+    env: CrmAgentEnv,
+    agent,
+    group_size: int = 8,
+    seed: int = 0,
+) -> list[Rollout]:
+    """Collect a group of rollouts with the same seed for GRPO."""
+    group = []
+    for _ in range(group_size):
+        # Same seed = same initial state, different agent samples
+        rollout = collect_rollout(env, agent, seed=seed)
+        group.append(rollout)
+    return group
+
+def compute_grpo_advantages(group: list[Rollout]) -> list[float]:
+    """Compute relative advantages within a group."""
+    rewards = [r.total_reward for r in group]
+    mean_reward = sum(rewards) / len(rewards)
+    std_reward = (sum((r - mean_reward) ** 2 for r in rewards) / len(rewards)) ** 0.5
+    
+    if std_reward < 1e-8:
+        return [0.0] * len(rewards)
+    
+    return [(r - mean_reward) / std_reward for r in rewards]
+
+# Training loop
+with CrmAgentEnv(
+    base_url="https://api.construct-labs.com",
+    api_key="your-api-key"
+) as env:
+    for step in range(num_training_steps):
+        # Collect group of rollouts
+        group = collect_grpo_group(env, agent, group_size=8, seed=step)
+        
+        # Compute advantages
+        advantages = compute_grpo_advantages(group)
+        
+        # Update policy using advantages
+        agent.update(group, advantages)
+```
+
+### Basic Training Loop
+
+```python
+from construct_labs_crm_env import CrmAgentEnv
+
+env = CrmAgentEnv(
+    base_url="https://api.construct-labs.com",
+    api_key="your-api-key"
+)
+
+with env:
+    result = env.reset(seed=42)
+    
+    while not result.done:
+        # Get action from your agent/LLM
+        tool_call = your_agent.get_action(
+            env.system_prompt,
+            env.tools,
+            result.observation
+        )
+        
+        # Parse and execute
+        parsed = env.parse_tool_call(tool_call)
+        if parsed.is_valid:
+            result = env.step(parsed.action)
+        else:
+            # Handle invalid action
+            print(f"Invalid action: {parsed.error_message}")
+            break
+```
+
+## API Reference
+
+### CrmAgentEnv
+
+Main client class for interacting with the CRM environment.
+
+**Constructor:**
+- `base_url` (str): Base URL of the CRM environment server
+- `api_key` (str, optional): API key for authentication
+- `connect_timeout_s` (float): Connection timeout in seconds (default: 10)
+- `message_timeout_s` (float): Message timeout in seconds (default: 60)
+
+**Methods:**
+- `reset(seed=None)` - Reset the environment
+- `step(action)` - Execute an action
+- `state()` - Get current environment state
+- `close()` - Close the connection
+- `parse_tool_call(tool_call)` - Parse LLM tool call to action
+- `format_observation(observation)` - Format observation for LLM
+
+**Properties (overridable):**
+- `system_prompt` - System prompt for the agent
+- `tools` - Available tool definitions
+
+### CrmAgentAction
+
+Pydantic model for CRM actions.
+
+```python
+action = CrmAgentAction(
+    action_type=CRMActionType.CREATE_COMPANY,
+    company_name="Acme Corp",
+    company_domain="acme.com",
+    company_employees=100
+)
+```
+
+### CrmAgentObservation
+
+Pydantic model for CRM observations.
+
+- `success` (bool): Whether the action succeeded
+- `error` (str | None): Error message if failed
+- `data` (dict): Raw response data
+- `done` (bool): Whether episode has ended
+- `reward` (float | None): Reward signal
+
+Use `observation.model_dump_json()` to get JSON representation.
+
+## Support
+
+For licensing, technical support, or questions:
+
+**Email:** hello@construct-labs.com
+
+## License
+
+Copyright (c) 2024 Construct Labs GmbH. All rights reserved.
+
+This software is proprietary and requires a commercial license.
+See [LICENSE](LICENSE) for details.