eventum-generator/eventum

Purpose and Entry Points

Eventum is a Python synthetic-event generation platform. A configured pipeline schedules inputs, renders or replays events, and fans them out to destinations in live or bulk modes. Primary entry points are CLI commands in eventum/cli/commands/eventum.py, application startup in eventum/app/main.py, and the combined server in eventum/server/main.py. Default application/startup configuration lives in config/eventum.yml and config/startup.yml.

Generator Core and Pipeline

The core builds validated generator configurations, initializes plugins, and executes an input → event → output pipeline. eventum/core/generator.py represents generator construction, eventum/core/executor.py drives execution, and eventum/core/queue.py provides the pipeline buffering boundary. Explicit stages in eventum/core/stages/input_stage.py, eventum/core/stages/event_stage.py, and eventum/core/stages/output_stage.py isolate scheduling, event production, and delivery.

Plugin Architecture

Plugins are the main extension boundary, loaded and registered through eventum/plugins/loader.py and eventum/plugins/registry.py, with common contracts under eventum/plugins/base/plugin.py. Input plugins emit timestamps or work items; examples include cron, HTTP, timer, and statistical time patterns under eventum/plugins/input/plugins/. Event plugins transform inputs into event payloads; template rendering is centered in eventum/plugins/event/plugins/template/plugin.py. Output plugins serialize and deliver generated events under eventum/plugins/output/plugins/.

Scheduling, Event Rendering, and Outputs

Input scheduling supports cron, fixed/static sequences, HTTP-triggered input, linspace, timestamps, timers, and time-pattern distributions, coordinated by eventum/plugins/input/scheduler.py. Template event generation uses Jinja-like templates plus Faker/Mimesis integrations in eventum/plugins/event/plugins/template/modules/. Outputs support stdout, files, HTTP, TCP/UDP, Kafka, ClickHouse, and OpenSearch; representative implementations are eventum/plugins/output/plugins/kafka/plugin.py, eventum/plugins/output/plugins/clickhouse/plugin.py, and eventum/plugins/output/plugins/opensearch/plugin.py. These external systems are integration boundaries rather than internal persistence dependencies.

Application Lifecycle, Workspaces, and Security

Application mode manages multiple independent generator instances, their lifecycle, configuration workspaces, and startup state. Key orchestration components are eventum/app/manager.py, eventum/app/workspace.py, and eventum/app/startup/service.py. The REST-facing application state is separated from engine execution through dependency injection in eventum/api/dependencies/app.py. Credentials/secrets are handled by the encrypted-keyring-oriented security layer in eventum/security/manage.py and eventum/security/auth.py.

Server, REST API, and Studio

The server composes API, MCP, and static UI services, with lifecycle/shutdown coordination in eventum/server/main.py and eventum/server/shutdown.py. The REST API is assembled in eventum/api/main.py; routers expose generators, instances, previews, scenarios, secrets, startup state, and auth, notably eventum/api/routers/generators/routes.py, eventum/api/routers/preview/routes.py, and eventum/api/routers/scenarios/routes.py. The bundled Eventum Studio is a TypeScript/React/Vite frontend rooted at eventum/ui/src/main.tsx, with API client bindings in eventum/ui/src/api/client.ts and project editing workspace in eventum/ui/src/pages/ProjectPage/.

MCP and Operational Interfaces

An MCP server gives AI assistants controlled access to authoring, live operation, previews, scenarios, secrets, and workspace files. Its server and context boundary are eventum/mcp/server.py and eventum/mcp/context.py; callable capabilities are grouped in eventum/mcp/tools/. Server-side MCP injection and authentication are isolated in eventum/server/services/mcp/injector.py and eventum/server/services/mcp/auth.py. Docker deployment is defined by Dockerfile; integration infrastructure includes ClickHouse, Kafka, and OpenSearch in tests/docker/docker-compose.yml.