Initial Commit

## What it does
- Reads Instagram Story images from uploaded files
- Converts images into structured semantic descriptions using OpenAI
- Caches outputs to avoid repeated API calls
- Runs per-day audits (default: today, overridable via config)

README.md

@@ -1,13 +1,24 @@
----
-title: IG Story Audit
-emoji: 🌍
-colorFrom: green
-colorTo: purple
-sdk: gradio
-sdk_version: 6.1.0
-app_file: app.py
-pinned: false
-short_description: A lightweight audit system to analyse Instagram Stories usin
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Instagram Story Audit
+
+A lightweight audit system to analyse Instagram Stories using OpenAI Vision,
+store semantic interpretations, and evaluate compliance against configurable
+policy rules.
+
+## What it does
+- Reads Instagram Story images from disk
+- Converts images into structured semantic descriptions using OpenAI
+- Caches outputs to avoid repeated API calls
+- Runs per-day audits (default: today, overridable via config)
+
+## Project structure
+- `data/raw_stories/` — input Story images
+- `data/vision_output/` — cached AI vision outputs (JSON)
+- `config/settings.ini` — runtime configuration
+- `config/modes.ini` — audit policy definitions
+
+## Running locally
+```bash
+source venv/bin/activate
+pip install -e .
+export OPENAI_API_KEY=your_key_here
+python -m ig_story_audit.main

app.py

@@ -0,0 +1,66 @@
+import gradio as gr
+from pathlib import Path
+import shutil
+
+from ig_story_audit.main import main as run_audit
+
+
+UPLOAD_DIR = Path("data/raw_stories")
+UPLOAD_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def audit_stories(files, goal, language):
+    # Clear previous uploads
+    for f in UPLOAD_DIR.iterdir():
+        f.unlink()
+
+    # Save uploaded files
+    for file in files:
+        shutil.copy(file.name, UPLOAD_DIR / Path(file.name).name)
+
+    # Override config dynamically (simple approach)
+    from ig_story_audit.utils.config import load_config
+    config = load_config()
+    config["general"]["language"] = language
+
+    # Run audit
+    run_audit()
+
+    # Read latest audit output
+    audit_dir = Path("data/audit_logs")
+    latest = max(audit_dir.glob("*_narrative_audit.txt"), key=lambda p: p.stat().st_mtime)
+
+    return latest.read_text(encoding="utf-8")
+
+
+with gr.Blocks() as demo:
+    gr.Markdown("## Instagram Story Narrative Audit")
+
+    files = gr.File(
+        file_types=["image"],
+        file_count="multiple",
+        label="Upload Instagram Story images (JPG/PNG)",
+    )
+
+    goal = gr.Textbox(
+        label="Audit goal",
+        placeholder="e.g. Reinforce the feeling of tiredness through repetition",
+    )
+
+    language = gr.Dropdown(
+        choices=["id", "en"],
+        value="id",
+        label="Output language",
+    )
+
+    run_btn = gr.Button("Run Audit")
+
+    output = gr.Textbox(label="Audit Result", lines=20)
+
+    run_btn.click(
+        audit_stories,
+        inputs=[files, goal, language],
+        outputs=output,
+    )
+
+demo.launch()

config/modes.ini

@@ -0,0 +1,30 @@
+[modes]
+active = narrative.universal_massage_awareness
+
+; ==================================================
+; NARRATIVE GOALS
+; Evaluated at STORY-SERIES level (per day)
+; ==================================================
+
+[narrative.universal_massage_awareness]
+description = Massage is relevant and needed by people from all walks of life
+
+; Minimum number of distinct subject groups represented across the series
+min_subject_diversity = 2
+
+; Allowed subject groups inferred from stories
+# allowed_subject_groups = individual, family, elderly, worker, general_public
+
+; At least one story must explicitly or implicitly generalise the need
+require_universal_framing = true
+
+; Disallowed narrowing frames
+forbidden_narratives = luxury_only, elite_only, athlete_only
+
+; Aggregate confidence threshold (mean of contributing stories)
+min_aggregate_confidence = 0.65
+
+; Weighting (used for qualitative scoring, not pass/fail)
+weights.subject_diversity = 0.4
+weights.universal_framing = 0.4
+weights.coherence = 0.2

config/settings.ini

@@ -0,0 +1,25 @@
+[general]
+timezone = Asia/Jakarta
+environment = development
+language = id
+
+[instagram]
+handle = jiva.familymassage
+
+[paths]
+raw_stories_dir = data/raw_stories
+vision_output_dir = data/vision_output
+audit_logs_dir = data/audit_logs
+
+[openai]
+vision_model = gpt-5-nano
+analysis_model = gpt-5-nano
+timeout_seconds = 60
+
+[vision]
+min_confidence = 0.6
+max_images_per_run = 20
+
+[run]
+date = 2025-12-14
+# date = today

requirements.txt

@@ -0,0 +1,4 @@
+openai
+python-dotenv
+gradio
+requests

src/ig_story_audit.egg-info/PKG-INFO

@@ -0,0 +1,3 @@
+Metadata-Version: 2.4
+Name: ig_story_audit
+Version: 0.0.0

src/ig_story_audit.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+README.md
+pyproject.toml
+src/ig_story_audit/__init__.py
+src/ig_story_audit/main.py
+src/ig_story_audit.egg-info/PKG-INFO
+src/ig_story_audit.egg-info/SOURCES.txt
+src/ig_story_audit.egg-info/dependency_links.txt
+src/ig_story_audit.egg-info/top_level.txt
+src/ig_story_audit/io/__init__.py
+src/ig_story_audit/io/loader.py
+src/ig_story_audit/io/writer.py
+src/ig_story_audit/judgement/__init__.py
+src/ig_story_audit/judgement/qualitative.py
+src/ig_story_audit/rules/__init__.py
+src/ig_story_audit/rules/evaluator.py
+src/ig_story_audit/utils/__init__.py
+src/ig_story_audit/utils/logging.py
+src/ig_story_audit/vision/__init__.py
+src/ig_story_audit/vision/describe_image.py
+src/ig_story_audit/vision/openai_client.py

src/ig_story_audit.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

src/ig_story_audit.egg-info/top_level.txt

@@ -0,0 +1 @@
+ig_story_audit

src/ig_story_audit/io/instagram_story_fetcher.py

@@ -0,0 +1,107 @@
+import requests
+from pathlib import Path
+from datetime import datetime
+from typing import Optional
+
+from ig_story_audit.utils.config import load_config
+
+
+HEADERS = {
+    "User-Agent": (
+        "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
+        "AppleWebKit/537.36 (KHTML, like Gecko) "
+        "Chrome/120.0.0.0 Safari/537.36"
+    ),
+    "Accept": "*/*",
+}
+
+
+def stories_already_fetched(run_date: str, output_dir: Path) -> bool:
+    if not output_dir.exists():
+        return False
+    return any(p.name.startswith(run_date) for p in output_dir.iterdir())
+
+
+def resolve_user_id(username: str) -> Optional[str]:
+    """
+    Resolve Instagram numeric user ID from username
+    using a public, anonymous endpoint.
+    """
+    url = f"https://www.instagram.com/{username}/?__a=1&__d=dis"
+
+    resp = requests.get(url, headers=HEADERS, timeout=10)
+    if resp.status_code != 200:
+        return None
+
+    try:
+        data = resp.json()
+        return data["graphql"]["user"]["id"]
+    except Exception:
+        return None
+
+
+def fetch_today_stories() -> None:
+    """
+    Fetch Instagram Stories for a public account using
+    anonymous, read-only access.
+    """
+    config = load_config()
+    username = config["instagram"]["handle"]
+    output_dir = Path(config["paths"]["raw_stories_dir"])
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    run_date = datetime.now().strftime("%Y-%m-%d")
+
+    # Enforce: fetch only once per day
+    if stories_already_fetched(run_date, output_dir):
+        print("Today's Instagram Stories already fetched. Skipping.")
+        return
+
+    user_id = resolve_user_id(username)
+    if not user_id:
+        raise RuntimeError("Unable to resolve Instagram user ID (profile may be private).")
+
+    reels_url = (
+        "https://www.instagram.com/api/v1/feed/reels_media/"
+        f"?reel_ids={user_id}"
+    )
+
+    resp = requests.get(reels_url, headers=HEADERS, timeout=10)
+    if resp.status_code != 200:
+        raise RuntimeError("Failed to fetch stories (anonymous access blocked).")
+
+    data = resp.json()
+    reels = data.get("reels", {})
+    user_reel = reels.get(user_id)
+
+    if not user_reel or "items" not in user_reel:
+        print("No active stories found.")
+        return
+
+    index = 1
+    for item in user_reel["items"]:
+        media_url = None
+        ext = "jpg"
+
+        if item.get("video_versions"):
+            media_url = item["video_versions"][0]["url"]
+            ext = "mp4"
+        elif item.get("image_versions2"):
+            media_url = item["image_versions2"]["candidates"][0]["url"]
+            ext = "jpg"
+
+        if not media_url:
+            continue
+
+        filename = output_dir / f"{run_date}_story_{index}.{ext}"
+
+        print(f"Downloading story {index}...")
+        media_resp = requests.get(media_url, headers=HEADERS, timeout=15)
+        media_resp.raise_for_status()
+
+        with open(filename, "wb") as f:
+            f.write(media_resp.content)
+
+        index += 1
+
+    print("Instagram Story fetch completed (anonymous).")

src/ig_story_audit/io/vision_cache.py

@@ -0,0 +1,16 @@
+import json
+from pathlib import Path
+
+def get_output_path(image_path: Path, output_dir: Path) -> Path:
+    return output_dir / f"{image_path.stem}.json"
+
+def load_cached_output(output_path: Path) -> dict | None:
+    if output_path.exists():
+        with open(output_path, "r", encoding="utf-8") as f:
+            return json.load(f)
+    return None
+
+def save_output(output_path: Path, data: dict):
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(output_path, "w", encoding="utf-8") as f:
+        json.dump(data, f, ensure_ascii=False, indent=2)

src/ig_story_audit/judgement/goal_gap_analyser.py

@@ -0,0 +1,47 @@
+from ig_story_audit.vision.openai_client import OpenAIClient
+from ig_story_audit.utils.config import load_config
+
+
+GOAL_EVALUATION_PROMPT = """
+You are an internal communication auditor.
+
+Language requirement:
+Write your response in the following language: {language}
+
+Context:
+The following is a narrative summary of Instagram Stories posted on a single day.
+
+Narrative summary:
+{summary}
+
+Audit goal:
+{goal}
+
+Your tasks:
+1. Clearly state whether the goal is achieved or not.
+2. Explain your reasoning in a calm, factual, human-readable way.
+3. If the goal is NOT achieved, explain what is missing or weak.
+4. Do NOT use bullet points unless necessary.
+5. Do NOT return JSON.
+6. Do NOT give marketing advice.
+
+Write 1–3 short paragraphs.
+"""
+
+
+def evaluate_goal_human_readable(
+    goal: str,
+    summary: str,
+) -> str:
+    config = load_config()
+    language = config["general"].get("language", "en")
+
+    client = OpenAIClient()
+
+    prompt = GOAL_EVALUATION_PROMPT.format(
+        goal=goal,
+        summary=summary,
+        language=language,
+    )
+
+    return client.describe_text(prompt).strip()

src/ig_story_audit/judgement/narrative_ai_summary.py

@@ -0,0 +1,47 @@
+import json
+from ig_story_audit.vision.openai_client import OpenAIClient
+from ig_story_audit.utils.config import load_config
+
+
+SUMMARY_PROMPT = """
+You are an internal audit assistant.
+
+Language requirement:
+Write the summary in the following language: {language}
+
+Narrative goal:
+{goal}
+
+Below is a list of story analysis results (JSON), in chronological order.
+Each item represents one Instagram Story frame.
+
+Your task:
+- Write a concise, human-readable summary (3–5 sentences)
+- Describe what the series of stories communicates as a whole
+- Base your summary ONLY on the provided data
+- Do NOT invent details
+- Do NOT give advice or marketing suggestions
+
+Story data:
+{stories_json}
+
+Return plain text only.
+"""
+
+
+def generate_ai_narrative_summary(
+    stories: list[dict],
+    narrative_description: str,
+) -> str:
+    config = load_config()
+    language = config["general"].get("language", "en")
+
+    client = OpenAIClient()
+
+    prompt = SUMMARY_PROMPT.format(
+        goal=narrative_description,
+        stories_json=json.dumps(stories, ensure_ascii=False, indent=2),
+        language=language,
+    )
+
+    return client.describe_text(prompt).strip()

src/ig_story_audit/judgement/narrative_evaluator.py

@@ -0,0 +1,79 @@
+from statistics import mean
+
+UNIVERSAL_KEYWORDS = {
+    "semua", "banyak", "keluarga", "orang tua", "ayah", "ibu", "anak"
+}
+
+SUBJECT_KEYWORDS = {
+    "family": {"keluarga", "ayah", "ibu", "anak"},
+    "elderly": {"orang tua", "lansia"},
+    "worker": {"kerja", "pegal"},
+}
+
+FORBIDDEN_NARRATIVES = {
+    "elite_only": {"mewah", "eksklusif"},
+    "athlete_only": {"atlet", "sport"}
+}
+
+
+def infer_subject_group(story: dict) -> str:
+    text = " ".join(story.get("text_present", [])).lower()
+
+    for group, keywords in SUBJECT_KEYWORDS.items():
+        if any(k in text for k in keywords):
+            return group
+
+    return "individual"
+
+
+def has_universal_framing(story: dict) -> bool:
+    text = " ".join(story.get("text_present", [])).lower()
+    return any(k in text for k in UNIVERSAL_KEYWORDS)
+
+
+def violates_forbidden_narrative(story: dict) -> bool:
+    text = " ".join(story.get("text_present", [])).lower()
+    for keywords in FORBIDDEN_NARRATIVES.values():
+        if any(k in text for k in keywords):
+            return True
+    return False
+
+
+def evaluate_narrative(stories: list[dict], narrative_cfg: dict) -> dict:
+    subject_groups = set()
+    universal_hits = 0
+    confidences = []
+
+    for story in stories:
+        subject_groups.add(infer_subject_group(story))
+        if has_universal_framing(story):
+            universal_hits += 1
+        if violates_forbidden_narrative(story):
+            return {
+                "fulfilled": False,
+                "reason": "Forbidden narrative detected"
+            }
+        confidences.append(story.get("confidence", 0))
+
+    diversity_ok = len(subject_groups) >= int(
+        narrative_cfg["min_subject_diversity"]
+    )
+
+    universal_ok = (
+        not narrative_cfg.get("require_universal_framing") or universal_hits > 0
+    )
+
+    confidence_ok = mean(confidences) >= float(
+        narrative_cfg["min_aggregate_confidence"]
+    )
+
+    fulfilled = diversity_ok and universal_ok and confidence_ok
+
+    return {
+        "fulfilled": fulfilled,
+        "subject_groups_detected": list(subject_groups),
+        "avg_confidence": round(mean(confidences), 2),
+        "universal_framing_present": universal_hits > 0,
+        "diversity_ok": diversity_ok,
+        "confidence_ok": confidence_ok
+    }

src/ig_story_audit/judgement/story_categoriser.py

@@ -0,0 +1,34 @@
+import json
+from ig_story_audit.vision.openai_client import OpenAIClient
+
+CATEGORISATION_PROMPT = """
+You are analysing a single Instagram Story.
+
+User-defined goal:
+{goal}
+
+Story analysis data (JSON):
+{story_json}
+
+Your tasks:
+1. Assign a short message category (e.g. education, promo, testimonial, filler, repost, brand)
+2. Decide how relevant this story is to the user-defined goal (0.0–1.0)
+3. Briefly explain why
+
+Return JSON only with keys:
+- category
+- relevance_score
+- rationale
+"""
+
+
+def categorise_story(story: dict, goal: str) -> dict:
+    client = OpenAIClient()
+
+    prompt = CATEGORISATION_PROMPT.format(
+        goal=goal,
+        story_json=json.dumps(story, ensure_ascii=False, indent=2),
+    )
+
+    response = client.describe_text(prompt)
+    return json.loads(response)

src/ig_story_audit/main.py

@@ -0,0 +1,161 @@
+from dotenv import load_dotenv
+load_dotenv()
+
+import json
+import argparse
+from pathlib import Path
+from datetime import datetime
+
+from ig_story_audit.vision.openai_client import OpenAIClient
+from ig_story_audit.utils.config import load_config
+from ig_story_audit.utils.goal_resolver import resolve_goal_and_date
+from ig_story_audit.judgement.narrative_ai_summary import (
+    generate_ai_narrative_summary,
+)
+from ig_story_audit.judgement.goal_gap_analyser import (
+    evaluate_goal_human_readable,
+)
+from ig_story_audit.io.vision_cache import (
+    get_output_path,
+    load_cached_output,
+    save_output,
+)
+from ig_story_audit.io.instagram_story_fetcher import fetch_today_stories
+
+fetch_today_stories()
+
+VISION_PROMPT = """
+Describe the image factually and neutrally.
+Do not evaluate quality or effectiveness.
+Return JSON only with:
+- visual_elements
+- text_present
+- implied_message
+- dominant_intent
+- tone
+- confidence
+"""
+
+
+def ensure_vision_outputs(run_date: str) -> list[dict]:
+    config = load_config()
+    raw_dir = Path(config["paths"]["raw_stories_dir"])
+    output_dir = Path(config["paths"]["vision_output_dir"])
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    image_files = sorted(
+        p for p in raw_dir.iterdir()
+        if p.is_file()
+        and p.suffix.lower() in {".jpg", ".jpeg", ".png"}
+        and p.name.startswith(run_date)
+    )
+
+    if not image_files:
+        print(f"No raw story images found for date {run_date}")
+        return []
+
+    client = OpenAIClient()
+    results: list[dict] = []
+
+    for image_path in image_files:
+        output_path = get_output_path(image_path, output_dir)
+
+        cached = load_cached_output(output_path)
+        if cached:
+            results.append(cached)
+            continue
+
+        print(f"Running vision model on {image_path.name}...")
+
+        raw_text = client.describe_image(
+            image_path=str(image_path),
+            prompt=VISION_PROMPT,
+        )
+
+        result = json.loads(raw_text)
+        save_output(output_path, result)
+        results.append(result)
+
+    return results
+
+
+def persist_audit_result(
+    run_date: str,
+    goal: str,
+    summary: str,
+    evaluation_text: str,
+):
+    config = load_config()
+    audit_dir = Path(config["paths"]["audit_logs_dir"])
+    audit_dir.mkdir(parents=True, exist_ok=True)
+
+    timestamp = datetime.now().strftime("%Y-%m-%d_%H-%M-%S")
+    path = audit_dir / f"{timestamp}_narrative_audit.txt"
+
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(f"Date: {run_date}\n")
+        f.write(f"Goal: {goal}\n\n")
+
+        f.write("=== Narrative Summary ===\n")
+        f.write(summary.strip())
+        f.write("\n\n")
+
+        f.write("=== Goal Evaluation ===\n")
+        f.write(evaluation_text.strip())
+
+    print(f"\nAudit written to: {path}")
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--interactive",
+        action="store_true",
+        help="Prompt for goal and date interactively",
+    )
+    args = parser.parse_args()
+
+    # 1. Resolve goal + date
+    goal, run_date, is_preset = resolve_goal_and_date(args.interactive)
+
+    print("\n=== Audit Configuration ===")
+    print(f"Goal: {goal}")
+    print(f"Date: {run_date}")
+    print(f"Mode: {'preset' if is_preset else 'interactive'}")
+
+    # 2. Ensure vision outputs
+    stories = ensure_vision_outputs(run_date)
+
+    if not stories:
+        print("No stories available for audit.")
+        return
+
+    # 3. Narrative AI summary
+    summary = generate_ai_narrative_summary(
+        stories=stories,
+        narrative_description=goal,
+    )
+
+    print("\n=== Narrative Summary ===")
+    print(summary)
+
+    # 4. Human-readable goal evaluation
+    evaluation_text = evaluate_goal_human_readable(
+        goal=goal,
+        summary=summary,
+    )
+
+    print("\n=== Goal Evaluation ===")
+    print(evaluation_text)
+
+    # 5. Persist audit
+    persist_audit_result(
+        run_date=run_date,
+        goal=goal,
+        summary=summary,
+        evaluation_text=evaluation_text,
+    )
+
+
+if __name__ == "__main__":
+    main()

src/ig_story_audit/utils/config.py

@@ -0,0 +1,12 @@
+import configparser
+from pathlib import Path
+
+_CONFIG = None
+
+def load_config():
+    global _CONFIG
+    if _CONFIG is None:
+        parser = configparser.ConfigParser()
+        parser.read(Path("config/settings.ini"))
+        _CONFIG = parser
+    return _CONFIG

src/ig_story_audit/utils/date_utils.py

@@ -0,0 +1,15 @@
+from datetime import datetime
+from ig_story_audit.utils.config import load_config
+
+def get_run_date() -> str:
+    config = load_config()
+
+    if "run" in config and "date" in config["run"]:
+        date_value = config["run"]["date"]
+    else:
+        date_value = "today"
+
+    if date_value == "today":
+        return datetime.now().strftime("%Y-%m-%d")
+
+    return date_value

src/ig_story_audit/utils/goal_resolver.py

@@ -0,0 +1,31 @@
+from datetime import datetime
+from ig_story_audit.utils.modes_config import load_modes
+
+
+def resolve_goal_and_date(interactive: bool) -> tuple[str, str, bool]:
+    """
+    Returns:
+    - goal_description (str)
+    - run_date (YYYY-MM-DD)
+    - is_preset (bool)
+    """
+    if interactive:
+        goal = input("Enter the goal you want to audit:\n> ").strip()
+
+        today_choice = input("Is the date today? (Y/N): ").strip().lower()
+        if today_choice == "y":
+            run_date = datetime.now().strftime("%Y-%m-%d")
+        else:
+            run_date = input("Enter date (YYYY-MM-DD): ").strip()
+
+        return goal, run_date, False
+
+    # preset mode
+    modes = load_modes()
+    active_mode = modes["modes"]["active"]
+    cfg = modes[active_mode]
+
+    goal = cfg.get("description", active_mode)
+    run_date = datetime.now().strftime("%Y-%m-%d")
+
+    return goal, run_date, True

src/ig_story_audit/utils/interactive_input.py

@@ -0,0 +1,13 @@
+from datetime import datetime
+
+def prompt_for_goal_and_date() -> tuple[str, str]:
+    goal = input("Enter the goal you want to audit for this day:\n> ").strip()
+
+    today_choice = input("Is the date today? (Y/N): ").strip().lower()
+
+    if today_choice == "y":
+        date = datetime.now().strftime("%Y-%m-%d")
+    else:
+        date = input("Enter the date (YYYY-MM-DD): ").strip()
+
+    return goal, date

src/ig_story_audit/utils/modes_config.py

@@ -0,0 +1,12 @@
+import configparser
+from pathlib import Path
+
+_MODES = None
+
+def load_modes():
+    global _MODES
+    if _MODES is None:
+        parser = configparser.ConfigParser()
+        parser.read(Path("config/modes.ini"))
+        _MODES = parser
+    return _MODES

src/ig_story_audit/vision/openai_client.py

@@ -0,0 +1,64 @@
+import base64
+import os
+from openai import OpenAI
+
+from ig_story_audit.utils.config import load_config
+
+
+class OpenAIClient:
+    """
+    Thin OpenAI API wrapper.
+    - Vision calls use vision_model
+    - Text / analysis calls use analysis_model
+    """
+
+    def __init__(self, api_key: str | None = None):
+        self.api_key = api_key or os.getenv("OPENAI_API_KEY")
+        if not self.api_key:
+            raise ValueError("OPENAI_API_KEY not set")
+
+        config = load_config()
+
+        self.vision_model = config["openai"]["vision_model"]
+        self.analysis_model = config["openai"]["analysis_model"]
+
+        self.client = OpenAI(api_key=self.api_key)
+
+    def describe_image(self, image_path: str, prompt: str) -> str:
+        with open(image_path, "rb") as img:
+            image_b64 = base64.b64encode(img.read()).decode("utf-8")
+
+        image_data_url = f"data:image/jpeg;base64,{image_b64}"
+
+        response = self.client.responses.create(
+            model=self.vision_model,
+            input=[
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "input_text", "text": prompt},
+                        {
+                            "type": "input_image",
+                            "image_url": image_data_url,
+                        },
+                    ],
+                }
+            ],
+        )
+
+        return response.output_text
+
+    def describe_text(self, prompt: str) -> str:
+        response = self.client.responses.create(
+            model=self.analysis_model,
+            input=[
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "input_text", "text": prompt},
+                    ],
+                }
+            ],
+        )
+
+        return response.output_text