sica-bridge 0.1.0

Structure Investigation and Condition Assessment for Bridges (post-earthquake visual inspection)

sica-bridge

SICA = Structure Investigation and Condition Assessment.

sica-bridge is a Python package that uses a vision-capable LLM to perform post-earthquake visual inspection from photos and to support rapid decision-making for bridge safety assessment. It outputs an R-state (R1–R4) and a short reason per photo, then aggregates results to component-level and event-level summaries that can be used to prioritize inspections, closures, and follow-up actions.

Current scope: 4 component categories (approaches, columns, joints/hinges, abutments/wingwalls/shear keys).

R-states (Action Plan)

• R1 — Open
• R2 — Open but inspection needed
• R3 — Close but inspection needed
• R4 — Close immediately

Repository layout

.
├─ src/sica_bridge/
│  ├─ assess/                  # photo-level assessment + aggregation helpers
│  ├─ llm/                     # LLM client interface + prompt builder
│  ├─ registry/                # component registry (ids, display names, filenames)
│  ├─ resources/               # loaders for prompts/rubrics/reference images
│  ├─ schemas/                 # Pydantic output schemas (RState, ComponentAssessment, EventAssessment)
│  ├─ utils/                   # helpers (e.g., robust JSON extraction)
│  └─ gui/                     # demo UI 
├─ prompts/
│  ├─ system.md
│  └─ components/              # per-component prompt templates (.md)
├─ rubrics/                    # per-component rubrics (.yaml)
├─ assets/
│  └─ damage_examples/         # optional reference images used in prompts
│     └─ <component_id>/
│        ├─ meta.yaml          # optional captions & ordering
│        └─ *.jpg|*.png
└─ tests/                      # pytest unit tests

Install

Requirements

• Python >= 3.10

From source (recommended for development)

pip install -e .

Dev dependencies

pip install -e ".[dev]"

Quickstart: run the demo

The repo includes a default UI and you can have a quick local deployment for research or testing:

python src/sica_bridge/gui/webserver.py

Then open the local server URL and upload one or more photos for each component category. Please don't forget to set up the OpenAI or other LLM API key for the testing. If you are planning to use your own computer vision models, please set up the GPU server for testing. Go to Adding a new LLM provider for further information.

How it works (pipeline)

For each uploaded image:

1. Load reference images (optional, preset) for the component from:
   • assets/damage_examples/<component_id>/
2. Build a prompt:
   • prompts/system.md
   • prompts/components/<component_id>.md
   • rubrics/<component_id>.yaml (parsed into JSON and embedded)
   • Pydantic JSON schema for ComponentAssessment (the output contract)
3. Call a VisionLLMClient to produce JSON-only output.
4. Parse and validate the JSON into ComponentAssessment.
5. Aggregate:
   • component-level: worst-case (max severity) across that component’s photos
   • event-level: worst-case (max severity) across all component assessments

Schemas

from sica_bridge.schemas import RState, ComponentAssessment, EventAssessment

• RState: Enum of R1, R2, R3, R4
• ComponentAssessment:
  • component_id: str
  • r_state: RState
  • reason: str
  • notes: Optional[str]
• EventAssessment:
  • overall_r_state: RState
  • components: list[ComponentAssessment]

Assessment

from sica_bridge.assess import assess_component, assess_component_many, aggregate_component, aggregate_event
from sica_bridge.llm.openai_client import OpenAIVisionClient

Assess one photo

client = OpenAIVisionClient()
out = assess_component(
    component_id="columns",
    image_bytes=open("my_photo.jpg", "rb").read(),
    mime_type="image/jpeg",
    filename="my_photo.jpg",
    client=client,
)
print(out.r_state, out.reason)

Assess many photos for one component

photos = [
    (open("a.jpg","rb").read(), "a.jpg", "image/jpeg"),
    (open("b.jpg","rb").read(), "b.jpg", "image/jpeg"),
]
results = assess_component_many(component_id="columns", photos=photos, client=client)

Aggregate component and event states

overall_component = aggregate_component(results)  # -> RState
event = aggregate_event(results)                  # -> EventAssessment (worst-case across provided items)

---

LLM clients

Interface

Implement this provider-agnostic interface:

from sica_bridge.llm.client import VisionLLMClient, VisionInput

VisionLLMClient.complete_json(prompt: str, images: list[VisionInput]) -> str
should return a JSON object as plain text (no markdown), matching the schema.

OpenAI implementation

from sica_bridge.llm.openai_client import OpenAIVisionClient
client = OpenAIVisionClient(model="gpt-5.2")

In case you want to use your own computer vision models or other LLMs, please also check Adding a new LLM provider

---

Adding / editing components

Component categories are defined in:

• src/sica_bridge/registry/components.py

Each component has:

• id (stable key used across prompts, rubrics, schemas, GUI)
• rubric_filename in rubrics/
• prompt_filename in prompts/

To add a new component, add a new ComponentSpec entry and create:

• rubrics/<new_id>.yaml
• prompts/components/<new_id>.md
• (optional) assets/damage_examples/<new_id>/...

---