Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 1 addition & 7 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,8 @@ AUTH_TOKEN=change-me
JWT_SECRET=change-me-jwt
JWT_ALGORITHM=HS256
ACCESS_TOKEN_MINUTES=120
OPENAI_API_KEY=
SMTP_HOST=localhost
SMTP_PORT=1025
SMTP_FROM=noreply@aetherius.local
SMTP_USE_TLS=false
AETHERIUS_ENABLE_TTC=true
AETHERIUS_MODEL_NAME=gpt-4o-mini
AETHERIUS_API_KEY=
AETHERIUS_API_BASE_URL=https://api.openai.com/v1
AETHERIUS_API_TIMEOUT_SECONDS=45

SEC_USER_AGENT="Aetherius Research you@example.com"
4 changes: 1 addition & 3 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -19,9 +19,7 @@ jobs:
python -m pip install --upgrade pip
pip install -r requirements.txt
- name: Lint with ruff
run: |
pip install ruff
ruff check aetherius
run: ruff check aetherius simulations scripts
- name: Run pytest test suite
run: |
pytest -v aetherius/tests
12 changes: 7 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-green.svg)](https://www.python.org/)
[![Tests: 76 passed](https://img.shields.io/badge/Tests-76%20passed-success.svg)](aetherius/tests/)
[![Tests: 102 passed](https://img.shields.io/badge/Tests-102%20passed-success.svg)](aetherius/tests/)
[![Backtest Recall: 9/9](https://img.shields.io/badge/Backtest%20Recall-100%25%20(9%2F9)-informational.svg)](docs/working_paper/detection_timing_backtest_2026-07.md)

---
Expand Down Expand Up @@ -76,8 +76,8 @@ Aetherius was validated by replaying 161 real historical news observations acros
### 1. Install Dependencies

```bash
git clone https://github.com/zariffromlatif/Aetherius.git
cd Aetherius
git clone https://github.com/zariffromlatif/Aetherius-Risk-Intelligence.git
cd Aetherius-Risk-Intelligence
pip install -r requirements.txt
```

Expand Down Expand Up @@ -126,8 +126,10 @@ aetherius/
entity_mapping/ # Regex and acronym disambiguation
scoring/ # Deterministic risk & urgency formulas
signals/ # Downside signal taxonomy
delivery/ # PDF rendering & regulatory quality gates
tests/ # 76-test unit & integration test suite
delivery/ # PDF rendering, regulatory quality gates & retries
pipeline/ # Observation -> evidence -> signal flow shared by API & workers
workers/ # Celery beat: hourly EDGAR/GDELT ingestion, briefs, retries, retention
tests/ # 102-test unit & integration test suite
simulations/
backtest/
events/ # Frozen crisis fixtures (SVB, Wirecard, FTX)
Expand Down
24 changes: 24 additions & 0 deletions aetherius/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,30 @@ python -m alembic upgrade head

All protected routes require bearer authentication and role checks.

Client-scoped endpoints (reporting, delivery) allow admins on every client and
other operators only on clients assigned to them:

- Assign: `POST /api/v1/auth/assignments` (admin) with `operator_user_id`, `client_id`
- Unassign: `DELETE /api/v1/auth/assignments/{assignment_id}` (admin)

Delivering a brief requires `admin`, or an `analyst` assigned to that client.

## Scheduled Jobs (Celery beat)

| Job | Schedule | What it does |
| --- | --- | --- |
| `ingest_watchlist_sources` | hourly at :05 | EDGAR filings + 24h GDELT news per active ticker -> evidence -> signals |
| `briefing_daily_sweep` | 08:00 | Draft a daily brief per client for review |
| `briefing_weekly_sweep` | Mon 09:00 | Draft a weekly summary per client for review |
| `delivery_retry_failed` | every 5 min | Re-attempt failed deliveries (re-running every gate) with 5/10/20 min backoff |
| `dead_letter_requeue` | every 15 min | Move deliveries that exhausted retries to `dead_letter` |
| `observability_health_alerts` | every 10 min | Log a warning when failed/dead-letter/pending-review counts cross thresholds |
| `retention_archive_cleanup` | 02:00 | Mark observations older than 180 days `archived` (rows are kept for audit) |

Signals are only raised automatically for evidence that would ship
(elevated/high severity *and* adverse language in the source), using the same
scoring as `simulations/backtest/run_backtest.py`.

## Delivery Modes

- Local: Mailpit SMTP (`localhost:1025`, UI `http://localhost:8025`)
Expand Down
1 change: 0 additions & 1 deletion aetherius/alembic/versions/0001_initial.py
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,6 @@

from alembic import op


revision = "0001_initial"
down_revision = None
branch_labels = None
Expand Down
21 changes: 21 additions & 0 deletions aetherius/alembic/versions/0002_operator_client_assignments.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
"""operator client assignments

Revision ID: 0002_operator_client_assignments
Revises: 0001_initial
Create Date: 2026-10-16
"""

from alembic import op

revision = "0002_operator_client_assignments"
down_revision = "0001_initial"
branch_labels = None
depends_on = None


def upgrade() -> None:
op.execute(open("migrations/002_operator_client_assignments.sql", "r", encoding="utf-8").read())


def downgrade() -> None:
op.execute("DROP TABLE IF EXISTS operator_client_assignments")
43 changes: 34 additions & 9 deletions aetherius/app/api/deps.py
Original file line number Diff line number Diff line change
@@ -1,9 +1,12 @@
import uuid

import jwt
from fastapi import Depends, Header, HTTPException, status
from sqlalchemy.orm import Session

from app.core.config import settings
from app.db.session import get_db
from app.models.entities import OperatorClientAssignments


def db_dep() -> Session:
Expand All @@ -30,17 +33,39 @@ def require_admin(claims: dict = Depends(require_operator)) -> dict:
return claims


def require_client_scope(client_id: str, claims: dict = Depends(require_operator)) -> dict:
# Authority is derived from the authenticated operator, never from a
# client-supplied header. Admins may act across all clients.
#
# NOTE: This is correct for a single trusted operator team. When outside
# analysts are onboarded, replace the role check below with a lookup
# against an operator_client_assignments table (operator_id, client_id)
# and verify membership here.
def operator_can_access_client(db: Session, claims: dict, client_id: str) -> bool:
"""Admins may act on every client; others only on clients assigned to them."""
if claims.get("role") == "admin":
return True
operator_id = claims.get("sub")
if not operator_id:
return False
try:
operator_uuid = uuid.UUID(str(operator_id))
client_uuid = uuid.UUID(str(client_id))
except ValueError:
return False
return (
db.query(OperatorClientAssignments)
.filter(
OperatorClientAssignments.operator_user_id == operator_uuid,
OperatorClientAssignments.client_id == client_uuid,
)
.first()
is not None
)


def require_client_scope(
client_id: str,
claims: dict = Depends(require_operator),
db: Session = Depends(get_db),
) -> dict:
# Authority is derived from the authenticated operator and the
# operator_client_assignments table, never from a client-supplied header.
if operator_can_access_client(db, claims, client_id):
return claims
raise HTTPException(
status_code=status.HTTP_403_FORBIDDEN,
detail="Cross-client action requires admin role",
detail="Operator is not assigned to this client",
)
44 changes: 41 additions & 3 deletions aetherius/app/api/routers/auth.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,15 @@
from sqlalchemy.orm import Session

from app.api.deps import get_db, require_admin
from app.schemas.auth import LoginRequest, OperatorCreate, OperatorOut, TokenResponse
from app.models.entities import Clients, OperatorClientAssignments, OperatorUsers
from app.schemas.auth import (
ClientAssignmentCreate,
ClientAssignmentOut,
LoginRequest,
OperatorCreate,
OperatorOut,
TokenResponse,
)
from app.services.auth.service import authenticate_operator, create_access_token, create_operator

router = APIRouter(prefix="/auth", tags=["auth"])
Expand All @@ -23,9 +31,39 @@ def create_operator_endpoint(payload: OperatorCreate, db: Session = Depends(get_

@router.post("/bootstrap-admin", response_model=OperatorOut)
def bootstrap_admin(payload: OperatorCreate, db: Session = Depends(get_db)):
from app.models.entities import OperatorUsers

existing = db.query(OperatorUsers).count()
if existing > 0:
raise HTTPException(status_code=403, detail="Bootstrap disabled after first operator exists")
return create_operator(db, email=payload.email, password=payload.password, role="admin", full_name=payload.full_name)


@router.post("/assignments", response_model=ClientAssignmentOut, dependencies=[Depends(require_admin)])
def create_assignment_endpoint(payload: ClientAssignmentCreate, db: Session = Depends(get_db)):
if not db.query(OperatorUsers).filter(OperatorUsers.id == payload.operator_user_id).first():
raise HTTPException(status_code=404, detail="Operator not found")
if not db.query(Clients).filter(Clients.id == payload.client_id).first():
raise HTTPException(status_code=404, detail="Client not found")
existing = (
db.query(OperatorClientAssignments)
.filter(
OperatorClientAssignments.operator_user_id == payload.operator_user_id,
OperatorClientAssignments.client_id == payload.client_id,
)
.first()
)
if existing:
return existing
row = OperatorClientAssignments(operator_user_id=payload.operator_user_id, client_id=payload.client_id)
db.add(row)
db.commit()
db.refresh(row)
return row


@router.delete("/assignments/{assignment_id}", status_code=204, dependencies=[Depends(require_admin)])
def delete_assignment_endpoint(assignment_id: str, db: Session = Depends(get_db)):
row = db.query(OperatorClientAssignments).filter(OperatorClientAssignments.id == assignment_id).first()
if not row:
raise HTTPException(status_code=404, detail="Assignment not found")
db.delete(row)
db.commit()
14 changes: 6 additions & 8 deletions aetherius/app/api/routers/delivery.py
Original file line number Diff line number Diff line change
@@ -1,10 +1,8 @@
from fastapi import APIRouter, Depends
from fastapi import APIRouter, Depends, HTTPException
from pydantic import BaseModel, EmailStr
from sqlalchemy.orm import Session

from fastapi import HTTPException

from app.api.deps import get_db, require_operator
from app.api.deps import get_db, operator_can_access_client, require_operator
from app.models.entities import BriefingRuns, Deliveries
from app.services.delivery.service import deliver_briefing, retry_failed_delivery

Expand All @@ -24,10 +22,10 @@ def deliver_briefing_endpoint(
db: Session = Depends(get_db),
):
run = db.query(BriefingRuns).filter(BriefingRuns.id == briefing_run_id).one()
# Sending a client's brief is an admin-only action. Non-admins cannot
# deliver across clients (no spoofable header).
if claims.get("role") != "admin":
raise HTTPException(status_code=403, detail="Delivery requires admin role")
# Sending a client's brief needs an admin, or an analyst assigned to that
# client. Viewers never send. Authority comes from the token, never a header.
if claims.get("role") not in {"admin", "analyst"} or not operator_can_access_client(db, claims, str(run.client_id)):
raise HTTPException(status_code=403, detail="Delivery requires admin or an analyst assigned to this client")
return deliver_briefing(db, briefing_run_id=briefing_run_id, recipient=payload.recipient, channel=payload.channel)


Expand Down
8 changes: 3 additions & 5 deletions aetherius/app/api/routers/observations.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@

from app.api.deps import get_db, require_operator
from app.models.entities import SourceObservations
from app.services.entity_mapping.service import extract_entities, map_to_watchlist, persist_entities
from app.services.ingestion.service import ingest_observation
from app.services.pipeline.service import process_observation

router = APIRouter(prefix="/observations", tags=["observations"], dependencies=[Depends(require_operator)])

Expand Down Expand Up @@ -38,10 +38,8 @@ def create_observation_endpoint(payload: ObservationCreate, db: Session = Depend
)
if observation is None:
return {"deduped": True}
entities = extract_entities(payload.raw_text)
persist_entities(db, observation.id, entities)
links = map_to_watchlist(db, observation)
return {"deduped": False, "observation_id": str(observation.id), "evidence_links_created": len(links)}
result = process_observation(db, observation)
return {"deduped": False, "observation_id": str(observation.id), **result}


@router.get("")
Expand Down
10 changes: 9 additions & 1 deletion aetherius/app/api/routers/operator_console.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,15 @@
from sqlalchemy.orm import Session

from app.api.deps import get_db, require_operator
from app.models.entities import BriefingRuns, Clients, Deliveries, RiskSignals, SourceObservations, WatchlistItems, Watchlists
from app.models.entities import (
BriefingRuns,
Clients,
Deliveries,
RiskSignals,
SourceObservations,
WatchlistItems,
Watchlists,
)

template_dir = Path(__file__).resolve().parents[2] / "templates" / "console"
templates = Jinja2Templates(directory=str(template_dir))
Expand Down
1 change: 1 addition & 0 deletions aetherius/app/api/routers/ops.py
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
def metrics(db: Session = Depends(get_db)):
return {
"failed_deliveries": db.query(func.count(Deliveries.id)).filter(Deliveries.delivery_status == "failed").scalar() or 0,
"dead_letter_deliveries": db.query(func.count(Deliveries.id)).filter(Deliveries.delivery_status == "dead_letter").scalar() or 0,
"pending_reviews": db.query(func.count(BriefingRuns.id)).filter(BriefingRuns.status == "pending_review").scalar() or 0,
"stale_observations": db.query(func.count(SourceObservations.id)).filter(SourceObservations.stale.is_(True)).scalar() or 0,
}
2 changes: 0 additions & 2 deletions aetherius/app/core/config.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,6 @@ class Settings(BaseSettings):
smtp_password: str | None = None
smtp_from: str = "noreply@aetherius.local"
smtp_use_tls: bool = False
openai_api_key: str | None = None
openai_model: str = "gpt-4o-mini"
sec_user_agent: str = "Aetherius Research zarif@aetheriusresearch.tech"
auth_token: str = "change-me"
jwt_secret: str = "change-me-jwt"
Expand Down
13 changes: 12 additions & 1 deletion aetherius/app/main.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,18 @@

from fastapi import FastAPI, Request

from app.api.routers import auth, clients, delivery, observations, operator_console, ops, reporting, review, signals, watchlists
from app.api.routers import (
auth,
clients,
delivery,
observations,
operator_console,
ops,
reporting,
review,
signals,
watchlists,
)
from app.core.config import settings
from app.utils.logging import configure_logging, correlation_id_var

Expand Down
18 changes: 13 additions & 5 deletions aetherius/app/models/entities.py
Original file line number Diff line number Diff line change
@@ -1,15 +1,12 @@
import uuid
from datetime import datetime

from sqlalchemy import Boolean, CheckConstraint, DateTime, ForeignKey, Integer, Numeric, Text, Time
from sqlalchemy import Boolean, CheckConstraint, DateTime, ForeignKey, Integer, Numeric, Text, Time, UniqueConstraint
from sqlalchemy.dialects.postgresql import JSONB, UUID
from sqlalchemy.orm import Mapped, mapped_column

from app.db.base import Base


def utcnow() -> datetime:
return datetime.utcnow()
from app.utils.time import utcnow


class Clients(Base):
Expand Down Expand Up @@ -37,6 +34,17 @@ class OperatorUsers(Base):
updated_at: Mapped[datetime] = mapped_column(DateTime, nullable=False, default=utcnow, onupdate=utcnow)


class OperatorClientAssignments(Base):
"""Which clients a non-admin operator may act on. Admins bypass this table."""

__tablename__ = "operator_client_assignments"
__table_args__ = (UniqueConstraint("operator_user_id", "client_id", name="uq_operator_client"),)
id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
operator_user_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("operator_users.id"), nullable=False)
client_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("clients.id"), nullable=False)
created_at: Mapped[datetime] = mapped_column(DateTime, nullable=False, default=utcnow)


class ClientConfigs(Base):
__tablename__ = "client_configs"
id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
Expand Down
Loading
Loading