diff --git a/README.md b/README.md index 2223375..d697e25 100644 --- a/README.md +++ b/README.md @@ -4,244 +4,91 @@ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Python Versions](https://img.shields.io/pypi/pyversions/langchain-salesforce.svg)](https://pypi.org/project/langchain-salesforce/) [![CI](https://github.com/colesmcintosh/langchain-salesforce/actions/workflows/ci.yml/badge.svg)](https://github.com/colesmcintosh/langchain-salesforce/actions/workflows/ci.yml) -[![Code Quality](https://github.com/colesmcintosh/langchain-salesforce/actions/workflows/pr-checks.yml/badge.svg)](https://github.com/colesmcintosh/langchain-salesforce/actions/workflows/pr-checks.yml) -The `langchain-salesforce` package provides a seamless integration between LangChain and Salesforce CRM, enabling developers to leverage LangChain's powerful framework to interact with Salesforce data. - -## Overview - -This package allows you to connect to your Salesforce instance and perform various operations, such as querying data with SOQL, inspecting object schemas, and managing records (Create, Read, Update, Delete - CRUD). It is designed to be a flexible tool within the LangChain ecosystem. - -## Key Features - -- **Salesforce CRM Integration**: Connect LangChain applications directly to Salesforce. -- **SOQL Execution**: Run Salesforce Object Query Language (SOQL) queries. -- **Schema Inspection**: Describe Salesforce object structures. -- **Object Listing**: List all available SObjects in your Salesforce org. -- **CRUD Operations**: Create, update, and delete Salesforce records. -- **Environment Variable Configuration**: Easy setup using standard environment variables. -- **Comprehensive Error Handling**: Robust error management for Salesforce API interactions. +LangChain integration for Salesforce CRM. Query data with SOQL, inspect schemas, and manage records (CRUD) directly from your LangChain applications. ## Installation -To install the package, run the following command: - ```bash pip install -U langchain-salesforce ``` ## Configuration -Before using the tool, configure your Salesforce credentials by setting the following environment variables: +Set these environment variables: -- `SALESFORCE_USERNAME`: Your Salesforce username. -- `SALESFORCE_PASSWORD`: Your Salesforce password. -- `SALESFORCE_SECURITY_TOKEN`: Your Salesforce security token. -- `SALESFORCE_DOMAIN`: Your Salesforce domain (e.g., "login" for production, "test" for sandbox environments). Defaults to "login". +| Variable | Description | +|----------|-------------| +| `SALESFORCE_USERNAME` | Your Salesforce username | +| `SALESFORCE_PASSWORD` | Your Salesforce password | +| `SALESFORCE_SECURITY_TOKEN` | Your Salesforce security token | +| `SALESFORCE_DOMAIN` | `login` (production) or `test` (sandbox). Default: `login` | ## Quick Start -Here's a quick example of how to initialize the `SalesforceTool` and query for contacts: - ```python from langchain_salesforce import SalesforceTool -import os - -# Initialize the tool (credentials can also be sourced from environment variables) -tool = SalesforceTool( - username=os.getenv("SALESFORCE_USERNAME", "your-username"), - password=os.getenv("SALESFORCE_PASSWORD", "your-password"), - security_token=os.getenv("SALESFORCE_SECURITY_TOKEN", "your-token"), - domain=os.getenv("SALESFORCE_DOMAIN", "login") -) - -# Example: Query for the first 5 contacts -query_result = tool.run({ - "operation": "query", - "query": "SELECT Id, Name, Email FROM Contact LIMIT 5" -}) - -print(query_result) -``` - -## `SalesforceTool` Usage - -The `SalesforceTool` is the primary interface for interacting with Salesforce. It accepts a dictionary input specifying the `operation` and its required parameters. - -### Supported Operations -#### 1. Query Data (`query`) -Execute SOQL queries to retrieve data from Salesforce. +tool = SalesforceTool() -```python +# Query contacts result = tool.run({ "operation": "query", - "query": "SELECT Id, Name, Industry FROM Account WHERE Industry = 'Technology' LIMIT 10" + "query": "SELECT Id, Name, Email FROM Contact LIMIT 5" }) -print(result) ``` -#### 2. Describe Object Schema (`describe`) -Get the schema information for a specific Salesforce object. +## Operations -```python -schema = tool.run({ - "operation": "describe", - "object_name": "Account" -}) -print(schema) -``` +| Operation | Description | Required Parameters | +|-----------|-------------|---------------------| +| `query` | Execute SOQL queries | `query` | +| `describe` | Get object schema | `object_name` | +| `list_objects` | List all SObjects | — | +| `create` | Create a record | `object_name`, `record_data` | +| `update` | Update a record | `object_name`, `record_id`, `record_data` | +| `delete` | Delete a record | `object_name`, `record_id` | +| `get_field_metadata` | Get field details | `object_name`, `field_name` | -#### 3. List Available Objects (`list_objects`) -Retrieve a list of all available SObjects in your Salesforce organization. +### Examples ```python -available_objects = tool.run({ - "operation": "list_objects" -}) -print(available_objects) -``` +# Describe an object +tool.run({"operation": "describe", "object_name": "Account"}) -#### 4. Create New Record (`create`) -Create a new record for a specified Salesforce object. - -```python -new_contact_details = tool.run({ +# Create a record +tool.run({ "operation": "create", "object_name": "Contact", - "record_data": { - "LastName": "Doe", - "FirstName": "John", - "Email": "john.doe@example.com", - "Phone": "123-456-7890" - } + "record_data": {"LastName": "Doe", "Email": "doe@example.com"} }) -print(new_contact_details) # Returns ID of the new record and success status -``` - -#### 5. Update Existing Record (`update`) -Update fields on an existing Salesforce record. -```python -update_status = tool.run({ +# Update a record +tool.run({ "operation": "update", "object_name": "Contact", - "record_id": "003XXXXXXXXXXXXXXX", # Replace with an actual Contact ID - "record_data": { - "Email": "john.doe.updated@example.com", - "Description": "Updated contact information." - } -}) -print(update_status) # Returns ID of the updated record and success status -``` - -#### 6. Delete Record (`delete`) -Delete a Salesforce record by its ID. - -```python -delete_confirmation = tool.run({ - "operation": "delete", - "object_name": "Contact", - "record_id": "003YYYYYYYYYYYYYYY" # Replace with an actual Contact ID + "record_id": "003XXXXXXXXXXXXXXX", + "record_data": {"Email": "updated@example.com"} }) -print(delete_confirmation) # Returns ID of the deleted record and success status -``` - -#### 7. Get Field Metadata (`get_field_metadata`) -Get detailed metadata for a specific field on a Salesforce object. -```python -field_metadata = tool.run({ - "operation": "get_field_metadata", - "object_name": "Contact", - "field_name": "Email" -}) -print(field_metadata) # Returns detailed field information including type, length, constraints, etc. +# Delete a record +tool.run({"operation": "delete", "object_name": "Contact", "record_id": "003XXXXXXXXXXXXXXX"}) ``` -The field metadata includes comprehensive information such as: -- **Field type** (string, email, number, picklist, etc.) -- **Length and precision** for text and numeric fields -- **Labels and help text** -- **Validation rules** (required, unique, etc.) -- **Picklist values** for picklist fields -- **many more details...** - ## Development -Interested in contributing? Follow these steps to set up your development environment: - -1. **Clone the repository:** - ```bash - git clone https://github.com/YOUR_USERNAME/YOUR_REPOSITORY.git # Replace with your repository URL - cd langchain-salesforce - ``` - -2. **Install dependencies:** - This project uses [uv](https://docs.astral.sh/uv/) for dependency management. - ```bash - uv sync --all-groups - ``` - -3. **Run tests:** - ```bash - make test - ``` - -4. **Run linters and formatters:** - ```bash - make lint - ``` - -## CI/CD - -This project uses GitHub Actions for continuous integration and deployment. All pull requests must pass the following checks: - -- **Code formatting** (ruff format) -- **Import sorting** (ruff) -- **Linting** (ruff check) -- **Type checking** (mypy) -- **Spelling** (codespell) -- **Unit tests** (pytest on Python 3.9, 3.10, 3.11) - -### For Contributors - -Before submitting a pull request: - ```bash -# Format and fix imports -make format - -# Check for issues -make lint +git clone https://github.com/colesmcintosh/langchain-salesforce.git +cd langchain-salesforce +uv sync --all-groups -# Run tests -make test +make format # Format code +make lint # Run linters +make test # Run tests ``` -### Branch Protection - -The `main` branch is protected and requires: -- All status checks to pass -- At least one approval -- Up-to-date branches - -See [CI/CD Setup Guide](.github/SETUP.md) for detailed configuration instructions. - -## Contributing - -Contributions are welcome! Please open an issue or submit a pull request if you have suggestions or improvements. - -### Pull Request Process - -1. Fork the repository -2. Create a feature branch -3. Make your changes with tests -4. Ensure all CI checks pass -5. Submit a pull request - -For detailed guidelines, see our [Contributing Guide](CONTRIBUTING.md). +See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. ## License -This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details. \ No newline at end of file +MIT License. See [LICENSE](LICENSE).