CausalMosaic

CausalMosaic extracts causal mechanisms from unstructured research papers and synthesizes them into verifiable models for high-stakes decision making. It automates the pipeline from paper acquisition to causal querying, enabling researchers, medical professionals, and policy makers to understand causal relationships without manually reading hundreds of sources.

What Does It Do?

1. User defines variables (e.g., "smoking", "lung cancer", "air pollution")
2. System retrieves relevant papers from OpenAlex
3. LLM extracts causal relationships from PDFs
4. Ensemble Bayesian Network is constructed from extracted relationships
5. Users explore the graph and run queries (observational, interventional, counterfactual)

Results show probability distributions with full traceability back to source papers.

---

Key Technologies:

• Frontend: React 19, TypeScript, Vite, Redux Toolkit, Sigma.js (graph rendering), Tailwind CSS
• Backend: FastAPI, MongoDB, OpenAI API, OpenAlex API, Selenium
• Infrastructure: Docker, Nginx (reverse proxy), Certbot (SSL), Keycloak (authentication)

---

Prerequisites

Before you begin, ensure you have:

• Docker & Docker Compose (latest versions)
• Node.js 20+ (for local frontend development)
• Python 3.11+ (for local backend development)
• SSH key access (ed25519) for server deployment
• Git configured with your credentials

---

Project Structure

causalmosaic/
├── frontend/                 # React application
│   ├── src/
│   │   ├── components/      # Reusable UI components
│   │   ├── views/           # Full-page views (login, graph, paper, etc.)
│   │   ├── state/           # Redux slices and store
│   │   ├── services/        # API communication layer
│   │   ├── models/          # TypeScript interfaces
│   │   ├── hooks/           # Custom React hooks
│   │   └── constants/       # Static values (colors, etc.)
│   ├── package.json
│   └── vite.config.ts
│
├── backend/                 # FastAPI application
│   ├── app/
│   │   ├── routers/         # API endpoints
│   │   ├── services/        # Business logic layer
│   │   ├── models/          # Pydantic schemas
│   │   └── utils/           # Helper functions
│   ├── requirements.txt
│   └── main.py
│
├── nginx/                   # Reverse proxy configuration
│   ├── nginx.conf
│   └── certs/               # Local dev certificates
│
├── docs/                    # Documentation (this folder)
│
├── docker-compose.yml       # Local development
├── docker-compose-deploy.yml # Production deployment
├── .env                     # Environment variables (CREATE THIS!)
└── README.md

---

Environment Setup

1. Clone the Repository

git clone <repository-url>
cd causalmosaic

2. Create Your .env File

Copy the default environment template and fill in your credentials:

cp /docs/deployment/.env_default .env

Important: Add .env to your .gitignore! Never commit credentials.

LLM provider

The causal extraction works with any OpenAI-compatible API that supports structured (JSON schema) outputs. For example, Groq's free tier:

OPENAI_BASE_URL=https://api.groq.com/openai/v1
OPENAI_MODEL=openai/gpt-oss-120b
OPENAI_API_KEY=<your Groq API key>

Optional tuning (defaults suit rate-limited free tiers; raise the concurrency for paid APIs):

Variable	Default	Meaning
LLM_MAX_CONCURRENCY	2	Parallel LLM requests across all projects
LLM_MAX_RETRIES	8	Retries per request on rate limits, timeouts and server errors (exponential backoff, honors Retry-After)

If a request still fails after its retries, the project is marked as failed instead of building a graph from incomplete answers.

3. Install Local SSL Certificates

For https://localhost to work, you must trust the development CA:

See docs/CausalMosaic Documentation/6.7 Certificate Configuration for detailed instructions.

---

Running the Application

Full Stack with Docker

# Build and start all services
docker-compose up --build

# Run in detached mode
docker-compose up -d

Access the application:

• Frontend: https://localhost:443
• Backend API: https://localhost/api
• Keycloak Admin: https://localhost/admin

View logs:

docker-compose logs -f backend
docker-compose logs -f frontend

Stop services:

docker-compose down

---

Common Development Tasks

Install Dependencies

Frontend:

cd frontend
npm install

Backend:

cd backend
pip install -r requirements.txt --break-system-packages

Run Tests

Frontend:

cd frontend
npm run prettier:check  # Linting
npm run test           # Jest tests (if configured)

Backend:

cd backend
pytest                 # Unit tests
black --check .        # Code formatting check

Access the Database

Option 1: MongoDB Shell (on server)

ssh causalmosaic@api.causalmosaic.com
mongosh

Option 2: MongoDB Compass (local GUI)

• Set up SSH tunnel to api.causalmosaic.com
• Connect to localhost:27017
• See docs/CausalMosaic Documentation/6.5 MongoDB Development for detailed instructions

Deploy to Production

Deployment is automated via GitLab CI/CD when you push to main or develop:

git push origin main

The pipeline will:

1. Build frontend and backend
2. Run tests
3. Deploy to server (if on main/develop)
4. Provision/renew SSL certificates
5. Restart services

See docs/CausalMosaic Documentation/6.6 CI_CD for pipeline details.

---

Server Access

SSH Access

ssh causalmosaic@api.causalmosaic.com

First-time setup:

1. Generate ed25519 SSH key: ssh-keygen -t ed25519
2. Send public key (~/.ssh/id_ed25519.pub) to admin
3. Wait for provisioning confirmation

See docs/CausalMosaic Documentation/6.2 SSH Server for detailed instructions.

---

Troubleshooting

"Certificate not trusted" error

• Ensure dev-ca.crt is properly imported into your OS trust store
• Restart your browser after importing
• For Firefox: Import separately in browser settings

Docker containers won't start

# Check logs
docker-compose logs

# Remove old containers and rebuild
docker-compose down -v
docker-compose up --build

Frontend can't connect to backend

• Verify .env has VITE_API_URL=https://localhost
• Check nginx is running: docker-compose ps nginx
• Verify certificates are in nginx/certs/

Contributing

1. Create a feature branch: git checkout -b feature/your-feature
2. Make changes and test locally
3. Run linting: npm run prettier:check (frontend) or black . (backend)
4. Commit with clear messages
5. Push and create a merge request
6. Ensure CI pipeline passes

---

License

Lukas Alex Jochim
Jeremy Dix
Yassine El Alami
Len Bioly