<div align="center">
<img src="https://raw.githubusercontent.com/primevalai/onyx-octopus/main/assets/onyx-octopus-avatar.png" alt="Onyx Octopus" width="300">
# Eventuali API Server
</div>
A FastAPI-based REST and Server-Sent Events (SSE) API server for the Eventuali event sourcing system.
## Features
- **Event Management**: Emit and query events across agent, workflow, and system aggregates
- **Real-time Streaming**: Server-Sent Events (SSE) for live event monitoring
- **RESTful API**: Complete REST API with OpenAPI documentation
- **Health Monitoring**: Built-in health checks for API and database
- **CORS Support**: Configurable cross-origin resource sharing
- **CLI Interface**: Simple command-line interface for server management
## Installation
```bash
pip install eventuali-api-server
```
## Quick Start
### Start the server with defaults:
```bash
eventuali-api-server
```
The server will start on `http://127.0.0.1:8765` with Swagger UI available at `/docs`.
### Start with custom configuration:
```bash
eventuali-api-server --host 0.0.0.0 --port 9000 --reload
```
### Environment Variables
All CLI options can also be set via environment variables:
```bash
export HOST=0.0.0.0
export PORT=9000
export RELOAD=true
export LOG_LEVEL=debug
export DATA_DIR=/path/to/events
export CORS_ORIGINS="http://localhost:3000,https://app.example.com"
eventuali-api-server
```
## API Endpoints
### Events
- `POST /events/emit/agent` - Emit agent lifecycle events
- `POST /events/emit/workflow` - Emit workflow lifecycle events
- `POST /events/emit/system` - Emit system lifecycle events
- `GET /events/` - Query events with pagination and filters
- `GET /events/agents/{agent_id}` - Get events for specific agent
- `GET /events/workflows/{workflow_id}` - Get events for specific workflow
- `GET /events/workflows/{workflow_id}/agents` - Get agents in workflow
- `GET /events/stream` - Real-time event stream via SSE
### Health
- `GET /health/` - Overall health check
- `GET /health/database` - Database connection health
### Documentation
- `GET /docs` - Swagger UI documentation
- `GET /openapi.json` - OpenAPI schema
## Event Types
### Agent Events
```json
{
"name": "agent.started",
"attributes": {
"agent_name": "url-cacher",
"message": "Agent started successfully"
},
"aggregate_id": "url-cacher-abc123",
"correlation_id": "workflow-def456",
"causation_id": "parent-agent-789"
}
```
### Workflow Events
```json
{
"name": "workflow.started",
"attributes": {
"user_prompt": "Cache the documentation page"
},
"aggregate_id": "workflow-def456"
}
```
### System Events
```json
{
"name": "session.started",
"attributes": {
"session_type": "interactive"
},
"aggregate_id": "session-ghi789"
}
```
## Configuration
The server can be configured via CLI options, environment variables, or programmatically:
```python
from eventuali_api_server import APIServerConfig, set_config
config = APIServerConfig(
host="0.0.0.0",
port=8765,
data_dir="/custom/events/path",
cors_origins=["https://myapp.com"],
log_level="debug"
)
set_config(config)
```
## Development
### Install for development:
```bash
git clone <repository>
cd eventuali-api-server
pip install -e ".[dev]"
```
### Run tests:
```bash
pytest
```
### Code quality:
```bash
black src/ tests/
flake8 src/ tests/
mypy src/
```
## Integration
The API server integrates with:
- **Eventuali Event Store**: SQLite-based event storage
- **eventuali-mcp-server**: MCP server for Claude Code integration
- **@eventuali/dashboard**: React-based UI dashboard
## License
MIT License - see LICENSE file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "eventuali-api-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "event-sourcing, eventuali, fastapi, real-time, sse",
"author": null,
"author_email": "Primeval AI <noreply@primevalai.com>",
"download_url": "https://files.pythonhosted.org/packages/81/81/9fb277ebe8b59d417cf96839e050289d75ec4af5e1ad533215dcc0cffe07/eventuali_api_server-0.2.2.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n <img src=\"https://raw.githubusercontent.com/primevalai/onyx-octopus/main/assets/onyx-octopus-avatar.png\" alt=\"Onyx Octopus\" width=\"300\">\n \n # Eventuali API Server\n</div>\n\nA FastAPI-based REST and Server-Sent Events (SSE) API server for the Eventuali event sourcing system.\n\n## Features\n\n- **Event Management**: Emit and query events across agent, workflow, and system aggregates\n- **Real-time Streaming**: Server-Sent Events (SSE) for live event monitoring\n- **RESTful API**: Complete REST API with OpenAPI documentation\n- **Health Monitoring**: Built-in health checks for API and database\n- **CORS Support**: Configurable cross-origin resource sharing\n- **CLI Interface**: Simple command-line interface for server management\n\n## Installation\n\n```bash\npip install eventuali-api-server\n```\n\n## Quick Start\n\n### Start the server with defaults:\n\n```bash\neventuali-api-server\n```\n\nThe server will start on `http://127.0.0.1:8765` with Swagger UI available at `/docs`.\n\n### Start with custom configuration:\n\n```bash\neventuali-api-server --host 0.0.0.0 --port 9000 --reload\n```\n\n### Environment Variables\n\nAll CLI options can also be set via environment variables:\n\n```bash\nexport HOST=0.0.0.0\nexport PORT=9000\nexport RELOAD=true\nexport LOG_LEVEL=debug\nexport DATA_DIR=/path/to/events\nexport CORS_ORIGINS=\"http://localhost:3000,https://app.example.com\"\neventuali-api-server\n```\n\n## API Endpoints\n\n### Events\n\n- `POST /events/emit/agent` - Emit agent lifecycle events\n- `POST /events/emit/workflow` - Emit workflow lifecycle events \n- `POST /events/emit/system` - Emit system lifecycle events\n- `GET /events/` - Query events with pagination and filters\n- `GET /events/agents/{agent_id}` - Get events for specific agent\n- `GET /events/workflows/{workflow_id}` - Get events for specific workflow\n- `GET /events/workflows/{workflow_id}/agents` - Get agents in workflow\n- `GET /events/stream` - Real-time event stream via SSE\n\n### Health\n\n- `GET /health/` - Overall health check\n- `GET /health/database` - Database connection health\n\n### Documentation\n\n- `GET /docs` - Swagger UI documentation\n- `GET /openapi.json` - OpenAPI schema\n\n## Event Types\n\n### Agent Events\n\n```json\n{\n \"name\": \"agent.started\",\n \"attributes\": {\n \"agent_name\": \"url-cacher\",\n \"message\": \"Agent started successfully\"\n },\n \"aggregate_id\": \"url-cacher-abc123\",\n \"correlation_id\": \"workflow-def456\",\n \"causation_id\": \"parent-agent-789\"\n}\n```\n\n### Workflow Events\n\n```json\n{\n \"name\": \"workflow.started\", \n \"attributes\": {\n \"user_prompt\": \"Cache the documentation page\"\n },\n \"aggregate_id\": \"workflow-def456\"\n}\n```\n\n### System Events\n\n```json\n{\n \"name\": \"session.started\",\n \"attributes\": {\n \"session_type\": \"interactive\"\n },\n \"aggregate_id\": \"session-ghi789\"\n}\n```\n\n## Configuration\n\nThe server can be configured via CLI options, environment variables, or programmatically:\n\n```python\nfrom eventuali_api_server import APIServerConfig, set_config\n\nconfig = APIServerConfig(\n host=\"0.0.0.0\",\n port=8765,\n data_dir=\"/custom/events/path\",\n cors_origins=[\"https://myapp.com\"],\n log_level=\"debug\"\n)\n\nset_config(config)\n```\n\n## Development\n\n### Install for development:\n\n```bash\ngit clone <repository>\ncd eventuali-api-server\npip install -e \".[dev]\"\n```\n\n### Run tests:\n\n```bash\npytest\n```\n\n### Code quality:\n\n```bash\nblack src/ tests/\nflake8 src/ tests/\nmypy src/\n```\n\n## Integration\n\nThe API server integrates with:\n\n- **Eventuali Event Store**: SQLite-based event storage\n- **eventuali-mcp-server**: MCP server for Claude Code integration \n- **@eventuali/dashboard**: React-based UI dashboard\n\n## License\n\nMIT License - see LICENSE file for details.",
"bugtrack_url": null,
"license": "MIT",
"summary": "FastAPI server for Eventuali event sourcing system with real-time streaming",
"version": "0.2.2",
"project_urls": {
"Bug Reports": "https://github.com/primevalai/eventuali-api-server/issues",
"Documentation": "https://github.com/primevalai/eventuali-api-server#readme",
"Homepage": "https://github.com/primevalai/eventuali-api-server",
"Repository": "https://github.com/primevalai/eventuali-api-server"
},
"split_keywords": [
"event-sourcing",
" eventuali",
" fastapi",
" real-time",
" sse"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "81819fb277ebe8b59d417cf96839e050289d75ec4af5e1ad533215dcc0cffe07",
"md5": "df1c385122d92ff8cf851e25b4ae9e6f",
"sha256": "8aba397b1899c7c8ac47db79d0b736bd9554038ea2ee02ca9c0fa5b601bf2a84"
},
"downloads": -1,
"filename": "eventuali_api_server-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "df1c385122d92ff8cf851e25b4ae9e6f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 12679,
"upload_time": "2025-08-25T20:34:47",
"upload_time_iso_8601": "2025-08-25T20:34:47.758082Z",
"url": "https://files.pythonhosted.org/packages/81/81/9fb277ebe8b59d417cf96839e050289d75ec4af5e1ad533215dcc0cffe07/eventuali_api_server-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-25 20:34:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "primevalai",
"github_project": "eventuali-api-server",
"github_not_found": true,
"lcname": "eventuali-api-server"
}
JSON
