{"id":51970748,"url":"https://github.com/ibuilder/osprey","last_synced_at":"2026-07-29T22:01:20.985Z","repository":{"id":373017345,"uuid":"1310020250","full_name":"ibuilder/osprey","owner":"ibuilder","description":"The foreman that never sleeps — open-source, self-hostable background agent that watches every source on a construction/RE project and surfaces the one thing to act on now.","archived":false,"fork":false,"pushed_at":"2026-07-24T20:24:37.000Z","size":885,"stargazers_count":0,"open_issues_count":12,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-24T22:06:21.126Z","etag":null,"topics":["ai-agent","construction","fastapi","open-source","python","real-estate","rust","self-hosted","tauri"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ibuilder.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-23T14:17:08.000Z","updated_at":"2026-07-24T20:24:46.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ibuilder/osprey","commit_stats":null,"previous_names":["ibuilder/osprey"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ibuilder/osprey","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibuilder%2Fosprey","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibuilder%2Fosprey/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibuilder%2Fosprey/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibuilder%2Fosprey/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ibuilder","download_url":"https://codeload.github.com/ibuilder/osprey/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibuilder%2Fosprey/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36050896,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-29T02:00:04.910Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","construction","fastapi","open-source","python","real-estate","rust","self-hosted","tauri"],"created_at":"2026-07-29T22:01:20.235Z","updated_at":"2026-07-29T22:01:20.975Z","avatar_url":"https://github.com/ibuilder.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Osprey\n\n\u003e **The foreman that never sleeps.**\n\n[![CI](https://github.com/ibuilder/osprey/actions/workflows/ci.yml/badge.svg)](https://github.com/ibuilder/osprey/actions/workflows/ci.yml)\n[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-0E1A2B.svg)](LICENSE)\n\u0026nbsp;·\u0026nbsp; [**Website**](https://ibuilder.github.io/osprey/)\n\nEvery project buries the thing that matters under a thousand emails, RFIs, submittals,\nchange orders, invoices, and calendar invites — spread across systems that don't talk\nto each other. **Osprey watches all of them at once and hands you the five things that\nactually need you today** — with the reason why, the dollars and schedule at stake, the\ndeadline, the source, and the recommended next move.\n\nIt's **free, open source, and runs on your own server**, so your project data never\nleaves your control. No seat licenses. No vendor lock-in.\n\n### What you get\n\n- **One prioritized hotlist** across all your sources — Outlook, Gmail, Procore,\n  calendars, and a catch-all *forward-an-email / drop-a-CSV* fallback for everything else.\n- **Every item explains itself** — why it ranked where it did, the $ exposure, the\n  deadline, links back to the source, and a concrete next action. No black box.\n- **Contract notice deadlines weighted highest** — miss one and you can waive a claim\n  worth more than the whole fee. Osprey is built to never let that happen quietly.\n- **🔴 Act today / 🟠 This week / 🟡 Watch** buckets, and one-click **Excel + PDF export**\n  for your OAC meeting.\n- **Ask your own AI** to sift the project (\"flag anything about liquidated damages\") and\n  push what it finds straight onto the hotlist — using *your* Claude/OpenAI key.\n- **Private by design** — self-hosted; least-privilege, read-only access to your accounts;\n  tokens encrypted; nothing routed through a third party.\n\n### See it work in 30 seconds\n\n```bash\ncd backend \u0026\u0026 python -m osprey.seed\n```\n\n```\n  Tower B — 8 items, $279,000 exposure\n\n  1. [ACT TODAY] [83] NOTICE OF DELAY — differing site conditions   - $180,000\n  2. [ACT TODAY] [74] Safety observation — missing fall protection at level 3\n  3. [THIS WEEK] [64] PCO-088 — slab thickening at loading dock     - $45,000\n  4. [THIS WEEK] [54] RFI-0500 — curtain wall anchor spacing at grid C-4\n  5. [THIS WEEK] [51] Pay Application 07 — retention release         - $54,000\n  ...                                            → demo/hotlist.xlsx · demo/hotlist.pdf\n```\n\n### The two pieces\n\n- **The brain** (this repo, `backend/`) — the always-on service that does the watching,\n  ranking, and exporting. Runs on a spare machine, a small server, or your own laptop.\n- **The apps** (`clients/`) — a desktop app (system-tray, live hotlist, connect your\n  accounts) and a mobile viewer. They are **viewers**: they connect to the brain, they\n  don't contain it.\n\n\u003e **So the desktop app needs the brain running somewhere it can reach** — by default\n\u003e `http://localhost:8000`, changeable on the sign-in screen. Installing only the app\n\u003e gets you a sign-in screen with nothing behind it. See [Run it](#run-it) below;\n\u003e a one-installer, nothing-else-required build is on the\n\u003e [roadmap](docs/backlog.md#self-contained-desktop-build-no-separate-backend), not done.\n\n---\n\n## What's built here\n\n| Area | Status |\n|---|---|\n| Monorepo skeleton, config, DB layer, migrations baseline | ✅ |\n| Data model (Org → User → Project → Connection → Signal → Item → Score → Action) | ✅ |\n| Connector framework (ABC + registry) | ✅ |\n| Universal **File-Drop / IMAP / Forward-To** fallback connector | ✅ |\n| Connectors: **Outlook · Gmail · Google Calendar · Procore** (OAuth2 + delta/webhook) | ✅ |\n| **Desktop-app OAuth** — user authorizes each source in their own browser (loopback + PKCE), tokens sealed server-side, never via any AI/MCP layer | ✅ |\n| Engine: cluster → extract → **explainable score** → rank → hotlist | ✅ |\n| AI layer: pluggable (deterministic offline default · Claude · Ollama) | ✅ |\n| **Bring-your-own AI** connection + natural-language **sift → hotlist** (cited findings) | ✅ |\n| **User Python background scripts** (sandboxed) that emit signals into the hotlist | ✅ |\n| Exports: styled Excel + branded PDF from one `HotlistSnapshot` | ✅ |\n| Security: token vault (AES-GCM), RBAC, JWT auth, append-only audit log | ✅ |\n| REST + webhook + **WebSocket (live hotlist)** API (FastAPI) | ✅ |\n| Background workers (ARQ: poll · ingest · score · run-scripts · notify) | ✅ |\n| **Push**: device registration + APNs/FCM/Web-Push sender abstraction | ✅ |\n| Admin console (connection health · audit verify · stats · feature flags) | ✅ |\n| **Tauri 2.0 desktop client** (tray · live hotlist · connect · AI · scripts) + **mobile viewer** scaffold | ✅ |\n| Tests: 101 backend (connector poll-loops, Postgres **RLS isolation proven**, ~79% cov) + **11 desktop UI component tests** | ✅ |\n| docker-compose + **Helm chart** (api · worker · migrations · ingress) | ✅ |\n| CI (9 blocking jobs): Python **3.11/3.12/3.13** · ruff lint+format · mypy · coverage gate · **Postgres+pgvector** (migrations, drift, asyncpg suite) · frontend · **Rust** (fmt/clippy/build) · **Helm lint+render** · **live kind deploy smoke (RLS enforced end-to-end)** · SBOM · pip-audit / npm-audit / Trivy | ✅ |\n\n## Run it\n\n**Docker is optional.** The backend defaults to SQLite, an offline rule-based AI\nprovider, and needs no Redis unless you want scheduled polling — so the smallest way\nto run Osprey is Python and nothing else.\n\n### Option A — just Python (simplest)\n\n```bash\ncd backend\npython -m venv .venv \u0026\u0026 . .venv/Scripts/activate   # (.venv/bin/activate on *nix)\npip install -c constraints.txt -e \".[dev]\"\nuvicorn osprey.main:app                             # http://localhost:8000/docs\n```\n\nThat is enough for the desktop app to sign in, ingest forwarded email/CSV, score, and\nexport. What you *don't* get: background polling of connected sources (that is the\nworker), and Postgres-backed features like pgvector search and DB-enforced tenant\nisolation.\n\n### Option B — the full stack (Docker)\n\n```bash\ncp .env.example .env      # set OSPREY_SECRET_KEY + OSPREY_ENCRYPTION_KEY\ndocker compose up         # api :8000, worker, postgres+pgvector, redis\n```\n\nAdds the background worker (polling, scheduled scripts, subscription renewal),\nPostgres + pgvector, and Redis. This is what production looks like.\n\n### Then the desktop app\n\nGrab an installer from [Releases](https://github.com/ibuilder/osprey/releases) —\nWindows `.exe`/`.msi` and Linux `.deb`/`.rpm`/`.AppImage`. macOS builds need Apple\nsigning certificates that aren't configured yet, so build from source there:\n\n```bash\ncd clients/desktop \u0026\u0026 npm install \u0026\u0026 npm run tauri dev   # needs the Rust toolchain\n```\n\nOn the sign-in screen, point **Backend URL** at wherever you started the brain\n(`http://localhost:8000` by default), then create an account.\n\n\u003e Windows installers are signed with the app's *updater* key, not an Authenticode\n\u003e certificate, so SmartScreen will warn on first run until the project buys one.\n\n## Design principles (the golden rules)\n\n- **Least-privilege, read-only OAuth.** Never store a source-account password.\n- **Encrypt tokens at rest** (AES-256-GCM envelope; OS keychain in local mode).\n- **Idempotent ingestion** — dedupe on `external_id`; pollers use rate-limit + backoff.\n- **Explainable scoring** — every hotlist item shows its factor breakdown and cites\n  source text. No black-box ranking until there's feedback data.\n- **Contractual notice deadlines are weighted highest** — missing one can waive a claim.\n- **Excel and PDF exports derive from the same `HotlistSnapshot`.**\n\nKnown deferrals and their rationale live in [`docs/backlog.md`](docs/backlog.md).\n\nSee [`CLAUDE.md`](CLAUDE.md) for the full agent operating guide and [`SPEC.md`](SPEC.md)\nfor the complete build specification.\n\n## License\n\nCore is **AGPL-3.0** (see [`LICENSE`](LICENSE)). Connector SDK and client libs are\nApache-2.0/MIT. See [`SECURITY.md`](SECURITY.md) for the security posture and\nresponsible-disclosure policy.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fibuilder%2Fosprey","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fibuilder%2Fosprey","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fibuilder%2Fosprey/lists"}