# PinionAI Python Library

This is the official Python client library for the PinionAI platform. It provides a convenient, asynchronous way to interact with PinionAI agents, manage sessions, and use its various features including AI interactions and gRPC messaging. AI Agent authoring is performed in PinionAI Studio.

## Website and Documentation

[PinionAI website](https://www.pinionai.com)

[PinionAI documentation](https://docs.pinionai.com)

[Run PinionAI Agent from Github](https://github.com/pinionai/pinionai-streamlit-agent)

## Installation

### From PyPI

This package is available on PyPI and can be installed with `pip` or `uv`. We recommend `uv` for its speed.

**With `uv`**

If you don't have `uv`, you can install it from astral.sh.

```bash
# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
#OR
brew install uv
```

```bash
# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

Once `uv` is installed, you can install the `pinionai` package from PyPI:

```bash
uv pip install pinionai
```

**With `pip`**

If you prefer to use pip, you can still install the package with:

```bash
pip install pinionai
```

### From GitHub

To install the latest development version directly from the GitHub repository:

```bash
pip install git+https://github.com/pinionai/pinionai-package.git
```

## Optional Features

The client includes optional features that require extra dependencies. You can install them as needed based on the services you intend to use.

- gcp: Google Cloud Storage support (google-cloud-storage)
- aws: AWS S3 support (boto3)
- openai: Support for OpenAI models (openai)
- anthropic: Support for Anthropic models (anthropic)
- javascript: Support for running JavaScript snippets (mini-racer)
- sendgrid: Support for running sendgrid delivery (twiliio service)
- twilio: Support for sms delivery

To install one or more optional features, specify them in brackets. For example, to get support for GCP and AWS:

```bash
pip install pinionai[gcp,aws]
```

To install all optional features at once, use the `all` extra:

```bash
pip install pinionai[all]
```

**Options include:**

- dev = [
  "build",
  "twine",
  "ruff",
  "grpcio-tools",
  ]
- gcp = ["google-cloud-storage"]
- aws = ["boto3"]
- openai = ["openai"]
- anthropic = ["anthropic"]
- javascript = ["mini-racer"]
- sendgrid = ["sendgrid"]
- twilio = ["twilio"]
- all = [
  "pinionai[gcp,aws,openai,anthropic,javascript,twilio,sendgrid]"
  ]

## Adding to Requirements

To add this library to your project's requirements file, you can use the following formats.

**For `requirements.txt` or `requirements.in`:**

```bash
# For a specific version from PyPI
pinionai==0.2.7

# With optional features
pinionai[gcp,openai]==0.2.7

# From the main branch on GitHub
git+https://github.com/pinionai/pinionai-package.git@main
```

## Usage

Here's a Github link to a complete, fully functional example of how to use the `AsyncPinionAIClient`. In the link to our complete example, you can run a Streamlit or a CLI chat. **Note**: you can run a specific agent or deploy it to run and accept AIA files to run various agents.

[PinionAI Agent on Github](https://github.com/pinionai/pinionai-streamlit-agent)

## Configuration For Developers

### Setting up the environment

To set up a development environment, first create and activate a virtual environment using uv:

```bash
# Create a virtual environment named .venv +uv venv
# Activate the virtual environment
# On macOS and Linux
source .venv/bin/activate
# On Windows
.venv\Scripts\activate
```

Then, install the package in editable mode with its development dependencies:

```bash
uv pip install -e .[dev]
```
