sica-bridge 0.1.0__tar.gz

sica_bridge-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Issac Pang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sica_bridge-0.1.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: sica-bridge
+Version: 0.1.0
+Summary: Structure Investigation and Condition Assessment for Bridges (post-earthquake visual inspection)
+Author: Issac K.T. Pang
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: python-dotenv>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Dynamic: license-file
+
+# sica-bridge
+
+<img src="image/sica_logo.svg" alt="SICA logo" width="420"/>
+
+**SICA** = **S**tructure **I**nvestigation and **C**ondition **A**ssessment.
+
+`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
+
+```text
+.
+├─ 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)
+
+```bash
+pip install -e .
+```
+
+### Dev dependencies
+
+```bash
+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:
+
+```bash
+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](README_new_llm_section.md) 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
+
+```python
+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
+
+```python
+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**
+
+```python
+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**
+
+```python
+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**
+
+```python
+overall_component = aggregate_component(results)  # -> RState
+event = aggregate_event(results)                  # -> EventAssessment (worst-case across provided items)
+```
+
+---
+
+## LLM clients
+
+### Interface
+
+Implement this provider-agnostic interface:
+
+```python
+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
+
+```python
+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](README_new_llm_section.md)
+
+---
+
+## 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>/...`
+
+---

sica_bridge-0.1.0/README.md

@@ -0,0 +1,183 @@
+# sica-bridge
+
+<img src="image/sica_logo.svg" alt="SICA logo" width="420"/>
+
+**SICA** = **S**tructure **I**nvestigation and **C**ondition **A**ssessment.
+
+`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
+
+```text
+.
+├─ 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)
+
+```bash
+pip install -e .
+```
+
+### Dev dependencies
+
+```bash
+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:
+
+```bash
+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](README_new_llm_section.md) 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
+
+```python
+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
+
+```python
+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**
+
+```python
+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**
+
+```python
+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**
+
+```python
+overall_component = aggregate_component(results)  # -> RState
+event = aggregate_event(results)                  # -> EventAssessment (worst-case across provided items)
+```
+
+---
+
+## LLM clients
+
+### Interface
+
+Implement this provider-agnostic interface:
+
+```python
+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
+
+```python
+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](README_new_llm_section.md)
+
+---
+
+## 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>/...`
+
+---

sica_bridge-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sica-bridge"
+version = "0.1.0"
+description = "Structure Investigation and Condition Assessment for Bridges (post-earthquake visual inspection)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Issac K.T. Pang" }]
+dependencies = [
+  "pydantic>=2.0",
+  "pyyaml>=6.0",
+  "openai>=1.0.0",
+  "python-dotenv>=1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.0",
+  "ruff>=0.5",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.package-data]
+# include non-python assets if/when we move rubrics/prompts into src later
+sica_bridge = ["py.typed", "data/**/*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"

sica_bridge-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sica_bridge-0.1.0/src/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.0"

sica_bridge-0.1.0/src/sica_bridge/assess/__init__.py

@@ -0,0 +1,4 @@
+from .component_assessor import assess_component, assess_component_many, aggregate_component
+from .event_aggregator import aggregate_event
+
+__all__ = ["assess_component", "assess_component_many", "aggregate_component", "aggregate_event"]

sica_bridge-0.1.0/src/sica_bridge/assess/component_assessor.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from sica_bridge.llm import render_prompt
+from sica_bridge.llm.client import VisionInput, VisionLLMClient
+from sica_bridge.schemas import ComponentAssessment
+from sica_bridge.utils import extract_json_object
+from sica_bridge.resources import load_reference_images
+from typing import Iterable
+from sica_bridge.schemas import RState
+
+# severity order (higher = worse)
+_SEVERITY = {RState.R1: 1, RState.R2: 2, RState.R3: 3, RState.R4: 4}
+
+def assess_component(
+    *,
+    component_id: str,
+    image_bytes: bytes,
+    client: VisionLLMClient,
+    mime_type: str = "image/jpeg",
+    filename: str | None = None,
+    reference_limit: int = 4,  # optional tuning knob
+) -> ComponentAssessment:
+    """
+    Assess ONE inspection photo.
+    Preset reference images are auto-loaded from the codebase.
+    """
+    query_image = VisionInput(
+        image_bytes=image_bytes,
+        mime_type=mime_type,
+        filename=filename,
+        role="query",
+        caption="Inspection photo",
+    )
+
+    refs = load_reference_images(component_id, limit=reference_limit)  # preset only
+    images = [query_image, *refs]
+
+    prompt = render_prompt(component_id, images=images)
+    raw = client.complete_json(prompt=prompt, images=images)
+
+    data = extract_json_object(raw)
+    data["component_id"] = component_id  # enforce consistency
+    return ComponentAssessment.model_validate(data)
+
+
+def assess_component_many(
+    *,
+    component_id: str,
+    photos: Iterable[tuple[bytes, str | None, str]],  # (image_bytes, filename, mime_type)
+    client,
+) -> list[ComponentAssessment]:
+    """
+    Issac: assess inspection photos one-by-one.
+    Each photo returns its own R_state + reason.
+    """
+    results: list[ComponentAssessment] = []
+    for idx, (b, fname, mt) in enumerate(photos, start=1):
+        a = assess_component(
+            component_id=component_id,
+            image_bytes=b,
+            filename=fname,
+            mime_type=mt,
+            client=client,
+        )
+        # optional traceability (doesn't change required fields)
+        a = a.model_copy(update={"notes": f"photo_index={idx}, filename={fname}"})
+        results.append(a)
+    return results
+
+
+def aggregate_component(assessments: list[ComponentAssessment]) -> RState:
+    """
+    Worst-case rollup for ONE component (across multiple photos).
+    """
+    if not assessments:
+        raise ValueError("No photo assessments for this component.")
+    return max(assessments, key=lambda a: _SEVERITY[a.r_state]).r_state

sica_bridge-0.1.0/src/sica_bridge/assess/event_aggregator.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from sica_bridge.schemas import ComponentAssessment, EventAssessment, RState
+
+
+# severity order (higher = worse)
+_SEVERITY = {
+    RState.R1: 1,
+    RState.R2: 2,
+    RState.R3: 3,
+    RState.R4: 4,
+}
+
+
+def aggregate_event(components: list[ComponentAssessment]) -> EventAssessment:
+    if not components:
+        raise ValueError("No component assessments provided.")
+
+    overall = max(components, key=lambda c: _SEVERITY[c.r_state]).r_state
+    return EventAssessment(overall_r_state=overall, components=components)

sica_bridge-0.1.0/src/sica_bridge/llm/__init__.py

@@ -0,0 +1,3 @@
+from .prompt_builder import render_prompt
+
+__all__ = ["render_prompt"]

sica_bridge-0.1.0/src/sica_bridge/llm/client.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import abc
+from dataclasses import dataclass
+from typing import Optional, Literal
+
+ImageRole = Literal["query", "reference"]
+
+@dataclass(frozen=True)
+class VisionInput:
+    """
+    Represents one image to analyze.
+    The model will receive images in the given order.
+    """
+    image_bytes: bytes
+    mime_type: str = "image/jpeg"
+    filename: Optional[str] = None
+
+    # Issac: help the prompt explain what each image is
+    role: ImageRole = "query"          # "query" or "reference"
+    caption: Optional[str] = None      # e.g., "Example: diagonal shear cracking"
+
+class VisionLLMClient(abc.ABC):
+    """
+    Provider-agnostic interface.
+    Implementations will call OpenAI / Anthropic / etc.
+    """
+
+    @abc.abstractmethod
+    def complete_json(self, *, prompt: str, images: list[VisionInput]) -> str:
+        """
+        Returns the model's raw text output (expected to be JSON text).
+        """
+        raise NotImplementedError
+
+
+class FakeVisionLLMClient(VisionLLMClient):
+    """
+    Deterministic fake for tests/dev without network.
+    """
+
+    def __init__(self, json_text: str):
+        self._json_text = json_text
+
+    def complete_json(self, *, prompt: str, images: VisionInput) -> str:
+        # ignore prompt/image; return deterministic stub
+        return self._json_text

sica_bridge-0.1.0/src/sica_bridge/llm/openai_client.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import base64
+import os
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+from openai import OpenAI
+
+from sica_bridge.llm.client import VisionInput, VisionLLMClient
+
+
+def _to_data_url(image_bytes: bytes, mime_type: str) -> str:
+    b64 = base64.b64encode(image_bytes).decode("ascii")
+    return f"data:{mime_type};base64,{b64}"
+
+
+@dataclass
+class OpenAIVisionClient(VisionLLMClient):
+    """
+    OpenAI Responses API implementation.
+
+    API key is read from environment variable OPENAI_API_KEY.
+    """
+    model: str = "gpt-5.2"
+    detail: str = "auto"
+
+    def __post_init__(self) -> None:
+        api_key = os.getenv("OPENAI_API_KEY")
+        if not api_key:
+            raise RuntimeError(
+                "OPENAI_API_KEY environment variable is not set. "
+                "Set it before running the application."
+            )
+
+        self._client = OpenAI(api_key=api_key)
+
+        self.model = os.getenv("SICA_OPENAI_MODEL", self.model)
+
+    def _build_input(self, prompt: str, images: list[VisionInput]) -> list[Dict[str, Any]]:
+        content: List[Dict[str, Any]] = [{"type": "input_text", "text": prompt}]
+
+        for im in images:
+            content.append(
+                {
+                    "type": "input_image",
+                    "image_url": _to_data_url(im.image_bytes, im.mime_type),
+                    "detail": self.detail,
+                }
+            )
+
+        return [{"role": "user", "content": content}]
+
+    def complete_json(self, *, prompt: str, images: list[VisionInput]) -> str:
+        resp = self._client.responses.create(
+            model=self.model,
+            input=self._build_input(prompt, images),
+        )
+        return (resp.output_text or "").strip()