Mirror of https://github.com/roostorg/osprey
github.com/roostorg/osprey
1# ROOST - Osprey
2
3<img width="200" height="64" alt="Copy of ROOST-Mark-Yellow" src="/images/ROOST-Horizontal-Yellow.png" />
4
5# Welcome to Osprey
6
7<img alt="Osprey UI Sample" src="./images/query-and-charts.png" />
8
9
10## Overview
11
12This repository is home to one of ROOST’s safety tools, the Osprey rules engine. Osprey is an open-source event stream decisions engine and analysis UI designed to investigate and take automatic action on events and their properties as they happen in real-time. Originally developed internally at [Discord](https://discord.com/) to combat spam, abuse, botting, and scripting across its platform, Osprey has now been open-sourced to help other platforms facing similar challenges.
13
14Osprey is a library for processing actions through human-written rules and outputting verdicts & custom effects back to configurable output sinks. It evaluates events using structured rule logic (SML) that is extendable via user-defined functions (UDFs). Osprey can also track state across events by labelling entities if implementers provide a labels service backend (see [labels_service.py](./example_plugins/src/services/labels_service.py) for a Postgres-backed labels service example)
15
16This 'Rules \+ Investigation' tool is able to:
17
18- take action based on user behavior
19- combine actions with human written rules
20- let operators query human actions and past decisions
21- perform investigations or write new rules based on decisions
22
23## v0 Release Notes
24The v0 release is built for engineers and Trust & Safety teams who want to explore, test, and integrate Osprey's core capabilities into their platform for incident response and Trust & Safety investigation.
25
26Some UI features have been planned for the v1 release to ensure a solid foundation for experimentation:
27
28- **Bulk actions** - Mass investigation and response operations through the UI
29- **Labels** - Visual entity tagging and categorization systems in the interface
30- **Event stream in UI** - Real-time event monitoring and alert dashboard
31- **Load Balancing** - Better performance efficiency and management of sync/async rules
32
33### Feedback Wanted
34This is a working system, not a prototype. Try it locally, connect your data, write some rules, and tell us what's missing for your use case. We're particularly interested in:
35
36- Integration challenges with your existing platform infrastructure
37- Performance characteristics with your event volumes and rule complexity
38- Missing detection capabilities or response actions you need
39- API improvements that would make adoption easier for your team
40
41Your experimentation feedback will directly shape v1 priorities and help us build the most useful Trust & Safety tooling for the community.
42
43## Join Us
44Writing code is not the only way to help the project. Reviewing pull requests, answering questions to help others on mailing lists or issues, providing feedback from a domain expert perspective, organizing and teaching tutorials, working on the website, improving the documentation, are all priceless contributions.
45
46- Join us on [Discord server](https://discord.gg/5Csqnw2FSQ)
47- Join our [newsletter](https://roost.tools/#get-started) for more announcements and information
48- Follow us on [Bluesky](https://bsky.app/profile/roost.tools) or [LinkedIn](https://www.linkedin.com/company/roost-tools/)
49
50_ROOST (Robust Open Online Safety Tools), a non-profit organization that brings together expertise, resources, and investments from major technology companies and philanthropies to build scalable, interoperable safety infrastructure for the AI era._
51
52## 🚀 Quick Start
53
54### Prerequisites
55
56- Python 3.11 or higher
57- Git
58- [uv](https://docs.astral.sh/uv/) (Python package manager) or python package manager of choice
59
60### Installation
61
621. **Clone the repository:**
63
64 ```bash
65 git clone git@github.com:roostorg/osprey.git
66 cd osprey
67 ```
68
692. **Install dependencies using uv:**
70
71 ```bash
72 uv sync
73 ```
74
753. **Set up development tools:**
76
77 ```bash
78 uv run pre-commit install
79 ```
80
814. **Verify setup:**
82
83 ```bash
84 # Test linting
85 uv run ruff check
86 uv run mypy .
87
88 # Test formatting
89 uv run ruff format --diff
90
91 # Test pre-commit hooks
92 uv run pre-commit run --all-files
93
945. **Start Services:**
95
96 ```bash
97 docker compose up -d
98 ```
99
100 or using the wrapper script
101
102 ```bash
103 ./start.sh
104 ```
105
106 this starts the osprey-worker on its own along with all its required dependencies.
107
108 alternatively, you can start Osprey with `osprey-coordinator`, refer to the [Coordinator README](./example_docker_compose/run_osprey_with_coordinator/README.md) for more information
109
1106. (Optional) **Port Forward the UI/UI API:**
111
112 If you are running the docker compose on a headless machine, you will need to port forward the UI and UI API.
113 Namely, ports `5002` (UI) and `5004` (UI API). Then, you can connect via http://localhost:5002/ :D
114
115
116### Development Workflow
117
118- See [DEVELOPMENT.md](./docs/DEVELOPMENT.md) for comprehensive development setup and workflow documentation
119- All code changes should pass linting (Ruff) and type checking (MyPy)
120- Pre-commit hooks automatically run on each commit to maintain code quality
121
122
123## Recognition
124Discord uses Osprey to quickly detect and remove new types of harm that put users at risk. Rather than leaving other platforms to build similar tools from scratch, ROOST and Discord have open-sourced this powerful rule engine in collaboration with [internet.dev](https://internet.dev/) to make it available for anyone who needs it.