SCOPE is a modular platform for observing, analyzing, and explaining the executions of Multi-Agent Systems (MAS) from OpenTelemetry traces. It ingests raw OTel spans, maps them onto a shared MAS ontology, and enriches each session with analysis such as semantic grouping, anomaly detection, consistency checking, and stateful trajectory evaluation — surfaced through a web dashboard.
- A MAS sends OTel spans to an OTel collector, which stores them (ClickHouse by default, swappable for another backend).
- Once a trace is complete, the SCOPE ingestion pipeline maps the raw spans onto the MAS ontology, producing a structured execution model.
- The session representation is enriched by the analysis workers (semantic grouping, anomaly detection, consistency checking, stateful evaluation, metrics).
- The enriched knowledge graph is served through the API and visualized in the UI, giving explainability and insight into the MAS's inner workings.
| Path | Description |
|---|---|
backend/ |
Python libraries and workers implementing ingestion, normalization, analysis, and the data API. See backend/README.md. |
backend/api |
Unified DB access layer and REST API over the raw OTel spans and the knowledge graph. |
backend/norm |
Normalizes raw OTel traces into structured MAS execution models. |
backend/mce |
Metric computation engine for sessions. |
backend/stateful-evals |
Cost-effective evaluation of a session's trajectory. |
backend/workers |
Standalone workers built on top of the backend libraries. |
ui/ |
React/TypeScript web dashboard for browsing applications, sessions, execution graphs, and live topology. See ui/README.md. |
ontology/ |
The MAS telemetry ontology (Turtle/OWL) and the scope-ontology Python package. See ontology/README.md. |
docs/ |
Documentation site sources (MkDocs), built with mkdocs.yml. |
deploy/ |
Deployment: Helm charts for Kubernetes (deploy/k8s) and a Docker Compose stack (deploy/docker-compose) running the API, UI, workers and supporting infra. |
Each component has its own setup instructions:
- Backend (API, workers, local Docker Compose stack): backend/README.md
- UI (dashboard): ui/README.md
- Ontology (Python package, docs, versioning): ontology/README.md
- Kubernetes deployment: deploy/k8s/charts/scope/README.md
For a fully local stack, see the Docker Compose deployment, which runs the same components as the Helm chart: OTel collector, ClickHouse, RabbitMQ, Neo4j, the ingestion pipeline, the API and the UI.
The documentation site is built from docs/ with mkdocs.yml and published at ioc-project.github.io/scope:
- Overview: what SCOPE is and how it works.
- Ingestion: the telemetry path, normalization and the ontology.
- Analysis: the analysis engines, pipelines, workers and components.
- Platform: the platform, API and UI.
- Tutorials: your first trace, instrument your app and deploy SCOPE.
- Preview locally:
pip install -r docs/requirements.txt && mkdocs serve.
The ontology reference documentation (Widoco and WebVOWL) is generated separately:
- Ontology: ontology/index.md, also published at ioc-project.github.io/scope/ontologies.html
Contributions are welcome — see CONTRIBUTING.md for guidelines, CODE_OF_CONDUCT.md for community standards, and SECURITY.md for reporting vulnerabilities. Maintainers are listed in MAINTAINERS.md.
Licensed under the Apache License 2.0 — see LICENSE for the full text.