archit-studio 0.3.0

AI-powered architecture studio built on archit-app — multi-agent design assistant with Chainlit UI.

archit-studio

AI-powered architecture design studio built on archit-app.

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

---

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+

pip install archit-studio

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

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

Environment setup:

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

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

---

Running

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

Or via the installed CLI entry point:

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):

# 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:

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.

[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

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.