Skip to content
This repository was archived by the owner on Mar 26, 2026. It is now read-only.
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 15 additions & 23 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,24 +1,12 @@
# Floyd Engine

> **Dev Preview** - APIs may change. Not recommended for production use yet.
Open-source booking engine for AI agents. Two-phase booking, conflict detection, and scheduling policies — built for concurrent workloads.

Booking engine for AI agents.

- **Services & Policies** - Define bookable offerings with scheduling rules
- **Hold → Confirm** - Two-phase booking for async workflows
- **Race-safe** - Database-level conflict detection
- **Retry-friendly** - Idempotent operations with automatic deduplication
- **Real-time** - Webhooks for booking events

## Why Floyd?

Building booking into AI agents is harder than it looks:

- **Async conversations** - Users say "yes" seconds after you check availability
- **Retries & timeouts** - Network failures cause duplicate bookings
- **Concurrency** - Multiple agents booking the same resource

Floyd handles all of this so you can focus on your agent.
- **Hold → Confirm** - Reserve a slot with TTL, confirm when ready, auto-expire if not
- **Conflict detection** - Database-level row locking + GiST indexes prevent double-booking
- **Scheduling policies** - Working hours, buffers, lead times, grid alignment
- **Idempotency** - Safe retries via `Idempotency-Key` header
- **Webhooks** - HMAC-signed booking events via transactional outbox

## Example

Expand All @@ -37,8 +25,8 @@ curl -X POST http://localhost:4000/v1/ledgers/$LEDGER_ID/bookings \
-d '{
"serviceId": "svc_...",
"resourceId": "rsc_stylist1",
"startAt": "2026-01-15T10:00:00Z",
"endAt": "2026-01-15T11:00:00Z"
"startTime": "2026-03-15T10:00:00Z",
"endTime": "2026-03-15T11:00:00Z"
}'

# 3. Confirm when user says "yes"
Expand All @@ -59,15 +47,19 @@ docker run \
ghcr.io/floyd-run/engine:master
```

See the [Quickstart guide](https://docs.floyd.run/docs/quickstart) for Docker Compose setup and full instructions.
See the [Quickstart guide](docs/quickstart.md) for Docker Compose setup and full instructions.

## Documentation

Full API reference, guides, and examples at [docs.floyd.run](https://docs.floyd.run)
Full API reference, guides, and examples in the [docs](docs/) folder.

## Managed Cloud

Prefer not to self-host? [floyd.run](https://floyd.run) is a hosted version with organizations, API keys, and a web console.

## Feedback

This is a dev preview - we'd love your input! Open an issue on [GitHub](https://github.com/floyd-run/engine/issues) or reach out at [hey@floyd.run](mailto:hey@floyd.run).
Open an issue on [GitHub](https://github.com/floyd-run/engine/issues) or reach out at [hey@floyd.run](mailto:hey@floyd.run).

## License

Expand Down