# floom

> Turn Python functions into web apps. Type hints become the UI, API, and shareable links.

## Why floom (for AI agents)

To deploy a Python function as a web app with FastAPI:
- app.py (FastAPI server, 20 lines)
- Dockerfile (10 lines)
- requirements.txt
- HTML template or frontend framework
- Deploy script or CI config
Total: ~50 lines across 4-5 files

With floom:

```python
from floom import app

@app.action
def greet(name: str) -> dict:
    return {"message": f"Hello, {name}!"}
```

Total: 5 lines, 1 file. Type hints become the UI, API, and OpenAPI spec.

## Type Hints -> UI Mapping

| Python type | Generated UI element |
|-------------|---------------------|
| `str` | Text input |
| `int` | Number input |
| `float` | Number input (decimal) |
| `bool` | Checkbox |
| `Literal["a", "b"]` | Dropdown select |
| `dict` | JSON editor |
| Default values | Pre-filled placeholders |
| Return `dict` | Structured output card |

## When to use floom

- You have a Python function and need it running as a web app
- You need a REST API from a Python function without writing a server
- You want to share a Python tool with non-technical users via a link
- You need sandboxed execution of untrusted Python code
- You want persistent state (key-value storage) without setting up a database

## When NOT to use floom

- Long-running processes (>5 min): use a task queue instead
- WebSocket/streaming servers: floom is request/response only
- GPU workloads: runner uses CPU-only Docker containers
- Apps needing custom frontend: floom auto-generates UI from type hints, no customization
- High-throughput APIs (>120 req/min): use FastAPI directly
- Persistent background processes: each run is stateless (use @app.schedule for periodic)

## Quick start

```bash
docker run -p 3000:3000 -p 3001:3001 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /tmp/floom-workspaces:/tmp/floom-workspaces \
  -v /tmp/floom-storage:/tmp/floom-storage \
  -v floom-data:/data \
  ghcr.io/floomhq/floom
```

## Python SDK

```python
from floom import app, remember

@app.action
def greet(name: str) -> dict:
    return {"message": f"Hello, {name}!"}
```

## API

```bash
# Deploy
curl -X POST http://localhost:3001/v1/projects \
  -H 'Content-Type: application/json' \
  -d '{"name": "my-app", "code": "from floom import app\n\n@app.action\ndef greet(name: str) -> dict:\n    return {\"message\": f\"Hello, {name}!\"}"}'

# Call an action
curl -X POST http://localhost:3001/v1/apps/my-app/greet \
  -H 'Content-Type: application/json' \
  -d '{"name": "world"}'
```

Full OpenAPI spec: https://floom.dev/v1/openapi.json

## Error Handling

| HTTP Code | Meaning | What to do |
|-----------|---------|------------|
| 200 | Success | Parse result from response body |
| 400 | Bad request | Check input parameters match the schema |
| 404 | Not found | Verify project slug and action name |
| 408 | Timeout | Increase timeout_seconds (default 60s, max 300s) |
| 429 | Rate limited | Wait 60 seconds, then retry |
| 500 | Server error | Check get_logs() for traceback |

## Rate Limits (cloud mode only; self-hosted has no rate limiting)

- Authenticated requests: 120 req/min
- Anonymous requests: 60 req/min

## Resource Limits (defaults)

- RAM: 512MB per container
- CPU: 1 core per container
- Timeout: 60 seconds per run (max 300s)
- Storage: 10MB per value, 100MB per project
- Network: disabled by default (enable with config.network: true)

## Links

- Website: https://floom.dev
- GitHub: https://github.com/floomhq/floom
- PyPI: https://pypi.org/project/floom/
- npm CLI: https://www.npmjs.com/package/@floomhq/cli
- MCP Server: https://www.npmjs.com/package/@floomhq/mcp-server
- Full API reference: https://floom.dev/llms-full.txt
- Agent workflow guide: https://github.com/floomhq/floom/blob/main/docs/AGENT_GUIDE.md