Sci-Agent Hub

Multi-agent scientific computing platform for quantum chemistry simulations. Users submit molecular calculation tasks; AI agents simulate DFT calculations and stream analysis via Claude.

---

Architecture

User ──► API (FastAPI :8000)
          ├── POST /auth/register|login      → JWT auth
          ├── POST /tasks/submit             → Celery queue → Redis
          ├── GET  /tasks/{id}               → task status + result
          ├── WS   /chat/{session_id}        → Claude streaming chat
          └── GET  /molecules/search         → pgvector similarity search

          PostgreSQL + pgvector
            ├── users
            ├── tasks (id, status, result, user_id)
            └── molecule_embeddings (pgvector for RAG)

Redis (queue + pub/sub)

Worker (Celery)
  ├── simulate_quantum_calc   → mock DFT: sleep + realistic output
  ├── run_analysis_agent      → Claude: interpret quantum output
  └── store_embedding         → pgvector: store for future RAG

---

Quick Start

1. Clone and configure

git clone https://github.com/your-org/sci-agent-hub-platform
cd sci-agent-hub-platform
cp .env.example .env
# Edit .env — set ANTHROPIC_API_KEY at minimum

2. Run with Docker Compose

docker compose up --build

Services:

• API: http://localhost:8000
• Docs: http://localhost:8000/docs
• Postgres: localhost:5432
• Redis: localhost:6379

3. Run tests

pip install -r api/requirements.txt pytest pytest-asyncio httpx aiosqlite
pytest api/tests/ -v

4. Lint

pip install ruff
ruff check . && ruff format --check .

---

API Reference

Method	Path	Auth	Description
POST	/auth/register	—	Register a new user
POST	/auth/login	—	Login, get JWT token
POST	/tasks/submit	JWT	Submit quantum calc task
GET	/tasks/{id}	JWT	Get task status + result
GET	/tasks/	JWT	List your tasks
WS	/chat/{session_id}	JWT (query param)	Real-time AI chat
POST	/molecules/search	JWT	pgvector similarity search
GET	/health	—	Health check

Example: Register and submit a task

# Register
TOKEN=$(curl -s -X POST http://localhost:8000/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","username":"you","password":"password123"}' \
  | jq -r .access_token)

# Submit task
curl -X POST http://localhost:8000/tasks/submit \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"molecule":"H2O","method":"B3LYP/6-31G*","priority":"normal"}'

# Poll result
curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/tasks/{task_id}

WebSocket Chat

const ws = new WebSocket("ws://localhost:8000/chat/my-session?token=<JWT>");
ws.send(JSON.stringify({type: "message", content: "analyze H2O molecule"}));
// Receive: task_submitted → analysis_start → chunk... → done

---

Quantum Simulation Output

Mock DFT returns realistic values:

{
  "molecule": "H2O",
  "method": "B3LYP/6-31G*",
  "total_energy": -76.4102,
  "homo_energy": -0.3745,
  "lumo_energy": 0.1823,
  "homo_lumo_gap": 0.5568,
  "dipole_moment": 1.854,
  "converged": true,
  "iterations": 23
}

---

Deploy Options

Railway (recommended)

# Install CLI
npm install -g @railway/cli

# Deploy
railway login
railway up

Or via Terraform:

cd terraform
terraform init
terraform apply \
  -var="railway_token=$RAILWAY_TOKEN" \
  -var="anthropic_api_key=$ANTHROPIC_API_KEY"

Kubernetes

# Apply all manifests
kubectl apply -f k8s/namespace.yaml
kubectl apply -f k8s/configmap.yaml
kubectl apply -f k8s/secret.yaml   # fill in real values first
kubectl apply -f k8s/postgres-pvc.yaml
kubectl apply -f k8s/postgres-deployment.yaml
kubectl apply -f k8s/postgres-service.yaml
kubectl apply -f k8s/redis-deployment.yaml
kubectl apply -f k8s/redis-service.yaml
kubectl apply -f k8s/api-deployment.yaml
kubectl apply -f k8s/api-service.yaml
kubectl apply -f k8s/api-hpa.yaml
kubectl apply -f k8s/worker-deployment.yaml
kubectl apply -f k8s/worker-hpa.yaml

---

Project Structure

sci-agent-hub-platform/
├── api/                     # FastAPI service
│   ├── app/
│   │   ├── core/            # Config, DB engine, Celery app
│   │   ├── models/          # SQLAlchemy models + Pydantic schemas
│   │   ├── routes/          # auth, tasks, chat (WS), molecules
│   │   └── services/        # auth, claude, vector
│   ├── tests/
│   ├── Dockerfile
│   └── requirements.txt
├── worker/                  # Celery worker
│   ├── tasks/
│   │   ├── quantum.py       # Mock DFT simulation
│   │   ├── agent.py         # Claude analysis
│   │   └── embeddings.py    # pgvector upsert
│   ├── Dockerfile
│   └── requirements.txt
├── shared/                  # Shared between api and worker
│   ├── models/task_schemas.py
│   ├── prompts/analysis.py
│   └── config.py
├── k8s/                     # Kubernetes manifests + HPA
├── terraform/               # Railway IaC
├── infra/init.sql           # pgvector schema init
├── docker-compose.yml
└── .github/workflows/       # CI (ruff + pytest) + deploy

---

Environment Variables

Variable	Required	Description
DATABASE_URL	Yes	PostgreSQL async URL
REDIS_URL	Yes	Redis URL
SECRET_KEY	Yes	JWT signing secret
ANTHROPIC_API_KEY	Yes	Claude API key
OPENAI_API_KEY	No	OpenAI key for embeddings (falls back to keyword search)
ENVIRONMENT	No	development / production (default: development)
LOG_LEVEL	No	Log level (default: INFO)