sacs 0.1.0__py3-none-any.whl

sacs/__init__.py

@@ -0,0 +1,12 @@
+"""SACS - Smart Academic Coordination System.
+
+A real-time, multi-tenant school coordination platform. The package ships a
+Python CLI (``sacs``) that launches a complete local demonstration with five
+simultaneously usable browser workspaces backed by one shared service.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

sacs/alembic.ini

@@ -0,0 +1,40 @@
+[alembic]
+script_location = sacs/migrations
+prepend_sys_path = .
+version_path_separator = os
+# Overridden programmatically by sacs.db; present for manual `alembic` use.
+sqlalchemy.url = sqlite:///./_migrate_tmp.db
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARNING
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARNING
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

sacs/app.py

@@ -0,0 +1,97 @@
+"""FastAPI application factory for SACS."""
+
+from __future__ import annotations
+
+import asyncio
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from . import __version__
+from .config import get_settings
+from .db import get_sessionmaker
+from .events import background_dispatcher
+from .scheduler import bell_loop
+
+from .routers import auth as auth_router
+from .routers import academics as academics_router
+from .routers import bell as bell_router
+from .routers import platform as platform_router
+from .routers import realtime as realtime_router
+from .routers import requests as requests_router
+from .routers import schools as schools_router
+from .routers import timetable as timetable_router
+
+
+def cors_urls() -> list[str]:
+    settings = get_settings()
+    origins = list(settings.cors_origins)
+    if settings.env in ("demo", "dev"):
+        origins = ["*"]
+    return origins
+
+
+def create_app() -> FastAPI:
+    settings = get_settings()
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        session_factory = get_sessionmaker()
+        tasks = [
+            bell_loop(session_factory),
+            background_dispatcher(session_factory),
+        ]
+        for task in tasks:
+            app.state.tasks.append(asyncio.create_task(task))
+        yield
+        for task in app.state.tasks:
+            task.cancel()
+        await asyncio.gather(*app.state.tasks, return_exceptions=True)
+
+    app = FastAPI(
+        title="SACS - Smart Academic Coordination System",
+        version=__version__,
+        description="Multi-tenant academic coordination platform: one shared backend, "
+        "isolated school tenants, real-time delivery, and a software bell scheduler.",
+        lifespan=lifespan,
+    )
+    app.state.tasks = []
+
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=cors_urls(),
+        allow_credentials=False,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    app.include_router(schools_router.accept_router)
+    app.include_router(auth_router.router)
+    app.include_router(platform_router.router)
+    app.include_router(schools_router.router)
+    app.include_router(academics_router.router)
+    app.include_router(timetable_router.router)
+    app.include_router(requests_router.router)
+    app.include_router(bell_router.router)
+    app.include_router(bell_router.test_router)
+    app.include_router(realtime_router.router)
+
+    @app.get("/api/health", tags=["system"])
+    def public_health() -> dict:
+        return {"status": "ok", "service": "sacs", "version": __version__}
+
+    @app.get("/", include_in_schema=False)
+    def root() -> dict:
+        return {
+            "service": "sacs",
+            "version": __version__,
+            "docs": "/docs",
+            "health": "/api/health",
+            "note": "No browser frontend is shipped; the SACS CLI is the interface.",
+        }
+
+    return app
+
+
+__all__ = ["create_app"]

sacs/audit.py

@@ -0,0 +1,55 @@
+"""Audit event recording.
+
+Audit events are written inside the same transaction as the change they
+describe, so a committed business action always carries an auditable record.
+School-scoped records carry a ``school_id``; platform-level records do not.
+"""
+
+from __future__ import annotations
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session as OrmSession
+
+from .models import AuditEvent, utcnow
+
+
+def record(
+    db: OrmSession,
+    *,
+    school_id: str | None,
+    actor_user_id: str | None,
+    actor_role: str | None,
+    action: str,
+    summary: str,
+    entity_type: str | None = None,
+    entity_id: str | None = None,
+    meta: dict | None = None,
+) -> str:
+    event = AuditEvent(
+        school_id=school_id,
+        actor_user_id=actor_user_id,
+        actor_role=actor_role,
+        action=action,
+        summary=summary,
+        entity_type=entity_type,
+        entity_id=entity_id,
+        meta=meta or {},
+    )
+    db.add(event)
+    db.flush()
+    return event.id
+
+
+def list_events(
+    db: OrmSession,
+    *,
+    school_id: str | None = None,
+    platform: bool = False,
+    limit: int = 100,
+) -> list[AuditEvent]:
+    stmt = select(AuditEvent).order_by(AuditEvent.created_at.desc())
+    if platform:
+        stmt = stmt.where(AuditEvent.school_id.is_(None))
+    elif school_id is not None:
+        stmt = stmt.where(AuditEvent.school_id == school_id)
+    return list(db.execute(stmt.limit(limit)).scalars().all() or [])