Metadata-Version: 2.1
Name: pyn8n
Version: 2024.12.24.4
Summary: N8N client and AI tools.
Home-page: https://github.com/user/seanchatmangpt/pyn8n
Author: Sean Chatman
Author-email: info@chatmangpt.com
Requires-Python: >=3.12,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: aio-apiclient (>=1.7.0,<2.0.0)
Requires-Dist: aiofiles (>=24.1.0,<25.0.0)
Requires-Dist: api-client-pydantic (>=3.1.0,<4.0.0)
Requires-Dist: cloudpickle (>=3.1.0,<4.0.0)
Requires-Dist: coloredlogs (>=15.0.1)
Requires-Dist: dslmodel (>=2024.12.22.2,<2025.0.0.0)
Requires-Dist: dspy-ai (>=2.5.43,<3.0.0)
Requires-Dist: fastapi[all] (>=0.110.1)
Requires-Dist: gunicorn (>=21.2.0)
Requires-Dist: pydantic (>=2.10.4,<3.0.0)
Requires-Dist: pydantic-ai[logfire] (>=0.0.14,<0.0.15)
Requires-Dist: respx (>=0.22.0,<0.23.0)
Requires-Dist: typer[all] (>=0.12.0)
Requires-Dist: uvicorn[standard] (>=0.29.0)
Project-URL: Repository, https://github.com/user/seanchatmangpt/pyn8n
Description-Content-Type: text/markdown

# pyn8n v4

**pyn8n** is an advanced Python client and automation toolkit designed to extend and enhance the functionality of [n8n](https://n8n.io). This new release introduces **dynamic integration capabilities**, **conversational automation tools**, and a seamless **developer experience** for orchestrating workflows with Python. It integrates directly with n8n while leveraging Python's flexibility to tackle advanced use cases, ensuring a smooth, efficient, and scalable automation process.

---

## 🚀 Features

- **Dynamic Workflow Generation**: Create, manage, and monitor workflows programmatically using a Pythonic API.
- **Conversational CLI**: Use natural language to define workflows with an interactive CLI powered by AI.
- **Ash Framework Integration**: Enable advanced orchestration and business logic layers with Ash while remaining invisible to n8n automators.
- **n8n API Wrapper**: Simplified and robust interaction with n8n’s REST APIs, including node discovery and dynamic updates.
- **Plug-and-Play Extensibility**: Add custom nodes, integrations, and pre-built actions with minimal setup.
- **Enterprise-Grade Governance**: Monitor workflows, track execution logs, and implement error handling for compliance-ready automation.

---

## 🛠️ Installation

To install pyn8n, run:

```bash
pip install pyn8n
```

---

## 🔧 Configuration

### Prerequisites

1. **n8n Instance**: Ensure you have an n8n instance running locally or hosted.
2. **API Key**: Generate an API key in your n8n settings for secure access.

### Environment Variables

Create a `.env` file in your project directory with the following:

```env
N8N_BASE_URL=http://localhost:5678
N8N_API_KEY=your_api_key_here
```

Or set them directly in your environment.

---

## 📚 Usage

### CLI

Run the following command to start the interactive CLI:

```bash
pyn8n
```

Example:

```bash
$ pyn8n
Welcome to pyn8n! What would you like to automate today?
> Send an email when a new row is added to Google Sheets.
> Generating workflow...
> Workflow created! Would you like to run it now? (yes/no)
```

### Python API

#### Creating a Workflow

```python
from pyn8n import N8nClient, Workflow

# Initialize client
client = N8nClient(base_url="http://localhost:5678", api_key="your_api_key")

# Define a workflow
workflow = Workflow(
    name="New Row Email Notification",
    nodes=[
        {
            "id": "1",
            "type": "trigger",
            "parameters": {"sheet": "ExampleSheet"},
            "position": [200, 150],
        },
        {
            "id": "2",
            "type": "email",
            "parameters": {"recipient": "user@example.com", "message": "New row added!"},
            "position": [400, 150],
        },
    ],
    connections={"1": ["2"]},
)

# Create and activate workflow
created_workflow = client.create_workflow(workflow)
client.activate_workflow(created_workflow.id)
```

#### Managing Credentials

```python
from pyn8n import Credential

# Add credentials
client.create_credential(Credential(name="Google Sheets API", type="google", data={"api_key": "your_google_api_key"}))
```

---

## 🧑‍💻 Development

### Running Locally

Clone the repository and start a development environment:

```bash
git clone https://github.com/user/seanchatmangpt/pyn8n.git
cd pyn8n

# Using Docker
docker compose up --detach dev
docker compose exec dev zsh

# Or, using Codespaces or VS Code Dev Containers
```

### Testing

Run tests with:

```bash
poe test
```

---

## 🤝 Contributing

We welcome contributions! Follow these steps to get started:

1. Fork the repository and create a new branch for your changes.
2. Run `poe lint` to check code style.
3. Submit a pull request with a detailed description of your changes.

For detailed contribution guidelines, see [`CONTRIBUTING.md`](CONTRIBUTING.md).

---

## 🌟 Features in v4

1. **Dynamic Node Mapping**: Automatically generate and sync node configurations based on n8n instances.
2. **Ash Framework Backend**: Optional integration for handling state machines, advanced orchestration, and resource management.
3. **Enterprise Integrations**: Extend n8n workflows with enterprise-grade observability and governance.
4. **Error Handling and Retries**: Built-in support for managing failed executions with fallback strategies.
5. **Interactive Workflow Creation**: Use natural language or the Python API to define workflows programmatically.

---

## 💼 For Enterprises

For enterprise users, pyn8n offers support for:

- **Role-based Access Control (RBAC)**
- **Custom Node Libraries**
- **Advanced Logging and Monitoring**
- **Dedicated Support and SLAs**

Contact us at [enterprise@pyn8n.io](mailto:enterprise@pyn8n.io) for more details.

---

## 🛣️ Roadmap

- [ ] **AI-Assisted Workflow Suggestions**  
- [ ] **Marketplace Integration for Pre-Built Workflows**  
- [ ] **Advanced Analytics Dashboards**  
- [ ] **Cross-Platform Automation**

---

## 📜 License

pyn8n is released under the [MIT License](LICENSE).  

Happy automating! 🚀
