salesforce-agent 0.2.0__py3-none-any.whl

salesforce_agent/__init__.py

@@ -0,0 +1,69 @@
+"""CONCEPT:ECO-4.0 Unified ecosystem initialization dynamic check."""
+
+import importlib
+import inspect
+from typing import Any
+
+__version__ = "0.2.0"
+__all__: list[str] = []
+
+CORE_MODULES = [
+    "salesforce_agent.salesforce_response_models",
+    "salesforce_agent.salesforce_input_models",
+    "salesforce_agent.auth",
+    "salesforce_agent.api_client",
+]
+OPTIONAL_MODULES = {
+    "salesforce_agent.agent_server": "agent",
+    "salesforce_agent.mcp_server": "mcp",
+}
+
+
+def _expose_members(module):
+    for name, obj in inspect.getmembers(module):
+        if (inspect.isclass(obj) or inspect.isfunction(obj)) and not name.startswith(
+            "_"
+        ):
+            globals()[name] = obj
+            if name not in __all__:
+                __all__.append(name)
+
+
+for module_name in CORE_MODULES:
+    module = importlib.import_module(module_name)
+    _expose_members(module)
+
+_loaded_optional_modules: dict[str, Any] = {}
+
+
+def _import_module_safely(module_name: str):
+    try:
+        return importlib.import_module(module_name)
+    except ImportError:
+        return None
+
+
+def __getattr__(name: str) -> Any:
+    if name == "_MCP_AVAILABLE":
+        mcp_key = next((k for k in OPTIONAL_MODULES if "mcp_server" in k), None)
+        return _import_module_safely(mcp_key) is not None if mcp_key else False
+    if name == "_AGENT_AVAILABLE":
+        agent_key = next((k for k in OPTIONAL_MODULES if "agent_server" in k), None)
+        return _import_module_safely(agent_key) is not None if agent_key else False
+
+    for module_name in OPTIONAL_MODULES:
+        if module_name not in _loaded_optional_modules:
+            module = _import_module_safely(module_name)
+            if module is not None:
+                _loaded_optional_modules[module_name] = module
+                _expose_members(module)
+
+        module = _loaded_optional_modules.get(module_name)
+        if module is not None and hasattr(module, name):
+            return getattr(module, name)
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    return sorted(list(globals().keys()) + __all__)

salesforce_agent/__main__.py

@@ -0,0 +1,4 @@
+from salesforce_agent.agent_server import agent_server
+
+if __name__ == "__main__":
+    agent_server()

salesforce_agent/agent_server.py

@@ -0,0 +1,77 @@
+"""Pydantic AI A2A agent server for the Salesforce connector."""
+
+import logging
+import os
+import sys
+import warnings
+
+__version__ = "0.2.0"
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+DEFAULT_AGENT_NAME = None
+DEFAULT_AGENT_DESCRIPTION = None
+DEFAULT_AGENT_SYSTEM_PROMPT = None
+
+
+def agent_server():
+    """Start graph-based Pydantic AI agent server."""
+    from agent_utilities import (
+        build_system_prompt_from_workspace,
+        create_agent_parser,
+        create_agent_server,
+        initialize_workspace,
+        load_identity,
+    )
+
+    global DEFAULT_AGENT_NAME, DEFAULT_AGENT_DESCRIPTION, DEFAULT_AGENT_SYSTEM_PROMPT
+    initialize_workspace()
+    meta = load_identity()
+    DEFAULT_AGENT_NAME = os.getenv(
+        "DEFAULT_AGENT_NAME", meta.get("name", "Salesforce Agent")
+    )
+    DEFAULT_AGENT_DESCRIPTION = os.getenv(
+        "AGENT_DESCRIPTION",
+        meta.get("description", "AI agent for Salesforce CRM operations."),
+    )
+    DEFAULT_AGENT_SYSTEM_PROMPT = os.getenv(
+        "AGENT_SYSTEM_PROMPT",
+        meta.get("content") or build_system_prompt_from_workspace(),
+    )
+
+    warnings.filterwarnings("ignore", message=".*urllib3.*")
+    warnings.filterwarnings("ignore", category=DeprecationWarning, module="fastmcp")
+
+    print(f"{DEFAULT_AGENT_NAME} v{__version__}", file=sys.stderr)
+    parser = create_agent_parser()
+    args = parser.parse_args()
+
+    create_agent_server(
+        mcp_url=args.mcp_url,
+        mcp_config=args.mcp_config or "mcp_config.json",
+        host=args.host,
+        port=args.port,
+        provider=args.provider,
+        model_id=args.model_id,
+        router_model=args.model_id,
+        agent_model=args.model_id,
+        base_url=args.base_url,
+        api_key=args.api_key,
+        custom_skills_directory=args.custom_skills_directory,
+        enable_web_ui=args.web,
+        enable_otel=args.otel,
+        otel_endpoint=args.otel_endpoint,
+        otel_headers=args.otel_headers,
+        otel_public_key=args.otel_public_key,
+        otel_secret_key=args.otel_secret_key,
+        otel_protocol=args.otel_protocol,
+        debug=args.debug,
+    )
+
+
+if __name__ == "__main__":
+    agent_server()

salesforce_agent/api/__init__.py

@@ -0,0 +1,17 @@
+"""Salesforce REST API resource clients (owned thin httpx wrappers)."""
+
+from salesforce_agent.api.api_client_admin import AdminClient
+from salesforce_agent.api.api_client_base import ApiClientBase
+from salesforce_agent.api.api_client_bulk import BulkClient
+from salesforce_agent.api.api_client_describe import DescribeClient
+from salesforce_agent.api.api_client_query import QueryClient
+from salesforce_agent.api.api_client_records import RecordsClient
+
+__all__ = [
+    "AdminClient",
+    "ApiClientBase",
+    "BulkClient",
+    "DescribeClient",
+    "QueryClient",
+    "RecordsClient",
+]

salesforce_agent/api/api_client_admin.py

@@ -0,0 +1,58 @@
+"""CONCEPT:SFDC-1.2 Org administration: identity, org info, and analytics.
+
+Resources:
+- UserInfo (OIDC): https://help.salesforce.com/s/articleView?id=sf.remoteaccess_using_userinfo_endpoint.htm
+- Reports REST:    https://developer.salesforce.com/docs/atlas.en-us.api_analytics.meta/api_analytics/sforce_analytics_rest_api_intro.htm
+
+Flows (list/run via the Actions or Tooling APIs) are intentionally OUT of
+scope for v1 of this connector — running flows mutates org state through an
+API surface with weaker guardrails; revisit behind ``allow_destructive``.
+"""
+
+from typing import Any
+
+from salesforce_agent.api.api_client_base import ApiClientBase
+
+ORG_INFO_SOQL = (
+    "SELECT Id, Name, OrganizationType, IsSandbox, InstanceName, "
+    "LanguageLocaleKey, TrialExpirationDate FROM Organization"
+)
+
+
+class AdminClient:
+    """Current user/org identity plus the synchronous Reports REST surface."""
+
+    def __init__(self, base: ApiClientBase):
+        self._client = base
+
+    def user_info(self) -> dict[str, Any]:
+        """Identity of the integration user (``/services/oauth2/userinfo``)."""
+        return self._client.request("GET", "/services/oauth2/userinfo")
+
+    def org_info(self) -> dict[str, Any]:
+        """Organization record (name, type, sandbox flag, instance)."""
+        return self._client.request(
+            "GET",
+            f"{self._client.data_base}/query",
+            params={"q": ORG_INFO_SOQL},
+        )
+
+    def list_reports(self) -> Any:
+        """Recently viewed reports (``/analytics/reports`` list resource)."""
+        return self._client.request(
+            "GET", f"{self._client.data_base}/analytics/reports"
+        )
+
+    def run_report(
+        self, report_id: str, include_details: bool = True
+    ) -> dict[str, Any]:
+        """Run a report synchronously.
+
+        Salesforce caps synchronous report results at 2,000 detail rows —
+        results beyond the cap are dropped by the platform, not paged.
+        """
+        return self._client.request(
+            "GET",
+            f"{self._client.data_base}/analytics/reports/{report_id}",
+            params={"includeDetails": str(include_details).lower()},
+        )

salesforce_agent/api/api_client_base.py

@@ -0,0 +1,119 @@
+"""CONCEPT:SFDC-1.0 Shared httpx base client for the Salesforce REST API.
+
+Owned thin client (no ``simple-salesforce``): a single httpx.Client that
+attaches the cached bearer token, maps failures to typed errors
+(:mod:`salesforce_agent.salesforce_response_models`), retries exactly once on 401 after
+invalidating the token cache, and redacts secrets from anything it raises.
+
+REST API reference:
+https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/intro_rest.htm
+"""
+
+from typing import Any
+
+import httpx
+
+from salesforce_agent.auth import SalesforceAuth
+from salesforce_agent.salesforce_response_models import map_response_error
+
+
+class ApiClientBase:
+    """Token-aware request runner shared by every resource client."""
+
+    def __init__(
+        self,
+        auth: SalesforceAuth,
+        transport: httpx.BaseTransport | None = None,
+    ):
+        self.auth = auth
+        self._http = httpx.Client(
+            timeout=auth.config.timeout,
+            verify=auth.config.verify,
+            transport=transport,
+            follow_redirects=True,
+        )
+
+    @property
+    def data_base(self) -> str:
+        """Versioned REST root, e.g. ``/services/data/v62.0``."""
+        return f"/services/data/{self.auth.config.api_version}"
+
+    def request_raw(
+        self,
+        method: str,
+        endpoint: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: Any | None = None,
+        content: str | bytes | None = None,
+        headers: dict[str, str] | None = None,
+        _retried: bool = False,
+    ) -> httpx.Response:
+        """Run one authenticated request and return the raw response.
+
+        ``endpoint`` is joined onto the org's instance URL unless it is
+        already absolute. A 401 invalidates the token cache and retries once
+        (refresh-on-401); any remaining HTTP >= 400 raises a typed
+        :class:`~salesforce_agent.salesforce_response_models.SalesforceError` with secrets
+        redacted from the message.
+        """
+        token, instance_url = self.auth.token()
+        url = endpoint if endpoint.startswith("http") else f"{instance_url}{endpoint}"
+        request_headers = {"Authorization": f"Bearer {token}"}
+        if headers:
+            request_headers.update(headers)
+
+        response = self._http.request(
+            method=method,
+            url=url,
+            params=params,
+            json=json,
+            content=content,
+            headers=request_headers,
+        )
+
+        if response.status_code == 401 and not _retried and self.auth.can_refresh:
+            self.auth.invalidate()
+            return self.request_raw(
+                method,
+                endpoint,
+                params=params,
+                json=json,
+                content=content,
+                headers=headers,
+                _retried=True,
+            )
+
+        if response.status_code >= 400:
+            raise map_response_error(
+                response.status_code, response.text, redact=self.auth.redact
+            )
+        return response
+
+    def request(
+        self,
+        method: str,
+        endpoint: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: Any | None = None,
+        content: str | bytes | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> Any:
+        """Run a request and return parsed JSON (or a success/text envelope)."""
+        response = self.request_raw(
+            method,
+            endpoint,
+            params=params,
+            json=json,
+            content=content,
+            headers=headers,
+        )
+        if response.status_code == 204 or not response.text.strip():
+            return {"success": True, "status_code": response.status_code}
+        if "json" in response.headers.get("content-type", ""):
+            return response.json()
+        return {"status_code": response.status_code, "text": response.text}
+
+    def close(self) -> None:
+        self._http.close()

salesforce_agent/api/api_client_bulk.py

@@ -0,0 +1,145 @@
+"""CONCEPT:SFDC-1.4 Bulk API 2.0 ingest job client (CSV in, CSV results out).
+
+Resources (Bulk API 2.0 developer guide):
+- Create job:   https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/create_job.htm
+- Upload data:  https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/upload_job_data.htm
+- Close/abort:  https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/close_job.htm
+- Job info:     https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/get_job_info.htm
+- Results:      https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/get_job_successful_results.htm
+
+CONCEPT:SFDC-1.3 — ``delete``/``hardDelete`` ingest jobs are gated by
+``allow_destructive``; result downloads are size-capped
+(``SALESFORCE_BULK_RESULTS_MAX_BYTES``).
+"""
+
+from typing import Any
+
+from salesforce_agent.api.api_client_base import ApiClientBase
+from salesforce_agent.salesforce_response_models import (
+    DestructiveOperationBlockedError,
+    SalesforceBadRequestError,
+)
+
+INGEST_OPERATIONS = {"insert", "update", "upsert", "delete", "hardDelete"}
+DESTRUCTIVE_OPERATIONS = {"delete", "hardDelete"}
+RESULT_KINDS = {
+    "successful": "successfulResults",
+    "failed": "failedResults",
+    "unprocessed": "unprocessedrecords",
+}
+
+
+class BulkClient:
+    """Bulk API 2.0 ingest job lifecycle: create → upload → close → results."""
+
+    def __init__(self, base: ApiClientBase):
+        self._client = base
+
+    @property
+    def _jobs_base(self) -> str:
+        return f"{self._client.data_base}/jobs/ingest"
+
+    def create_ingest_job(
+        self,
+        sobject: str,
+        operation: str,
+        external_id_field: str | None = None,
+        line_ending: str = "LF",
+        column_delimiter: str = "COMMA",
+    ) -> dict[str, Any]:
+        """Create an ingest job (insert/update/upsert/delete/hardDelete).
+
+        ``upsert`` requires ``external_id_field``. Delete operations are
+        gated by ``allow_destructive``.
+        """
+        if operation not in INGEST_OPERATIONS:
+            raise SalesforceBadRequestError(
+                f"Unknown bulk operation {operation!r}; "
+                f"expected one of {sorted(INGEST_OPERATIONS)}."
+            )
+        if operation in DESTRUCTIVE_OPERATIONS:
+            if not self._client.auth.config.allow_destructive:
+                raise DestructiveOperationBlockedError(f"bulk.{operation}")
+        if operation == "upsert" and not external_id_field:
+            raise SalesforceBadRequestError("Bulk upsert requires external_id_field.")
+        body: dict[str, Any] = {
+            "object": sobject,
+            "operation": operation,
+            "contentType": "CSV",
+            "lineEnding": line_ending,
+            "columnDelimiter": column_delimiter,
+        }
+        if external_id_field:
+            body["externalIdFieldName"] = external_id_field
+        return self._client.request("POST", self._jobs_base, json=body)
+
+    def upload(self, job_id: str, csv_data: str | bytes) -> dict[str, Any]:
+        """Upload the job's CSV payload (``PUT .../batches``, text/csv)."""
+        return self._client.request(
+            "PUT",
+            f"{self._jobs_base}/{job_id}/batches",
+            content=csv_data,
+            headers={"Content-Type": "text/csv", "Accept": "application/json"},
+        )
+
+    def close(self, job_id: str) -> dict[str, Any]:
+        """Mark upload complete so Salesforce starts processing the job."""
+        return self._client.request(
+            "PATCH", f"{self._jobs_base}/{job_id}", json={"state": "UploadComplete"}
+        )
+
+    def abort(self, job_id: str) -> dict[str, Any]:
+        """Abort a job that has not finished processing."""
+        return self._client.request(
+            "PATCH", f"{self._jobs_base}/{job_id}", json={"state": "Aborted"}
+        )
+
+    def status(self, job_id: str) -> dict[str, Any]:
+        """Job info: state, counts of processed/failed records, timing."""
+        return self._client.request("GET", f"{self._jobs_base}/{job_id}")
+
+    def list_jobs(self) -> dict[str, Any]:
+        """List ingest jobs (most recent first, paged by Salesforce)."""
+        return self._client.request("GET", self._jobs_base)
+
+    def delete_job(self, job_id: str) -> dict[str, Any]:
+        """Delete the job *metadata* (not org data) once it is terminal."""
+        return self._client.request("DELETE", f"{self._jobs_base}/{job_id}")
+
+    def results(
+        self,
+        job_id: str,
+        kind: str = "successful",
+        locator: str | None = None,
+        max_bytes: int | None = None,
+    ) -> dict[str, Any]:
+        """Download job results CSV (successful / failed / unprocessed).
+
+        The body is capped at ``max_bytes`` (default
+        ``SALESFORCE_BULK_RESULTS_MAX_BYTES``); a truncated download is
+        flagged and carries the ``Sforce-Locator`` header so the caller can
+        page through the remainder.
+        """
+        if kind not in RESULT_KINDS:
+            raise SalesforceBadRequestError(
+                f"Unknown result kind {kind!r}; expected one of {sorted(RESULT_KINDS)}."
+            )
+        cap = max_bytes or self._client.auth.config.bulk_results_max_bytes
+        params = {"locator": locator} if locator else None
+        response = self._client.request_raw(
+            "GET",
+            f"{self._jobs_base}/{job_id}/{RESULT_KINDS[kind]}",
+            params=params,
+            headers={"Accept": "text/csv"},
+        )
+        body = response.content
+        truncated = len(body) > cap
+        return {
+            "job_id": job_id,
+            "kind": kind,
+            "content": body[:cap].decode("utf-8", errors="replace"),
+            "bytes": min(len(body), cap),
+            "truncated": truncated,
+            "locator": response.headers.get("Sforce-Locator"),
+            "number_of_records": response.headers.get("Sforce-NumberOfRecords"),
+        }

salesforce_agent/api/api_client_describe.py

@@ -0,0 +1,40 @@
+"""CONCEPT:SFDC-1.2 Metadata describe, record counts, and org limits client.
+
+Resources:
+- Describe Global:  https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_describeGlobal.htm
+- sObject Describe: https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_sobject_describe.htm
+- Record Count:     https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_record_count.htm
+- Limits:           https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_limits.htm
+"""
+
+from typing import Any
+
+from salesforce_agent.api.api_client_base import ApiClientBase
+
+
+class DescribeClient:
+    """Schema discovery: object lists, field/relationship/picklist metadata."""
+
+    def __init__(self, base: ApiClientBase):
+        self._client = base
+
+    def global_describe(self) -> dict[str, Any]:
+        """List every sObject available to the integration user."""
+        return self._client.request("GET", f"{self._client.data_base}/sobjects")
+
+    def sobject(self, name: str) -> dict[str, Any]:
+        """Full describe of one sObject — fields, relationships, picklists."""
+        return self._client.request(
+            "GET", f"{self._client.data_base}/sobjects/{name}/describe"
+        )
+
+    def record_counts(self, sobjects: list[str] | None = None) -> dict[str, Any]:
+        """Approximate record counts, optionally for selected sObjects."""
+        params = {"sObjects": ",".join(sobjects)} if sobjects else None
+        return self._client.request(
+            "GET", f"{self._client.data_base}/limits/recordCount", params=params
+        )
+
+    def limits(self) -> dict[str, Any]:
+        """Org limits and current API usage (DailyApiRequests etc.)."""
+        return self._client.request("GET", f"{self._client.data_base}/limits")

salesforce_agent/api/api_client_query.py

@@ -0,0 +1,68 @@
+"""CONCEPT:SFDC-1.2 SOQL / SOSL query client with auto-pagination.
+
+Resources:
+- Query:    https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_query.htm
+- QueryAll: https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_queryall.htm
+- Explain:  https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_query_explain.htm
+- Search:   https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_search.htm
+"""
+
+from typing import Any
+
+from salesforce_agent.api.api_client_base import ApiClientBase
+
+
+class QueryClient:
+    """SOQL queries (with ``nextRecordsUrl`` pagination) and SOSL search."""
+
+    def __init__(self, base: ApiClientBase):
+        self._client = base
+
+    def query(
+        self,
+        soql: str,
+        *,
+        query_all: bool = False,
+        max_records: int | None = None,
+    ) -> dict[str, Any]:
+        """Run a SOQL query, following ``nextRecordsUrl`` pages up to a cap.
+
+        ``query_all=True`` uses the ``queryAll`` resource, which includes
+        soft-deleted and archived rows. ``max_records`` caps the records
+        gathered per call (default: ``SALESFORCE_MAX_QUERY_RECORDS``); when
+        the cap stops pagination early the result is flagged ``truncated``
+        and carries the unfollowed ``nextRecordsUrl``.
+        """
+        cap = max_records or self._client.auth.config.max_query_records
+        resource = "queryAll" if query_all else "query"
+        page = self._client.request(
+            "GET", f"{self._client.data_base}/{resource}", params={"q": soql}
+        )
+        records: list[dict[str, Any]] = list(page.get("records", []))
+        while not page.get("done", True) and len(records) < cap:
+            page = self._client.request("GET", page["nextRecordsUrl"])
+            records.extend(page.get("records", []))
+
+        truncated = len(records) > cap or not page.get("done", True)
+        return {
+            "totalSize": page.get("totalSize", len(records)),
+            "done": page.get("done", True),
+            "records": records[:cap],
+            "returned": min(len(records), cap),
+            "truncated": truncated,
+            "nextRecordsUrl": None
+            if page.get("done", True)
+            else page.get("nextRecordsUrl"),
+        }
+
+    def explain(self, soql: str) -> dict[str, Any]:
+        """Return the query plan for a SOQL statement (``?explain=``)."""
+        return self._client.request(
+            "GET", f"{self._client.data_base}/query/", params={"explain": soql}
+        )
+
+    def search(self, sosl: str) -> dict[str, Any]:
+        """Run a SOSL full-text search (``/search/?q=FIND {...}``)."""
+        return self._client.request(
+            "GET", f"{self._client.data_base}/search/", params={"q": sosl}
+        )