Metadata-Version: 2.4
Name: airbyte-agent-harvest
Version: 0.1.16
Summary: Airbyte Harvest Connector for AI platforms
Project-URL: Homepage, https://github.com/airbytehq/airbyte-agent-connectors
Project-URL: Documentation, https://docs.airbyte.com/ai-agents/
Project-URL: Repository, https://github.com/airbytehq/airbyte-agent-connectors
Project-URL: Issues, https://github.com/airbytehq/airbyte-agent-connectors/issues
Author-email: Airbyte <contact@airbyte.io>
License: Elastic-2.0
Keywords: agent,ai,airbyte,api,connector,data-integration,harvest,llm,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.13
Requires-Dist: httpx>=0.24.0
Requires-Dist: jinja2>=3.0.0
Requires-Dist: jsonpath-ng>=1.6.1
Requires-Dist: jsonref>=1.1.0
Requires-Dist: opentelemetry-api>=1.37.0
Requires-Dist: opentelemetry-sdk>=1.37.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: segment-analytics-python>=2.2.0
Description-Content-Type: text/markdown

# Harvest

The Harvest agent connector is a Python package that equips AI agents to interact with Harvest through strongly typed, well-documented tools. It's ready to use directly in your Python app, in an agent framework, or exposed through an MCP.

Connector for the Harvest time-tracking and invoicing API (v2). Provides read access
to time tracking data including users, clients, projects, tasks, time entries, invoices,
estimates, expenses, and more. Harvest is a cloud-based time tracking and invoicing
solution that helps teams track time, manage projects, and streamline invoicing.


## Example questions

The Harvest connector is optimized to handle prompts like these.

- List all users in Harvest
- Show me all active projects
- List all clients
- Show me recent time entries
- List all invoices
- Show me all tasks
- List all expense categories
- Get company information
- How many hours were logged last week?
- Which projects have the most time entries?
- Show me all unbilled time entries
- What are the active projects for a specific client?
- List all overdue invoices
- Which users logged the most hours this month?

## Unsupported questions

The Harvest connector isn't currently able to handle prompts like these.

- Create a new time entry in Harvest
- Update a project budget
- Delete an invoice
- Start a timer for a task

## Installation

```bash
uv pip install airbyte-agent-harvest
```

## Usage

Connectors can run in open source or hosted mode.

### Open source

In open source mode, you provide API credentials directly to the connector.

```python
from airbyte_agent_harvest import HarvestConnector
from airbyte_agent_harvest.models import HarvestPersonalAccessTokenAuthConfig

connector = HarvestConnector(
    auth_config=HarvestPersonalAccessTokenAuthConfig(
        token="<Your Harvest personal access token>",
        account_id="<Your Harvest account ID>"
    )
)

@agent.tool_plain # assumes you're using Pydantic AI
@HarvestConnector.tool_utils
async def harvest_execute(entity: str, action: str, params: dict | None = None):
    return await connector.execute(entity, action, params or {})
```

### Hosted

In hosted mode, API credentials are stored securely in Airbyte Cloud. You provide your Airbyte credentials instead. 
If your Airbyte client can access multiple organizations, also set `organization_id`.

This example assumes you've already authenticated your connector with Airbyte. See [Authentication](AUTH.md) to learn more about authenticating. If you need a step-by-step guide, see the [hosted execution tutorial](https://docs.airbyte.com/ai-agents/quickstarts/tutorial-hosted).

```python
from airbyte_agent_harvest import HarvestConnector, AirbyteAuthConfig

connector = HarvestConnector(
    auth_config=AirbyteAuthConfig(
        customer_name="<your_customer_name>",
        organization_id="<your_organization_id>",  # Optional for multi-org clients
        airbyte_client_id="<your-client-id>",
        airbyte_client_secret="<your-client-secret>"
    )
)

@agent.tool_plain # assumes you're using Pydantic AI
@HarvestConnector.tool_utils
async def harvest_execute(entity: str, action: str, params: dict | None = None):
    return await connector.execute(entity, action, params or {})
```

## Full documentation

### Entities and actions

This connector supports the following entities and actions. For more details, see this connector's [full reference documentation](REFERENCE.md).

| Entity | Actions |
|--------|---------|
| Users | [List](./REFERENCE.md#users-list), [Get](./REFERENCE.md#users-get), [Context Store Search](./REFERENCE.md#users-context-store-search) |
| Clients | [List](./REFERENCE.md#clients-list), [Get](./REFERENCE.md#clients-get), [Context Store Search](./REFERENCE.md#clients-context-store-search) |
| Contacts | [List](./REFERENCE.md#contacts-list), [Get](./REFERENCE.md#contacts-get), [Context Store Search](./REFERENCE.md#contacts-context-store-search) |
| Company | [Get](./REFERENCE.md#company-get), [Context Store Search](./REFERENCE.md#company-context-store-search) |
| Projects | [List](./REFERENCE.md#projects-list), [Get](./REFERENCE.md#projects-get), [Context Store Search](./REFERENCE.md#projects-context-store-search) |
| Tasks | [List](./REFERENCE.md#tasks-list), [Get](./REFERENCE.md#tasks-get), [Context Store Search](./REFERENCE.md#tasks-context-store-search) |
| Time Entries | [List](./REFERENCE.md#time-entries-list), [Get](./REFERENCE.md#time-entries-get), [Context Store Search](./REFERENCE.md#time-entries-context-store-search) |
| Invoices | [List](./REFERENCE.md#invoices-list), [Get](./REFERENCE.md#invoices-get), [Context Store Search](./REFERENCE.md#invoices-context-store-search) |
| Invoice Item Categories | [List](./REFERENCE.md#invoice-item-categories-list), [Get](./REFERENCE.md#invoice-item-categories-get), [Context Store Search](./REFERENCE.md#invoice-item-categories-context-store-search) |
| Estimates | [List](./REFERENCE.md#estimates-list), [Get](./REFERENCE.md#estimates-get), [Context Store Search](./REFERENCE.md#estimates-context-store-search) |
| Estimate Item Categories | [List](./REFERENCE.md#estimate-item-categories-list), [Get](./REFERENCE.md#estimate-item-categories-get), [Context Store Search](./REFERENCE.md#estimate-item-categories-context-store-search) |
| Expenses | [List](./REFERENCE.md#expenses-list), [Get](./REFERENCE.md#expenses-get), [Context Store Search](./REFERENCE.md#expenses-context-store-search) |
| Expense Categories | [List](./REFERENCE.md#expense-categories-list), [Get](./REFERENCE.md#expense-categories-get), [Context Store Search](./REFERENCE.md#expense-categories-context-store-search) |
| Roles | [List](./REFERENCE.md#roles-list), [Get](./REFERENCE.md#roles-get), [Context Store Search](./REFERENCE.md#roles-context-store-search) |
| User Assignments | [List](./REFERENCE.md#user-assignments-list), [Context Store Search](./REFERENCE.md#user-assignments-context-store-search) |
| Task Assignments | [List](./REFERENCE.md#task-assignments-list), [Context Store Search](./REFERENCE.md#task-assignments-context-store-search) |
| Time Projects | [List](./REFERENCE.md#time-projects-list), [Context Store Search](./REFERENCE.md#time-projects-context-store-search) |
| Time Tasks | [List](./REFERENCE.md#time-tasks-list), [Context Store Search](./REFERENCE.md#time-tasks-context-store-search) |


### Authentication

For all authentication options, see the connector's [authentication documentation](AUTH.md).

### Harvest API docs

See the official [Harvest API reference](https://help.getharvest.com/api-v2/).

## Version information

- **Package version:** 0.1.16
- **Connector version:** 1.0.3
- **Generated with Connector SDK commit SHA:** c5258debd165ab701252c1436d4acfb475bf92b9
- **Changelog:** [View changelog](https://github.com/airbytehq/airbyte-agent-connectors/blob/main/connectors/harvest/CHANGELOG.md)