Metadata-Version: 2.3
Name: persona-toolkit
Version: 0.1.2
Summary: Toolkit for Persona, an agent AI system — provides modular, callable tools for dynamic function execution
Author: Bruno Fortunato
Author-email: bruno.fortunato@applica.guru
Requires-Python: >=3.9
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: fastapi (>=0.115.12,<0.116.0)
Requires-Dist: pydantic (>=2.10.6,<3.0.0)
Requires-Dist: python-dotenv (>=1.0.1,<2.0.0)
Requires-Dist: rich (>=13.9.4,<14.0.0)
Requires-Dist: typer (>=0.15.2,<0.16.0)
Requires-Dist: uvicorn (>=0.34.0,<0.35.0)
Description-Content-Type: text/markdown

# Persona CLI

**Persona CLI** is a command-line tool for creating and managing projects that use the `persona-toolkit` — a modular
function-calling framework designed for agent-based systems.

This CLI helps you scaffold projects, generate tools, test them locally, and run the FastAPI server that exposes your
tools via REST API.

---

## 🚀 Installation

To use the CLI, first install the `persona-toolkit` library (assuming it's published or available locally):

```bash
pip install persona-toolkit
```

> Or if you're developing locally:

```bash
cd persona-toolkit/
poetry install
```

The CLI is exposed as:

```bash
persona-cli
```

---

## 📆 Features

### `init`

Create a new project scaffold with Poetry and the required structure:

```bash
persona-cli init my-project
```

This will:

- Initialize a Poetry project
- Install `persona-toolkit` as a dependency
- Create a `tools/` folder where your tools will live

---

### `add-tool`

Add a new tool interactively:

```bash
persona-cli add-tool
```

You'll be prompted for a tool name. A new Python file will be created in the `tools/` directory with a ready-to-edit
template including:

- `Input` and `Output` models (using Pydantic)
- A `run()` function

---

### `test-tool`

Test a tool locally by manually entering its input values:

```bash
persona-cli test-tool echo
```

This will:

- Import the specified tool from the `tools/` directory
- Prompt for input fields
- Run the `run()` function and show the output

---

### `run`

Start the FastAPI server and expose your tools via HTTP:

```bash
persona-cli run --port 8000
```

You can now access:

- `GET /tools` — list available tools
- `GET /tools/{tool}/schema` — get tool schema
- `POST /tools/{tool}/invocations` — run a tool

---

## 🗂 Project Structure

```bash
my-project/
├── pyproject.toml         # Poetry project config
├── tools/
│   └── echo.py            # Example tool
```

Each tool must define:

- `Input` (a Pydantic model)
- `Output` (a Pydantic model)
- `run(input: Input) -> Output`

---

## 💡 Example Tool

```python
# tools/echo.py

from pydantic import BaseModel, Field


class Input(BaseModel):
    message: str = Field(description="Message to echo")


class Output(BaseModel):
    message: str


def run(input: Input) -> Output:
    """Echo the message back"""
    return Output(message=f"Echo: {input.message}")
```

---

## ✅ Requirements

- Python 3.9+
- Poetry
- Uvicorn (installed automatically)

---

## 📃 License

MIT License

---

Built for the [Persona Agent System](https://github.com/your-org/persona) 🤖


