hi-day/multi_tower

Purpose and entry points

Multi-Tower is a Python 3.12 event recommendation engine intended to learn user and event representations and return top-N recommendations. It exposes both online and offline-facing interface shells:

• FastAPI application: src/multi_tower/interfaces/api/main.py

• CLI application: src/multi_tower/interfaces/cli/main.py

• Standalone inference/proof-of-concept scripts: infer.py, poc_multi_tower.py

Architectural style

The repository follows Clean Architecture with dependency direction from interfaces and infrastructure toward application/domain. The domain is intended to remain framework-independent; application defines orchestration contracts; infrastructure supplies model and storage implementations; interfaces adapt requests/commands.

• Domain boundary: src/multi_tower/domain/entities, src/multi_tower/domain/repositories

• Application boundary: src/multi_tower/application/use_cases, src/multi_tower/application/ports

• Adapters: src/multi_tower/infrastructure, src/multi_tower/interfaces

Data ingestion and quality gate

Raw recommendation inputs are maintained as bronze CSV data: student profiles, majors, events, and interactions. The data module loads, validates, schemas, and constants before downstream training/inference should consume records.

• Source data: data/bronze/student_profile.csv, data/bronze/event_master.csv, data/bronze/interaction.csv

• Data pipeline components: src/multi_tower/data/loader.py, src/multi_tower/data/validator.py, src/multi_tower/data/schemas.py

• Synthetic-data path: scripts/generate_dummy_data.py, src/multi_tower/data/generator.py

Domain and application orchestration

Core business concepts are Users, Events, and Interactions, represented through entities/value objects and abstract repository contracts. Application use cases coordinate these concepts through DTOs and ports rather than directly coupling API or model code to storage.

• Domain model locations: src/multi_tower/domain/entities, src/multi_tower/domain/value_objects

• Repository abstractions: src/multi_tower/domain/repositories

• Use-case and boundary definitions: src/multi_tower/application/use_cases, src/multi_tower/application/dtos, src/multi_tower/application/ports

Recommendation/model infrastructure

The intended model is a PyTorch multi-tower network: separate learned representations for users and events are jointly used for relevance scoring/ranking. Infrastructure owns concrete ML and persistence concerns and should implement application-defined ports, keeping model lifecycle out of interfaces.

• Model boundary: src/multi_tower/infrastructure/model

• Persistence boundary: src/multi_tower/infrastructure/persistence

• Prototype model implementation: poc_multi_tower.py

• Inference invocation: infer.py

Serving and execution flow

For online serving, requests enter FastAPI routes, are validated by API schemas, dispatched to application use cases, then resolved through infrastructure implementations to retrieve data and score/rank events. The CLI provides a parallel non-HTTP entry point for offline evaluation or operations.

• API composition: src/multi_tower/interfaces/api/main.py, src/multi_tower/interfaces/api/routes

• API request/response boundary: src/multi_tower/interfaces/api/schemas

• Offline command entry: src/multi_tower/interfaces/cli/main.py

Material runtime and storage choices

The runtime is Python with PyTorch for neural recommendation and Polars-oriented data handling, especially Parquet-capable persistence at scale. Configuration is expected through environment variables and Pydantic Settings; .env.example documents the environment boundary. No deployed cloud, database, queue, or external recommendation service is represented in the repository tree.

• Environment template: .env.example

• Package/runtime declaration: pyproject.toml

• Data/persistence implementation area: src/multi_tower/infrastructure/persistence