construct-labs-crm-env 0.1.1__tar.gz → 0.1.3__tar.gz

construct_labs_crm_env-0.1.3/.gitignore

@@ -0,0 +1,23 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Linting
+.ruff_cache/
+.mypy_cache/
+
+# Build
+dist/
+build/
+*.egg-info/
+
+# IDE
+.idea/
+.vscode/

construct_labs_crm_env-0.1.3/LICENSE

@@ -0,0 +1,56 @@
+Construct Labs CRM Environment SDK - Evaluation License
+
+Copyright (c) 2024 Construct Labs GmbH. All rights reserved.
+
+TERMS AND CONDITIONS
+
+1. EVALUATION LICENSE
+   This software and associated documentation files (the "Software") are
+   provided by Construct Labs GmbH for evaluation purposes only.
+
+   You may use this Software solely to evaluate its functionality and
+   suitability for your needs. This evaluation license does not grant
+   any rights to use the Software in production environments.
+
+2. RESTRICTIONS
+   Under this evaluation license, you may NOT:
+   - Deploy the Software in production environments
+   - Use the Software for commercial purposes
+   - Train models intended for production use
+   - Distribute, sublicense, or transfer the Software to third parties
+   - Remove or alter any proprietary notices
+
+3. COMMERCIAL LICENSE REQUIRED
+   Any use beyond evaluation requires a commercial license agreement
+   with Construct Labs GmbH. This includes but is not limited to:
+   - Production deployment
+   - Commercial use of any kind
+   - Training models for production use
+   - Integration into commercial products or services
+
+   To obtain a commercial license, contact:
+   
+   Construct Labs GmbH
+   Email: hello@construct-labs.com
+
+4. DATA AND PRIVACY
+   During evaluation, the Software may connect to Construct Labs servers.
+   Usage data may be collected for service improvement purposes.
+
+5. WARRANTY DISCLAIMER
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+6. LIMITATION OF LIABILITY
+   IN NO EVENT SHALL CONSTRUCT LABS GMBH BE LIABLE FOR ANY CLAIM, DAMAGES OR
+   OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+   ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+   DEALINGS IN THE SOFTWARE.
+
+7. TERMINATION
+   This evaluation license may be terminated by Construct Labs GmbH at any
+   time. Your rights under this license will terminate automatically without
+   notice if you fail to comply with any of its terms.
+
+For licensing inquiries: hello@construct-labs.com

{construct_labs_crm_env-0.1.1 → construct_labs_crm_env-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: construct-labs-crm-env
-Version: 0.1.1
+Version: 0.1.3
 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>
@@ -19,6 +19,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
+Requires-Dist: openenv-core>=0.2.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: websockets>=12.0
 Provides-Extra: dev

{construct_labs_crm_env-0.1.1 → construct_labs_crm_env-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "construct-labs-crm-env"
-version = "0.1.1"
+version = "0.1.3"
 description = "CRM Agent Environment SDK by Construct Labs - Train RL agents to interact with CRM systems"
 readme = "README.md"
 license = { text = "Proprietary" }
@@ -34,6 +34,7 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
+    "openenv-core>=0.2.0",
     "pydantic>=2.0.0",
     "websockets>=12.0",
 ]
@@ -88,7 +89,7 @@ warn_unused_ignores = true
 disallow_untyped_defs = true
 
 [[tool.mypy.overrides]]
-module = ["websockets.*"]
+module = ["websockets.*", "openenv.*"]
 ignore_missing_imports = true
 
 [tool.pytest.ini_options]

{construct_labs_crm_env-0.1.1 → construct_labs_crm_env-0.1.3}/src/construct_labs_crm_env/__init__.py

@@ -4,9 +4,11 @@ This package provides a Python client for interacting with the Construct Labs
 CRM Agent Environment - a reinforcement learning environment for training
 agents to interact with CRM systems.
 
-For more information, see https://docs.construct-labs.com/crm-agent
+For licensing and support, contact hello@construct-labs.com
 """
 
+from importlib.metadata import PackageNotFoundError, version
+
 from .client import CrmAgentEnv
 from .models import (
     CRMActionType,
@@ -16,7 +18,10 @@ from .models import (
 )
 from .protocol import ParsedAction
 
-__version__ = "0.1.0"
+try:
+    __version__ = version("construct-labs-crm-env")
+except PackageNotFoundError:
+    __version__ = "0.0.0+dev"
 
 __all__ = [
     # Main client

construct_labs_crm_env-0.1.3/src/construct_labs_crm_env/client.py

@@ -0,0 +1,515 @@
+"""CRM Agent Environment Client.
+
+This module provides the client for connecting to the Construct Labs CRM Agent
+Environment. The client handles authentication, WebSocket communication, and
+provides an extensible interface for customizing agent behavior.
+
+Example:
+    >>> from construct_labs_crm_env import CrmAgentEnv, CrmAgentAction, CRMActionType
+    >>>
+    >>> with CrmAgentEnv(
+    ...     base_url="https://api.construct-labs.com",
+    ...     api_key="your-api-key"
+    ... ) as env:
+    ...     result = env.reset()
+    ...     result = env.step(CrmAgentAction(
+    ...         action_type=CRMActionType.LIST_COMPANIES,
+    ...         limit=10
+    ...     ))
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, cast
+
+from openenv.core import EnvClient
+from openenv.core.client_types import StepResult
+from websockets.sync.client import connect as ws_connect
+
+from .models import (
+    CRMActionType,
+    CrmAgentAction,
+    CrmAgentObservation,
+    CrmAgentState,
+)
+from .protocol import ParsedAction
+from .tools import DEFAULT_TOOLS
+
+# Type alias for JSON-serializable dictionaries
+JsonDict = dict[str, Any]
+
+# Protocol version for API compatibility
+_PROTOCOL_VERSION = "v1"
+
+
+class CrmAgentEnv(EnvClient[CrmAgentAction, CrmAgentObservation, CrmAgentState]):
+    """Client for the Construct Labs CRM Agent Environment.
+
+    This client connects to the CRM environment server via WebSocket and
+    provides methods for interacting with CRM data. It supports customization
+    through subclassing - override `system_prompt`, `tools`, or
+    `format_observation` to customize agent behavior.
+
+    Args:
+        base_url: Base URL of the CRM environment server.
+        api_key: API key for authentication. Get one at https://construct-labs.com
+        connect_timeout_s: Timeout for establishing connection (default: 10s).
+        message_timeout_s: Timeout for receiving responses (default: 60s).
+
+    Example:
+        >>> # Basic usage
+        >>> with CrmAgentEnv(
+        ...     base_url="https://api.construct-labs.com",
+        ...     api_key="cl_live_xxx"
+        ... ) as env:
+        ...     result = env.reset()
+        ...     print(env.system_prompt)
+
+    Example (custom subclass):
+        >>> class SalesAgent(CrmAgentEnv):
+        ...     @property
+        ...     def system_prompt(self) -> str:
+        ...         return "You are a sales assistant..."
+        ...
+        ...     @property
+        ...     def tools(self) -> list[dict]:
+        ...         # Only expose company and opportunity tools
+        ...         return [t for t in self._default_tools()
+        ...                 if 'company' in t['function']['name']
+        ...                 or 'opportunity' in t['function']['name']]
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str | None = None,
+        connect_timeout_s: float = 10.0,
+        message_timeout_s: float = 60.0,
+    ) -> None:
+        """Initialize the CRM environment client.
+
+        Args:
+            base_url: Base URL of the CRM environment server.
+            api_key: API key for authentication. Can also be set via
+                CRM_AGENT_API_KEY environment variable.
+            connect_timeout_s: Timeout for establishing WebSocket connection.
+            message_timeout_s: Timeout for receiving responses.
+
+        Raises:
+            ValueError: If no API key is provided or found in environment.
+        """
+        # Resolve API key from parameter or environment
+        resolved_api_key = api_key or os.environ.get("CRM_AGENT_API_KEY")
+        if not resolved_api_key:
+            raise ValueError(
+                "API key is required. Pass api_key parameter or set "
+                "CRM_AGENT_API_KEY environment variable. "
+                "Contact hello@construct-labs.com to obtain an API key."
+            )
+
+        self._api_key = resolved_api_key
+
+        # Initialize parent class (but don't connect yet)
+        super().__init__(
+            base_url=base_url,
+            connect_timeout_s=connect_timeout_s,
+            message_timeout_s=message_timeout_s,
+        )
+
+    def connect(self) -> CrmAgentEnv:
+        """Establish authenticated WebSocket connection to the server.
+
+        The API key is transmitted via WebSocket subprotocol for secure
+        authentication during the handshake.
+
+        Returns:
+            self for method chaining.
+
+        Raises:
+            ConnectionError: If connection cannot be established or
+                authentication fails.
+        """
+        if self._ws is not None:
+            return self
+
+        # Bypass proxy for localhost connections
+        ws_url_lower = self._ws_url.lower()
+        is_localhost = "localhost" in ws_url_lower or "127.0.0.1" in ws_url_lower
+
+        old_no_proxy = os.environ.get("NO_PROXY")
+        if is_localhost:
+            current_no_proxy = old_no_proxy or ""
+            if "localhost" not in current_no_proxy.lower():
+                os.environ["NO_PROXY"] = (
+                    f"{current_no_proxy},localhost,127.0.0.1"
+                    if current_no_proxy
+                    else "localhost,127.0.0.1"
+                )
+
+        try:
+            # Authenticate via WebSocket subprotocol
+            # Format: crm-{version}.{api_key}
+            auth_subprotocol = f"crm-{_PROTOCOL_VERSION}.{self._api_key}"
+
+            self._ws = ws_connect(
+                self._ws_url,
+                open_timeout=self._connect_timeout,
+                subprotocols=[auth_subprotocol],
+            )
+        except Exception as e:
+            error_msg = str(e)
+            if "401" in error_msg or "403" in error_msg or "4001" in error_msg:
+                raise ConnectionError(
+                    "Authentication failed. Please verify your API key. "
+                    "Contact hello@construct-labs.com if you need assistance."
+                ) from e
+            raise ConnectionError(f"Failed to connect to {self._ws_url}: {e}") from e
+        finally:
+            # Restore original NO_PROXY value
+            if is_localhost:
+                if old_no_proxy is None:
+                    os.environ.pop("NO_PROXY", None)
+                else:
+                    os.environ["NO_PROXY"] = old_no_proxy
+
+        return self
+
+    def _step_payload(self, action: CrmAgentAction) -> JsonDict:
+        """Convert CrmAgentAction to JSON payload for step request."""
+        return action.model_dump()
+
+    def _parse_result(self, payload: JsonDict) -> StepResult[CrmAgentObservation]:
+        """Parse server response into StepResult."""
+        obs_data = payload.get("observation", {})
+        observation = CrmAgentObservation.model_validate(obs_data)
+
+        return StepResult(
+            observation=observation,
+            reward=payload.get("reward", observation.reward),
+            done=payload.get("done", observation.done),
+        )
+
+    def _parse_state(self, payload: JsonDict) -> CrmAgentState:
+        """Parse server response into CrmAgentState."""
+        return CrmAgentState.model_validate(payload)
+
+    # =========================================================================
+    # Extensible Properties - Override these in subclasses
+    # =========================================================================
+
+    @property
+    def system_prompt(self) -> str:
+        """System prompt for the CRM agent.
+
+        Override this property in a subclass to customize the agent's behavior
+        and instructions.
+
+        Returns:
+            The system prompt string to use for the agent.
+
+        Example:
+            >>> class CustomAgent(CrmAgentEnv):
+            ...     @property
+            ...     def system_prompt(self) -> str:
+            ...         return '''You are a data entry assistant.
+            ...         Focus on accuracy and completeness.'''
+        """
+        return self._default_system_prompt()
+
+    def _default_system_prompt(self) -> str:
+        """Return the default system prompt.
+
+        Subclasses can call this to get the default prompt and extend it.
+
+        Returns:
+            The default system prompt string.
+        """
+        return """You are a tool-using agent interacting with a CRM (Customer Relationship Management) system.
+
+GOAL: Complete CRM tasks by creating, updating, and managing business data.
+
+AVAILABLE OPERATIONS:
+- Companies: list, get, create, update, delete
+- People/Contacts: list, get, create, update, delete
+- Opportunities: list, get, create, update, delete
+- Notes: list, create (attach to companies, people, or opportunities)
+- Tasks: list, create, update, complete
+
+EXAMPLES:
+
+1. List companies:
+<tool_call>
+{"name": "list_companies", "arguments": {"limit": 10}}
+</tool_call>
+
+2. Create a company:
+<tool_call>
+{"name": "create_company", "arguments": {"company_name": "Acme Corp", "company_domain": "acme.com"}}
+</tool_call>
+
+3. Create a contact:
+<tool_call>
+{"name": "create_person", "arguments": {"person_first_name": "John", "person_last_name": "Doe", "person_email": "john@acme.com"}}
+</tool_call>
+
+4. Submit final answer:
+<tool_call>
+{"name": "submit_answer", "arguments": {"answer": "The total pipeline value is $1.5M"}}
+</tool_call>
+
+IMPORTANT: Output ONLY a tool_call, no other text."""
+
+    @property
+    def tools(self) -> list[JsonDict]:
+        """Tool definitions for the CRM environment.
+
+        Returns tool definitions formatted by `format_tools()`. Override
+        `format_tools()` to transform the tool schema for different providers
+        (e.g., Anthropic, Google).
+
+        Returns:
+            List of tool definitions (OpenAI format by default).
+
+        Example:
+            >>> class ReadOnlyAgent(CrmAgentEnv):
+            ...     @property
+            ...     def tools(self) -> list[dict]:
+            ...         # Only allow read operations
+            ...         read_ops = {'list_', 'get_', 'submit_answer'}
+            ...         return [t for t in self._default_tools()
+            ...                 if any(op in t['function']['name'] for op in read_ops)]
+        """
+        return self.format_tools(self._default_tools())
+
+    def format_tools(self, tools: list[JsonDict]) -> list[JsonDict]:
+        """Format tool definitions for the target LLM provider.
+
+        Override this method to transform tool schemas for different providers.
+        The default implementation returns OpenAI-compatible format unchanged.
+
+        Args:
+            tools: List of tool definitions in OpenAI format.
+
+        Returns:
+            Formatted tool definitions for your target provider.
+
+        Example (Anthropic format):
+            >>> class AnthropicCrmAgent(CrmAgentEnv):
+            ...     def format_tools(self, tools):
+            ...         # Convert OpenAI format to Anthropic format
+            ...         return [
+            ...             {
+            ...                 "name": t["function"]["name"],
+            ...                 "description": t["function"]["description"],
+            ...                 "input_schema": t["function"]["parameters"],
+            ...             }
+            ...             for t in tools
+            ...         ]
+        """
+        return tools
+
+    def _default_tools(self) -> list[JsonDict]:
+        """Return the default tool definitions.
+
+        Subclasses can call this to get all default tools and filter/extend them.
+
+        Returns:
+            Complete list of CRM tool definitions in OpenAI format.
+        """
+        return list(DEFAULT_TOOLS)
+
+    # =========================================================================
+    # Tool Parsing and Observation Formatting
+    # =========================================================================
+
+    def parse_tool_call(self, tool_call: JsonDict) -> ParsedAction:
+        """Parse a tool call from the LLM into a CrmAgentAction.
+
+        This method maps tool names to action types and extracts arguments.
+        Override this in a subclass to handle custom tools.
+
+        Args:
+            tool_call: Dictionary with 'name' and 'arguments' from LLM output.
+
+        Returns:
+            ParsedAction with the action and validity status.
+        """
+        tool_name = str(tool_call.get("name", "")).lower().strip()
+        arguments_raw = tool_call.get("arguments")
+
+        # Parse arguments
+        if isinstance(arguments_raw, dict):
+            arguments = cast(JsonDict, arguments_raw)
+        elif isinstance(arguments_raw, str):
+            try:
+                arguments = json.loads(arguments_raw)
+            except json.JSONDecodeError:
+                return ParsedAction(
+                    action=None,
+                    is_valid=False,
+                    error_message=f"Invalid JSON in arguments: {arguments_raw}",
+                )
+        else:
+            return ParsedAction(
+                action=None,
+                is_valid=False,
+                error_message=f"Arguments must be dict or JSON string, got: {type(arguments_raw)}",
+            )
+
+        # Map tool names to action types
+        tool_to_action_type: dict[str, CRMActionType] = {
+            # Company
+            "list_companies": CRMActionType.LIST_COMPANIES,
+            "get_company": CRMActionType.GET_COMPANY,
+            "create_company": CRMActionType.CREATE_COMPANY,
+            "update_company": CRMActionType.UPDATE_COMPANY,
+            "delete_company": CRMActionType.DELETE_COMPANY,
+            # Person
+            "list_people": CRMActionType.LIST_PEOPLE,
+            "get_person": CRMActionType.GET_PERSON,
+            "create_person": CRMActionType.CREATE_PERSON,
+            "update_person": CRMActionType.UPDATE_PERSON,
+            "delete_person": CRMActionType.DELETE_PERSON,
+            # Opportunity
+            "list_opportunities": CRMActionType.LIST_OPPORTUNITIES,
+            "get_opportunity": CRMActionType.GET_OPPORTUNITY,
+            "create_opportunity": CRMActionType.CREATE_OPPORTUNITY,
+            "update_opportunity": CRMActionType.UPDATE_OPPORTUNITY,
+            "delete_opportunity": CRMActionType.DELETE_OPPORTUNITY,
+            # Note
+            "list_notes": CRMActionType.LIST_NOTES,
+            "create_note": CRMActionType.CREATE_NOTE,
+            # Task
+            "list_tasks": CRMActionType.LIST_TASKS,
+            "create_task": CRMActionType.CREATE_TASK,
+            "update_task": CRMActionType.UPDATE_TASK,
+            "complete_task": CRMActionType.COMPLETE_TASK,
+            # Answer
+            "submit_answer": CRMActionType.SUBMIT_ANSWER,
+        }
+
+        if not tool_name:
+            return ParsedAction(
+                action=None,
+                is_valid=False,
+                error_message="Tool name is required",
+            )
+
+        action_type = tool_to_action_type.get(tool_name)
+        if action_type is None:
+            return ParsedAction(
+                action=None,
+                is_valid=False,
+                error_message=f"Unknown tool: '{tool_name}'. "
+                f"Valid tools: {list(tool_to_action_type.keys())}",
+            )
+
+        # Build action with all valid fields
+        action_kwargs: JsonDict = {"action_type": action_type}
+
+        valid_fields = {
+            "record_id",
+            "company_name",
+            "company_domain",
+            "company_address",
+            "company_employees",
+            "person_first_name",
+            "person_last_name",
+            "person_email",
+            "person_phone",
+            "person_company_id",
+            "person_job_title",
+            "opportunity_name",
+            "opportunity_amount",
+            "opportunity_stage",
+            "opportunity_close_date",
+            "opportunity_company_id",
+            "opportunity_person_id",
+            "note_body",
+            "note_target_id",
+            "note_target_type",
+            "task_title",
+            "task_body",
+            "task_due_date",
+            "task_assignee_id",
+            "task_status",
+            "task_target_id",
+            "task_target_type",
+            "limit",
+            "cursor",
+            "starting_after",
+            "ending_before",
+            "order_by",
+            "filter",
+            "depth",
+            "answer",
+        }
+
+        for field in valid_fields:
+            if field in arguments and arguments[field] is not None:
+                action_kwargs[field] = arguments[field]
+
+        # Convert generic note_target_id/type to specific fields
+        # Tool schema uses: note_target_id + note_target_type
+        # Server expects: note_target_person_id, note_target_company_id, etc.
+        note_target_id = action_kwargs.pop("note_target_id", None)
+        note_target_type = action_kwargs.pop("note_target_type", None)
+        if note_target_id and note_target_type:
+            target_type = str(note_target_type).lower()
+            if target_type == "person":
+                action_kwargs["note_target_person_id"] = note_target_id
+            elif target_type == "company":
+                action_kwargs["note_target_company_id"] = note_target_id
+            elif target_type == "opportunity":
+                action_kwargs["note_target_opportunity_id"] = note_target_id
+
+        # Same conversion for tasks
+        task_target_id = action_kwargs.pop("task_target_id", None)
+        task_target_type = action_kwargs.pop("task_target_type", None)
+        if task_target_id and task_target_type:
+            target_type = str(task_target_type).lower()
+            if target_type == "person":
+                action_kwargs["task_target_person_id"] = task_target_id
+            elif target_type == "company":
+                action_kwargs["task_target_company_id"] = task_target_id
+            elif target_type == "opportunity":
+                action_kwargs["task_target_opportunity_id"] = task_target_id
+
+        try:
+            action = CrmAgentAction(**action_kwargs)
+            return ParsedAction(action=action, is_valid=True)
+        except Exception as e:
+            return ParsedAction(
+                action=None,
+                is_valid=False,
+                error_message=f"Failed to create action: {e}",
+            )
+
+    def format_observation(self, observation: CrmAgentObservation) -> str:
+        """Format an observation as a string for the LLM.
+
+        Override this in a subclass to customize how observations are
+        presented to the agent.
+
+        Args:
+            observation: The observation to format.
+
+        Returns:
+            String representation for the LLM.
+
+        Example:
+            >>> class VerboseAgent(CrmAgentEnv):
+            ...     def format_observation(self, obs):
+            ...         base = super().format_observation(obs)
+            ...         return f"=== CRM Response ===\\n{base}\\n=== End ==="
+        """
+        import json
+
+        lines: list[str] = [json.dumps(observation.data)]
+
+        if observation.error:
+            lines.append(f"Error: {observation.error}")
+
+        return "\n".join(lines)

{construct_labs_crm_env-0.1.1 → construct_labs_crm_env-0.1.3}/src/construct_labs_crm_env/models.py

@@ -9,10 +9,9 @@ from __future__ import annotations
 from enum import Enum
 from typing import Any
 
+from openenv.core import Action, Observation, State
 from pydantic import ConfigDict, Field
 
-from ._vendored import Action, Observation, State
-
 
 class CRMActionType(str, Enum):
     """Types of actions available in the CRM environment.