diff --git a/README.md b/README.md index 504ee0a..be5a243 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,20 @@ FGP replaces slow MCP stdio servers with persistent UNIX socket daemons. Instead of spawning a new process for each tool call (~2.3s overhead), FGP keeps daemons warm and ready (~10-50ms latency). +> This repository hosts the **FGP docs, tooling, and companion apps**, plus the `fgp-travel` daemon. Core SDKs and most service daemons live in their own repos—see **Related Repositories** below. + +## What lives in this repo + +| Path | Description | +|------|-------------| +| `docs/` | MkDocs documentation site content (published to https://fast-gateway-protocol.github.io/fgp/) | +| `app/` | Tauri + SvelteKit desktop app for managing local FGP daemons | +| `website/` | Marketing site (React + Vite) | +| `travel/` | `fgp-travel` daemon for flight + hotel search via Kiwi/Skypicker and Xotelo | +| `benchmarks/` | Benchmark scripts and chart generation for performance claims | +| `install.sh` | Installer for the CLI + default daemons | +| `mkdocs.yml` | MkDocs configuration for the docs site | + ## Performance

@@ -86,146 +100,48 @@ Fast iMessage operations via direct SQLite queries to `chat.db`: **Key insight:** Latency is dominated by external API calls, not FGP overhead (~5-10ms). Local daemons (iMessage, Browser) are fastest. For MCP, add ~2.3s cold-start to every call. -## Why FGP? - -LLM agents make many sequential tool calls. Cold-start overhead compounds: - -

- Cumulative Cold-Start Overhead -

- -| Agent Workflow | Tool Calls | MCP Overhead | FGP Overhead | Time Saved | -|----------------|------------|--------------|--------------|------------| -| Check email | 2 | 4.6s | 0.02s | **4.6s** | -| Browse + fill form | 5 | 11.5s | 0.05s | **11.4s** | -| Full productivity check | 10 | 23s | 0.1s | **22.9s** | -| Complex agent task | 20 | 46s | 0.2s | **45.8s** | - -## Architecture - -``` -┌─────────────────────────────────────────────────────────────────┐ -│ AI Agent / Claude │ -├─────────────────────────────────────────────────────────────────┤ -│ FGP UNIX Sockets │ -│ ~/.fgp/services/{browser,gmail,calendar,github,imessage}/ │ -├──────────┬──────────┬──────────┬──────────┬──────────┬─────────┤ -│ Browser │ Gmail │ Calendar │ GitHub │ iMessage │ ... │ -│ Daemon │ Daemon │ Daemon │ Daemon │ Daemon │ │ -│ (Rust) │ (PyO3) │ (PyO3) │ (Rust) │ (Rust) │ │ -├──────────┴──────────┴──────────┴──────────┴──────────┴─────────┤ -│ Chrome │ Google APIs │ gh CLI │ chat.db + AS │ -└─────────────────────────────────────────────────────────────────┘ -``` - -**Key design decisions:** -- **UNIX sockets** - Zero network overhead, file-based permissions -- **NDJSON protocol** - Human-readable, streaming-friendly -- **Per-service daemons** - Independent scaling, fault isolation -- **Rust core** - Sub-millisecond latency, low memory (~10MB) - -## Installation - -### One-liner (Recommended) - -```bash -curl -fsSL https://raw.githubusercontent.com/fast-gateway-protocol/fgp/master/install.sh | bash -``` - -This installs the FGP CLI and browser daemon to `~/.fgp/bin/`. - -### Install specific daemons - -```bash -# Install Gmail and Calendar daemons -curl -fsSL https://raw.githubusercontent.com/fast-gateway-protocol/fgp/master/install.sh | bash -s -- gmail calendar - -# Install all daemons -curl -fsSL https://raw.githubusercontent.com/fast-gateway-protocol/fgp/master/install.sh | bash -s -- all -``` +## Quick paths for this repo -### From source +### Documentation site (MkDocs) ```bash -git clone https://github.com/fast-gateway-protocol/browser -cd browser && cargo build --release +cd docs +python3 -m venv .venv +source .venv/bin/activate +pip install -r requirements.txt +mkdocs serve ``` -## Quick Start - -### Browser Daemon +### Desktop app (Tauri + SvelteKit) ```bash -# Start daemon -fgp start browser - -# Or if installed from source: -cd browser && cargo build --release - -# Start daemon -./target/release/browser-gateway start - -# Use it -browser-gateway open "https://example.com" -browser-gateway snapshot -browser-gateway click "button#submit" -browser-gateway screenshot /tmp/page.png +cd app +pnpm install +pnpm dev ``` -### Gmail Daemon +### Marketing website (React + Vite) ```bash -cd gmail && cargo build --release - -# Start daemon (requires OAuth setup) -./target/release/fgp-gmail start - -# Use it -fgp call gmail.inbox '{"limit": 5}' -fgp call gmail.search '{"query": "from:important"}' +cd website +pnpm install +pnpm dev ``` -### Calendar Daemon +### Travel daemon (`fgp-travel`) ```bash -cd calendar && cargo build --release - -# Start daemon -./target/release/fgp-calendar start - -# Use it -fgp call calendar.today -fgp call calendar.upcoming '{"days": 7}' -fgp call calendar.free_slots '{"duration_minutes": 30}' +cd travel +cargo build --release +./target/release/fgp-travel start ``` -### GitHub Daemon +### Benchmarks ```bash -cd github && cargo build --release - -# Start daemon (uses gh CLI auth) -./target/release/fgp-github start - -# Use it -fgp call github.repos '{"limit": 10}' -fgp call github.issues '{"repo": "owner/repo"}' -fgp call github.notifications -``` - -### iMessage Daemon (macOS) - -```bash -cd imessage && cargo build --release - -# Start daemon (requires Full Disk Access) -./target/release/fgp-imessage-daemon start - -# Use it -fgp call imessage.recent '{"limit": 10}' -fgp call imessage.unread -fgp call imessage.analytics '{"days": 30}' -fgp call imessage.bundle '{"include": "unread_count,recent,analytics"}' +cd benchmarks +python3 browser_benchmark.py --iterations 5 +python3 generate_charts.py ``` ## FGP Protocol @@ -247,66 +163,21 @@ All daemons use the same NDJSON-over-UNIX-socket protocol. - `methods` - List available methods - `stop` - Graceful shutdown -## Repository Structure +## Related repositories -``` -fgp/ -├── daemon/ # Core SDK (Rust) - Build your own FGP daemons -├── daemon-py/ # Python SDK - For Python-based daemons -├── protocol/ # FGP protocol specification -├── cli/ # `fgp` CLI for daemon management -│ -├── browser/ # Browser automation (Chrome DevTools Protocol) -├── gmail/ # Gmail daemon (Google API) -├── calendar/ # Google Calendar daemon -├── github/ # GitHub daemon (GraphQL + REST) -├── imessage/ # iMessage daemon (macOS - SQLite + AppleScript) -└── ... -``` +Core SDKs and service daemons live in their own repos under the FGP GitHub org: -## Status - -| Component | Status | Performance | -|-----------|--------|-------------| -| imessage | **Production** | 5ms analytics, 8ms recent **(480x)** | -| browser | **Production** | 8ms navigate, 9ms snapshot **(292x)** | -| gmail | Beta | 116ms thread read, 881ms inbox | -| calendar | Beta | 177ms search, 233ms avg | -| github | Beta | 390ms issues, 474ms avg | -| daemon SDK | Stable | Core library | -| cli | WIP | Daemon management | - -## Building a New Daemon - -```rust -use fgp_daemon::{FgpServer, FgpService}; - -struct MyService { /* state */ } - -impl FgpService for MyService { - fn name(&self) -> &str { "my-service" } - fn version(&self) -> &str { "1.0.0" } - - fn dispatch(&self, method: &str, params: HashMap) -> Result { - match method { - "my-service.hello" => Ok(json!({"message": "Hello!"})), - _ => bail!("Unknown method"), - } - } -} - -fn main() { - let server = FgpServer::new(MyService::new(), "~/.fgp/services/my-service/daemon.sock")?; - server.serve()?; -} -``` +- [daemon](https://github.com/fast-gateway-protocol/daemon) - Core Rust SDK +- [daemon-py](https://github.com/fast-gateway-protocol/daemon-py) - Python SDK +- [cli](https://github.com/fast-gateway-protocol/cli) - `fgp` CLI +- [browser](https://github.com/fast-gateway-protocol/browser) - Browser daemon +- [gmail](https://github.com/fast-gateway-protocol/gmail) - Gmail daemon +- [calendar](https://github.com/fast-gateway-protocol/calendar) - Calendar daemon +- [github](https://github.com/fast-gateway-protocol/github) - GitHub daemon +- [imessage](https://github.com/fast-gateway-protocol/imessage) - iMessage daemon +- [neon](https://github.com/fast-gateway-protocol/neon) - Neon daemon +- [vercel](https://github.com/fast-gateway-protocol/vercel) - Vercel daemon ## License MIT - -## Related - -- [daemon](https://github.com/fast-gateway-protocol/daemon) - Core SDK -- [browser](https://github.com/fast-gateway-protocol/browser) - Browser daemon (292x faster) -- [imessage](https://github.com/fast-gateway-protocol/imessage) - iMessage daemon (480x faster, macOS) diff --git a/app/README.md b/app/README.md index 858d179..1defc9a 100644 --- a/app/README.md +++ b/app/README.md @@ -1,7 +1,45 @@ -# Tauri + SvelteKit + TypeScript +# FGP Manager App -This template should help get you started developing with Tauri, SvelteKit and TypeScript in Vite. +Desktop companion app for managing local FGP daemons. Built with **Tauri**, **SvelteKit**, and **TypeScript** and designed as a small popover window that can start/stop daemons, show status, and open the marketplace view. -## Recommended IDE Setup +## Tech stack -[VS Code](https://code.visualstudio.com/) + [Svelte](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-vscode) + [Tauri](https://marketplace.visualstudio.com/items?itemName=tauri-apps.tauri-vscode) + [rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer). +- Tauri 2 (Rust backend + webview) +- SvelteKit + TypeScript (frontend) +- Tailwind CSS for styling + +## Project layout + +``` +app/ +├── src/ # Svelte routes + UI +├── src-tauri/ # Tauri Rust commands & config +├── static/ # Static assets +└── vite.config.js # Vite configuration +``` + +## Development + +```bash +pnpm install +pnpm dev +``` + +## Building + +```bash +pnpm install +pnpm build +pnpm tauri build +``` + +## Useful commands + +- `pnpm dev` - Run the SvelteKit dev server +- `pnpm tauri dev` - Run the Tauri desktop shell in dev mode +- `pnpm tauri build` - Produce a production desktop build + +## Notes + +- The frontend relies on Tauri commands like `list_daemons`, `start_daemon`, and `stop_daemon` from the Rust backend in `src-tauri/`. +- Marketplace is rendered in a separate Tauri window opened from the main popover UI. diff --git a/benchmarks/README.md b/benchmarks/README.md index d14d039..d6fbee1 100644 --- a/benchmarks/README.md +++ b/benchmarks/README.md @@ -14,11 +14,12 @@ Performance benchmarks comparing FGP daemons against MCP servers and other autom | `gmail_workflow_benchmark.py` | Gmail operations | List, read, send timing | | `hn_workflow_benchmark.py` | HackerNews demo workflow | Real-world scraping scenario | | `mcp_server_benchmarks.py` | MCP baseline measurements | Cold-start overhead baseline | +| `generate_charts.py` | Chart generation for docs | SVG/PNG charts in `docs/assets/` | ## Requirements ```bash -pip install rich tabulate statistics +pip install rich tabulate statistics plotly kaleido ``` ## Quick Start diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..1393c30 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,33 @@ +# Documentation Site + +This directory contains the MkDocs source for the Fast Gateway Protocol documentation at https://fast-gateway-protocol.github.io/fgp/. + +## Structure + +- `index.md` - Landing page +- `getting-started/` - Installation and quickstart guides +- `daemons/` - Service-specific docs +- `protocol/` - NDJSON protocol spec +- `reference/` - CLI + API reference +- `development/` - Contributor and build docs +- `assets/` - Images and charts used in docs + +## Local development + +```bash +cd docs +python3 -m venv .venv +source .venv/bin/activate +pip install -r requirements.txt +mkdocs serve +``` + +## Build + +```bash +mkdocs build +``` + +## Updating benchmarks + +Benchmark charts are generated from `benchmarks/generate_charts.py` in the repo root and written to `docs/assets/`. diff --git a/travel/README.md b/travel/README.md new file mode 100644 index 0000000..def5161 --- /dev/null +++ b/travel/README.md @@ -0,0 +1,57 @@ +# fgp-travel + +FGP daemon for flight and hotel search via the **Kiwi/Skypicker GraphQL API** and the **Xotelo REST API**. It exposes FGP-compatible methods over a UNIX socket so agents can query travel options without paying repeated cold-start overhead. + +## Features + +- Flight search (one-way and round-trip) +- Hotel search + rate lookup +- Local airport/city lookup database for fast `find_location` +- Built-in response caching (5 minute TTL) + +## Build + +```bash +cargo build --release +``` + +## Running the daemon + +```bash +./target/release/fgp-travel start +``` + +Foreground mode: + +```bash +./target/release/fgp-travel start --foreground +``` + +Stop / status / health: + +```bash +./target/release/fgp-travel stop +./target/release/fgp-travel status +./target/release/fgp-travel health +``` + +## Methods + +| Method | Description | +|--------|-------------| +| `travel.find_location` | Search airports/cities by term | +| `travel.search_flights` | One-way flight search | +| `travel.search_roundtrip` | Round-trip flight search | +| `travel.search_hotels` | Hotel search | +| `travel.hotel_rates` | Hotel rate lookup | + +## Example + +```bash +echo '{"id":"1","v":1,"method":"travel.find_location","params":{"term":"SFO"}}' | nc -U ~/.fgp/services/travel/daemon.sock +``` + +## Notes + +- The daemon uses public endpoints from Kiwi/Skypicker and Xotelo; no API keys are required. +- Socket path defaults to `~/.fgp/services/travel/daemon.sock` (override with `--socket`). diff --git a/website/README.md b/website/README.md new file mode 100644 index 0000000..1ed36a8 --- /dev/null +++ b/website/README.md @@ -0,0 +1,31 @@ +# FGP Website + +Marketing site for the Fast Gateway Protocol project. Built with **React**, **Vite**, **TanStack Router**, and **Tailwind CSS**. + +## Project layout + +``` +website/ +├── src/ # React routes + components +├── public/ # Static assets +└── vite.config.ts # Vite configuration +``` + +## Development + +```bash +pnpm install +pnpm dev +``` + +## Build + +```bash +pnpm build +``` + +## Lint + +```bash +pnpm lint +```