Metadata-Version: 2.4
Name: archit-studio
Version: 0.3.0
Summary: AI-powered architecture studio built on archit-app — multi-agent design assistant with Chainlit UI.
Keywords: AI,BIM,agents,architecture,chainlit,crewai,floorplan
Requires-Python: >=3.11
Requires-Dist: anthropic>=0.28.0
Requires-Dist: archit-app>=0.3.3
Requires-Dist: chainlit>=1.2.0
Requires-Dist: crewai-tools>=0.14.0
Requires-Dist: crewai>=0.80.0
Requires-Dist: dynaconf>=3.2.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: openai>=1.30.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: tenacity>=8.3.0
Provides-Extra: dev
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="logo/archit-studio-icon-dark.svg">
  <img src="logo/archit-studio-icon-light.svg" alt="archit-studio" width="120">
</picture>

# archit-studio

AI-powered architecture design studio built on [archit-app](../archit-app/README.md).

```
pip install -e .
chainlit run studio/ui/app.py
```

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../archit-app/LICENSE)

---

## Overview

`archit-studio` wraps the `archit-app` library in a multi-agent AI design assistant with a Chainlit chat UI. A **7-agent CrewAI crew** works hierarchically — a Project Manager receives the user's request, decomposes it, delegates to specialist agents, and synthesises a response. Every agent calls `archit-app` Python tools directly; the building model is kept in-session and can be exported to SVG, JSON, DXF, or IFC at any time.

**Relationship to `archit-app`:**

| Layer | Package | Role |
|-------|---------|------|
| Data model + I/O | `archit-app` | Immutable building model, geometry, analysis, exports |
| AI agents + UI | `archit-studio` | CrewAI crew, Chainlit interface, session state, LLM routing |

`archit-studio` depends on `archit-app` as a PyPI dependency and never modifies the core library.

---

## Architecture

```
archit-studio/
├── studio/
│   ├── config.py          — Dynaconf settings (settings.toml + .env), model registry
│   ├── state/
│   │   └── session.py     — Per-session BuildingState + History (undo/redo) + JSON persistence
│   ├── agents/
│   │   ├── definitions.py — Role, goal, backstory for each of the 7 agents
│   │   ├── crew.py        — CrewAI hierarchical crew assembly and run() / arun() entry points
│   │   ├── tasks.py       — Task factory for the hierarchical process
│   │   └── tools/         — CrewAI tools wrapping archit-app API calls
│   │       ├── building_tools.py   — add_level, add_room, add_wall, add_opening, staircase, undo/redo
│   │       ├── structural_tools.py — add_column, add_beam, add_slab, add_ramp, add_elevator, set_grid
│   │       ├── analysis_tools.py   — compliance, egress, accessibility, daylighting, adjacency, set_land
│   │       ├── interior_tools.py   — add_furniture, add_text_annotation, set_room_material
│   │       └── io_tools.py         — export_svg, export_json, validate, save/load session
│   └── ui/
│       └── app.py         — Chainlit event handlers (on_chat_start, on_message, file upload, settings)
├── data/sessions/         — Saved session JSON files (auto-created at runtime)
├── settings.toml          — Default configuration
└── pyproject.toml
```

---

## The 7-Agent Crew

The crew runs under `Process.hierarchical` — the **Project Manager** is the manager agent that plans, delegates to specialists, and writes the final response. Specialists do not delegate.

| Agent | Role | Tools |
|-------|------|-------|
| **Project Manager** | Client-facing coordinator; plans and delegates | *(no tools — orchestration only)* |
| **Architect** | Spatial layout — rooms, walls, openings, levels, staircases | Building CRUD tools + undo/redo |
| **Structural Engineer** | Columns, beams, slabs, ramps, elevators, structural grid | Structural tools |
| **Compliance Analyst** | Zoning, FAR, egress, accessibility, daylighting | Analysis tools + `set_land` |
| **Interior Designer** | Furniture, materials, text annotations | Interior tools |
| **Space Programmer** | Area reports, adjacency analysis, brief compliance | Area + adjacency tools |
| **BIM Coordinator** | SVG/JSON export, model validation, session save/load | I/O tools + undo/redo |

Every agent also receives `get_building_context` and `get_building_detailed_context` (read-only shared tools).

---

## Installation

**Prerequisites:** Python 3.11+

```bash
pip install archit-studio
```

`archit-app` (with its IO extras) is pulled in automatically as a dependency. To install everything at once:

```bash
pip install "archit-studio[io,image,pdf,analysis]"
```

**Environment setup:**

Create a `.env` file in the `archit-studio/` directory:

```dotenv
OPENAI_API_KEY=sk-...          # required for OpenAI models
ANTHROPIC_API_KEY=sk-ant-...   # required for Claude models
```

---

## Running

```bash
cd archit-studio
chainlit run studio/ui/app.py --port 8000
```

Or via the installed CLI entry point:

```bash
archit-studio
```

Open `http://localhost:8000` in a browser.

---

## Docker

Both packages are installed from PyPI so the build context is just the `archit-studio/` directory.

**docker-compose (recommended):**

```bash
# 1. Create a .env file with your API keys
echo "OPENAI_API_KEY=sk-..." > archit-studio/.env

# 2. Build and start
docker compose -f archit-studio/docker-compose.yml up --build
```

Open `http://localhost:8000`.

**Plain docker build:**

```bash
docker build -f archit-studio/Dockerfile -t archit-studio archit-studio/
docker run --rm -p 8000:8000 \
  --env-file archit-studio/.env \
  -v archit-studio-sessions:/data/sessions \
  archit-studio
```

**Environment variables** (all optional — override `settings.toml` values):

| Variable | Default | Description |
|----------|---------|-------------|
| `OPENAI_API_KEY` | — | Required for OpenAI models |
| `ANTHROPIC_API_KEY` | — | Required for Claude models |
| `STUDIO_MODEL` | `gpt-4o-mini` | Default LLM for all agents |
| `STUDIO_VERBOSE_AGENTS` | `false` | Print agent chain-of-thought to logs |
| `STUDIO_DATA_DIR` | `/data/sessions` | Session save directory (inside container) |

Session JSON files are stored in the named volume `sessions` and persist across container restarts.

---

## Configuration

All settings live in `settings.toml` and can be overridden by environment variables prefixed `STUDIO_` or by a `.env` file.

```toml
[default]
model = "gpt-4o-mini"          # default LLM for all agents
verbose_agents = false          # show full agent chain-of-thought in terminal
data_dir = "./data/sessions"    # where session JSON files are saved
max_history = 50                # undo/redo stack depth

[default.agents.project_manager]
model = ""   # empty → uses top-level default; set to override per-agent
```

**Supported models** (selectable in the UI settings panel):

| ID | Provider | Notes |
|----|----------|-------|
| `gpt-4o-mini` | OpenAI | Default — fast and cost-efficient |
| `gpt-4o` | OpenAI | Higher capability |
| `gpt-5-mini` | OpenAI | Next-gen fast |
| `gpt-5` | OpenAI | Next-gen flagship |
| `claude-3-5-haiku-20241022` | Anthropic | Fast alternative |
| `claude-3-5-sonnet-20241022` | Anthropic | High-quality alternative |
| `claude-opus-4-5` | Anthropic | Most capable |

Override at runtime: `STUDIO_MODEL=claude-3-5-sonnet-20241022 chainlit run studio/ui/app.py`

---

## Session State

Each Chainlit session gets an isolated `SessionState` object holding:

- The current `Building` (from `archit-app`)
- A `History` stack for undo/redo (depth controlled by `max_history`)
- The active model name
- A session ID used for saving/loading JSON files to `data/sessions/`

Sessions are persisted as JSON and can be reloaded by uploading a `.json` file in the chat or asking the BIM Coordinator to load a named session.

---

## File Uploads

Drop files into the chat to import them:

| File type | Result |
|-----------|--------|
| `.json` (archit-app building) | Replaces current building in session |
| `.geojson` / `.geo.json` | Imported as a new Level in the current building |

---

## Auto SVG Export

After each response the UI checks whether any drawable elements (rooms or walls) were added or changed. If so, an SVG floorplan for every level is automatically exported and displayed inline in the chat. The BIM Coordinator can also export explicitly at any time via `export_level_svg`.

---

## Development

```bash
pip install -e "archit-studio[dev]"
pytest
ruff check studio/
mypy studio/
```

---

## Brand Colors

| Token | Hex | Use |
|-------|-----|-----|
| **Void** | `#0C1018` | Night sky — deep shadows, primary text on light |
| **Vellum** | `#E8EDF5` | Tracing paper — primary text on dark, light fills |
| **Blueprint** | `#3B82F6` | Technical lines — accents, links, speech bubble frame |
| **Datum** | `#F59E0B` | Reference point — icon handles, highlights |

---

## Theming & Avatars

The UI uses Chainlit 2.x theme format (`public/theme.json`) with CSS custom properties in HSL. Brand colors are applied globally — Blueprint (`#3B82F6`) for primary actions, Void (`#0C1018`) / Vellum (`#E8EDF5`) for backgrounds and text. Per-agent avatar icons live in `public/avatars/` as `{agent_name}.svg` (lowercase, underscores).

---

## Changelog

### 0.3.0
- **Fix: CrewAI 400 `tool_calls` error** — patch `_prepare_llm_call` in `crewai.utilities.agent_utils` to strip dangling unresponded tool_calls that CrewAI's hierarchical process leaks into specialist executor context before each OpenAI API call. Retry logic added in the UI for transient failures.
- **Fix: session_id now embedded in every agent's goal** — all 7 agents receive `ACTIVE SESSION ID: {session_id}` in their system prompt at crew creation time, ensuring tool calls always include the correct session context even when the PM's delegation omits it.
- **Fix: SVG auto-export trigger** — export now fires when walls or rooms change (not rooms alone), so designs that start with walls are rendered immediately.
- **Fix: explicit task workflow** — task description now spells out the mandatory `add_level → add_room → export_level_svg → save_session` call sequence, reducing narration-only responses.
- **UI: Chainlit 2.x theme** — migrated to `public/theme.json` with HSL CSS variables; removed legacy `[UI.theme]` TOML blocks.
- **UI: agent avatars** — added per-agent SVG icons in `public/avatars/` matching Chainlit 2.x normalised naming.

### 0.2.0
- Added 7-agent hierarchical CrewAI crew with specialist delegation
- Chainlit 2.x UI with file upload, session management, inline SVG display

### 0.1.x
- Initial release: single-agent crew, Docker support, basic Chainlit integration

---

## License

MIT — see [`archit-app/LICENSE`](../archit-app/LICENSE).
