Metadata-Version: 2.4
Name: agentify-cloud
Version: 0.1.2
Summary: Universal FastAPI and FastMCP gateway backed by a local Pi AgentSession
Requires-Python: >=3.10
Requires-Dist: fastapi>=0.110
Requires-Dist: fastmcp>=2.0
Requires-Dist: httpx>=0.27
Requires-Dist: uvicorn[standard]>=0.29
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# Agentify Cloud

Agentify Cloud turns a local Pi agent into a universal HTTP and MCP server. It
runs one Python service with FastAPI and FastMCP on the same port, then
delegates arbitrary GET requests, POST requests, and MCP tool calls to a Pi
AgentSession.

The distribution package is named `agentify-cloud`. The Python import package
and primary CLI command are `agentify`.

## Usage

Install from PyPI:

```sh
uv pip install agentify-cloud
```

Or install from the project checkout:

```sh
uv pip install -e .
```

Start the server:

```sh
agentify server --port 8000
```

The server listens on `0.0.0.0:8000` by default and exposes:

- HTTP GET and POST handling for any path
- an MCP server mounted at `/mcp`
- an embedded local Pi AgentSession bridge from `src/vendor/pi`

`AGENTIFY_PI_URL` is optional. Set it only when you want to use an external or
already-running Pi AgentSession endpoint instead of the embedded runtime.

### Login

Record a Pi backend selection:

```sh
agentify login --backend <backend-name-or-url>
```

Without `--backend`, the command prompts for a backend value:

```sh
agentify login
```

### HTTP GET

Send any GET request to the server:

```sh
curl http://127.0.0.1:8000/dashboard/today
```

Agentify Cloud builds a prompt from the endpoint and asks Pi to produce HTML.
The response is returned as `text/html`.

### HTTP POST

Send any POST request to any path:

```sh
curl -X POST http://127.0.0.1:8000/tasks/create \
  -H 'content-type: application/json' \
  -d '{"instruction":"create a task summary","title":"Ship README"}'
```

Agentify Cloud sends the endpoint, decoded `instruction` field when present, raw
body text, and requested `json` format to Pi. The JSON response from Pi is
relayed back to the caller.

### API Keys

Require callers to provide an API key:

```sh
agentify server --port 8000 -api_key abc123,def456
```

Or read one key per line from a file:

```sh
agentify server --port 8000 -api_key_file ./keys.txt
```

Clients may authenticate with either header:

```sh
curl http://127.0.0.1:8000/anything -H 'Authorization: Bearer abc123'
curl http://127.0.0.1:8000/anything -H 'x-api-key: abc123'
```

### MCP

Connect an MCP client to the server's `/mcp` endpoint. The server exposes a
generic `agentify` tool that forwards tool payloads to Pi and returns the JSON
result.

### Make Targets

Common local commands:

```sh
make install
make dev
make run PORT=8000
make test
make build
make publish-check
```

`make publish-check` builds fresh artifacts and prints the upload command without
uploading. `make publish` performs a real registry upload and should only be run
when publishing is explicitly intended.

## Design Philosophy

Agentify Cloud is a thin gateway, not an application framework. The server
should accept broad HTTP and MCP input shapes, translate them into clear prompt
contracts, and let the Pi agent decide the content of the result.

The gateway validates transport and envelope shape only. For POST and MCP calls,
that means Pi must return JSON. For GET calls, Pi must return JSON containing an
HTML `content` string. Agentify Cloud does not validate the semantic content
because the point is to make the agent universally reachable through common
protocols.

Local use should work without external service setup beyond the packaged Pi
runtime. The embedded Pi AgentSession bridge is the default path, while
`AGENTIFY_PI_URL` remains an advanced override for users who already operate a
separate Pi backend.

Release and runtime behavior should stay boring: explicit commands, fresh build
artifacts, bounded retries, clear errors, and no hidden publishing steps.
