todomat 0.2.1__tar.gz

todomat-0.2.1/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: todomat
+Version: 0.2.1
+Summary: Todomat — TODO orchestration with NLP2DSL, ITERUN, and curllm pipelines
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.26.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: beautifulsoup4>=4.12
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == "mcp"
+Provides-Extra: services
+Requires-Dist: fastapi>=0.115; extra == "services"
+Requires-Dist: uvicorn[standard]>=0.32; extra == "services"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: goal>=2.1.0; extra == "dev"
+Requires-Dist: costs>=0.1.20; extra == "dev"
+Requires-Dist: pfix>=0.1.60; extra == "dev"
+
+# Todomat
+
+
+## AI Cost Tracking
+
+![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.2.1-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![AI Cost](https://img.shields.io/badge/AI%20Cost-$0.15-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-1.0h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
+
+- 🤖 **LLM usage:** $0.1500 (1 commits)
+- 👤 **Human dev:** ~$100 (1.0h @ $100/h, 30min dedup)
+
+Generated on 2026-06-07 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
+
+---
+
+Stack testowy strony www dla klientów wdrażających automatyzację przez prompty.
+
+Łączy **Open WebUI** z **curllm** (dane online), **NLP2DSL** (procesy biznesowe) i **ITERUN** (usługi/API/stacki) przez OpenAI-compatible router.
+
+## Szybki start
+
+```bash
+cp .env.example .env
+./scripts/bootstrap.sh
+./scripts/test-local.sh
+```
+
+## Endpointy
+
+| Usługa | URL |
+|--------|-----|
+| Open WebUI | http://localhost:3000 |
+| Pipeline Router | http://localhost:9099/v1 |
+| Trigger Gateway | http://localhost:8084/trigger |
+| curllm API (opcjonalnie) | http://localhost:8810 |
+
+## curllm — dane z internetu
+
+```bash
+./scripts/start-curllm.sh   # opcjonalnie, pełny browser+LLM
+```
+
+Domyślnie adapter używa lekkiego HTTP fetch (`CURLLM_LIGHT_FETCH=1`). Pełny curllm: `CURLLM_LIGHT_FETCH=0` + uruchomiony API na :8810.
+
+## Open WebUI — połączenie
+
+Admin → Settings → Connections:
+
+```
+Base URL: http://pipeline-router:9099/v1   # gdy Open WebUI w sieci todomat
+API Key:  dev-key
+```
+
+Jeśli Open WebUI działa poza compose: `http://host.docker.internal:9099/v1`.
+Po `./scripts/bootstrap.sh` kontener `openwebui` jest automatycznie podłączany do sieci `todomat_todomat-net`.
+
+## Przykładowe prompty
+
+Zob. `examples/prompts/` — w tym [orchestration.md](examples/prompts/orchestration.md) (usługi, getv, desktop, workflow).
+
+## MCP (Cursor / agenty)
+
+Jeden router MCP routuje do curllm, nlp2dsl i iterun:
+
+```bash
+pip install -e .
+./scripts/start-mcp.sh
+```
+
+Dokumentacja: [docs/MCP.md](docs/MCP.md) · konfiguracja Cursor: `examples/mcp-cursor.json`
+
+## Orchestracja (URI, MCP, wiele usług)
+
+Przewodnik uruchomienia i kontroli usług, artefaktów, zmiennych getv i zadań:
+
+- **[docs/ORCHESTRATION.md](docs/ORCHESTRATION.md)** — trigger-gateway, MCP, scenariusze
+- [docs/MCP.md](docs/MCP.md) — router `todomat-mcp`
+- [docs/INTEGRATION.md](docs/INTEGRATION.md) — Open WebUI
+- [nlp2uri orchestration](https://github.com/semcod/nlp2uri/blob/main/docs/orchestration.md) — schematy URI
+
+```bash
+./scripts/sync-env-from-getv.sh llm/groq   # zmienne → .env
+./scripts/install-mcp-stack.sh             # MCP + nlp2uri + getv
+```
+
+## Dokumentacja
+
+- [docs/ORCHESTRATION.md](docs/ORCHESTRATION.md)
+- [docs/INTEGRATION.md](docs/INTEGRATION.md)
+
+
+## License
+
+Licensed under Apache-2.0.

todomat-0.2.1/README.md

@@ -0,0 +1,94 @@
+# Todomat
+
+
+## AI Cost Tracking
+
+![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.2.1-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![AI Cost](https://img.shields.io/badge/AI%20Cost-$0.15-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-1.0h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
+
+- 🤖 **LLM usage:** $0.1500 (1 commits)
+- 👤 **Human dev:** ~$100 (1.0h @ $100/h, 30min dedup)
+
+Generated on 2026-06-07 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
+
+---
+
+Stack testowy strony www dla klientów wdrażających automatyzację przez prompty.
+
+Łączy **Open WebUI** z **curllm** (dane online), **NLP2DSL** (procesy biznesowe) i **ITERUN** (usługi/API/stacki) przez OpenAI-compatible router.
+
+## Szybki start
+
+```bash
+cp .env.example .env
+./scripts/bootstrap.sh
+./scripts/test-local.sh
+```
+
+## Endpointy
+
+| Usługa | URL |
+|--------|-----|
+| Open WebUI | http://localhost:3000 |
+| Pipeline Router | http://localhost:9099/v1 |
+| Trigger Gateway | http://localhost:8084/trigger |
+| curllm API (opcjonalnie) | http://localhost:8810 |
+
+## curllm — dane z internetu
+
+```bash
+./scripts/start-curllm.sh   # opcjonalnie, pełny browser+LLM
+```
+
+Domyślnie adapter używa lekkiego HTTP fetch (`CURLLM_LIGHT_FETCH=1`). Pełny curllm: `CURLLM_LIGHT_FETCH=0` + uruchomiony API na :8810.
+
+## Open WebUI — połączenie
+
+Admin → Settings → Connections:
+
+```
+Base URL: http://pipeline-router:9099/v1   # gdy Open WebUI w sieci todomat
+API Key:  dev-key
+```
+
+Jeśli Open WebUI działa poza compose: `http://host.docker.internal:9099/v1`.
+Po `./scripts/bootstrap.sh` kontener `openwebui` jest automatycznie podłączany do sieci `todomat_todomat-net`.
+
+## Przykładowe prompty
+
+Zob. `examples/prompts/` — w tym [orchestration.md](examples/prompts/orchestration.md) (usługi, getv, desktop, workflow).
+
+## MCP (Cursor / agenty)
+
+Jeden router MCP routuje do curllm, nlp2dsl i iterun:
+
+```bash
+pip install -e .
+./scripts/start-mcp.sh
+```
+
+Dokumentacja: [docs/MCP.md](docs/MCP.md) · konfiguracja Cursor: `examples/mcp-cursor.json`
+
+## Orchestracja (URI, MCP, wiele usług)
+
+Przewodnik uruchomienia i kontroli usług, artefaktów, zmiennych getv i zadań:
+
+- **[docs/ORCHESTRATION.md](docs/ORCHESTRATION.md)** — trigger-gateway, MCP, scenariusze
+- [docs/MCP.md](docs/MCP.md) — router `todomat-mcp`
+- [docs/INTEGRATION.md](docs/INTEGRATION.md) — Open WebUI
+- [nlp2uri orchestration](https://github.com/semcod/nlp2uri/blob/main/docs/orchestration.md) — schematy URI
+
+```bash
+./scripts/sync-env-from-getv.sh llm/groq   # zmienne → .env
+./scripts/install-mcp-stack.sh             # MCP + nlp2uri + getv
+```
+
+## Dokumentacja
+
+- [docs/ORCHESTRATION.md](docs/ORCHESTRATION.md)
+- [docs/INTEGRATION.md](docs/INTEGRATION.md)
+
+
+## License
+
+Licensed under Apache-2.0.

todomat-0.2.1/pyproject.toml

@@ -0,0 +1,77 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "todomat"
+version = "0.2.1"
+description = "Todomat — TODO orchestration with NLP2DSL, ITERUN, and curllm pipelines"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+dependencies = [
+  "httpx>=0.26.0",
+  "pydantic>=2.0",
+  "beautifulsoup4>=4.12",
+]
+
+[project.optional-dependencies]
+mcp = [
+  "mcp>=1.0.0",
+]
+services = [
+  "fastapi>=0.115",
+  "uvicorn[standard]>=0.32",
+]
+dev = [
+  "pytest>=8.0",
+  "goal>=2.1.0",
+  "costs>=0.1.20",
+  "pfix>=0.1.60",
+]
+
+[dependency-groups]
+dev = [
+  "pytest>=8.0",
+]
+
+[project.scripts]
+todomat-mcp = "todomat_mcp.server:main"
+
+[tool.setuptools.packages.find]
+include = ["todomat*", "todomat_mcp*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+pythonpath = ["."]
+addopts = "-v --tb=short"
+
+[tool.pfix]
+# Self-healing Python configuration
+model = "openrouter/qwen/qwen3-coder-next"
+auto_apply = true
+auto_install_deps = true
+auto_restart = false
+max_retries = 3
+create_backups = false
+git_auto_commit = false
+
+[tool.pfix.runtime_todo]
+enabled = true
+todo_file = "TODO.md"
+min_severity = "low"
+deduplicate = true
+
+[tool.costs]
+# AI Cost tracking configuration
+badge = true
+update_readme = true
+readme_path = "README.md"
+default_model = "openrouter/qwen/qwen3-coder-next"
+analysis_mode = "byok"
+full_history = true
+max_commits = 500
+
+# Cost thresholds for badge colors (USD)
+badge_color_thresholds = { low = 1.0, medium = 5.0, high = 10.0, critical = 50.0 }

todomat-0.2.1/setup.cfg

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

todomat-0.2.1/tests/test_contracts.py

@@ -0,0 +1,47 @@
+"""Domain contract tests."""
+
+import pytest
+
+from todomat.domains.engines.nlp2dsl import Nlp2dslEngine, mock_workflow
+from todomat.domains.routing.intent import resolve_plan
+from todomat.domains.shared.config import _mock_for_engine
+from todomat.domains.shared.contracts import TodoIntentRequest, TodoResult
+from todomat.domains.shared.config import EngineConfig
+
+
+def test_resolve_plan_with_model():
+    plan = resolve_plan(TodoIntentRequest(text="pobierz https://x.com", model="curllm-web-research"))
+    assert plan.pipeline == "curllm"
+    assert plan.execute is True
+
+
+def test_todo_result_roundtrip():
+    payload = {"status": "complete", "summary": "ok", "dsl": {"steps": []}, "mock": True}
+    result = TodoResult.from_engine_payload(payload, pipeline="nlp2dsl")
+    data = result.to_dict()
+    assert data["pipeline"] == "nlp2dsl"
+    assert data["dsl"] == {"steps": []}
+
+
+def test_nlp2dsl_mock_engine():
+    import asyncio
+
+    engine = Nlp2dslEngine(EngineConfig(mock=True, upstream_url="http://localhost:8010"))
+    out = asyncio.run(engine.process("wyślij fakturę 200 PLN", execute=False))
+    assert out["mock"] is True
+    assert "send_invoice" in str(out["dsl"])
+
+
+def test_mock_workflow_invoice_amount():
+    out = mock_workflow("faktura 999 PLN", execute=True)
+    step = out["dsl"]["steps"][0]
+    assert step["config"]["amount"] == 999.0
+
+
+def test_per_engine_mock_env(monkeypatch):
+    monkeypatch.delenv("MOCK_MODE", raising=False)
+    monkeypatch.setenv("NLP2DSL_MOCK_MODE", "0")
+    assert _mock_for_engine("nlp2dsl") is False
+    monkeypatch.delenv("NLP2DSL_MOCK_MODE", raising=False)
+    monkeypatch.setenv("MOCK_MODE", "1")
+    assert _mock_for_engine("nlp2dsl") is True

todomat-0.2.1/tests/test_format_incomplete.py

@@ -0,0 +1,15 @@
+from todomat.domains.openai.format import format_chat_response
+
+
+def test_incomplete_shows_prompt_user():
+    result = {
+        "status": "incomplete",
+        "pipeline": "nlp2dsl",
+        "summary": "Status: incomplete",
+        "prompt_user": "Podaj: adres e-mail odbiorcy, treść wiadomości (body)",
+        "missing_fields": ["send_email.to", "send_email.body"],
+    }
+    text = format_chat_response("orchestrator-auto", result)
+    assert "Podaj:" in text
+    assert "send_email.to" in text
+    assert "incomplete" in text.lower() or "uzupełnienia" in text.lower()

todomat-0.2.1/tests/test_nlp2dsl_errors.py

@@ -0,0 +1,32 @@
+from todomat.domains.engines.errors import normalize_nlp2dsl_prompt, parse_upstream_error
+from todomat.domains.openai.format import format_chat_response
+
+
+class _FakeResponse:
+    def __init__(self, payload: dict, status_code: int = 422) -> None:
+        self._payload = payload
+        self.status_code = status_code
+
+    def json(self) -> dict:
+        return self._payload
+
+
+def test_normalize_z_trescja():
+    text = "Wyślij email do jan@firma.pl z treścią: Dzień dobry"
+    assert "treść:" in normalize_nlp2dsl_prompt(text).lower()
+
+
+def test_parse_nested_upstream_error():
+    resp = _FakeResponse({"detail": {"detail": {"error": "Nie rozpoznano intencji", "hint": "Spróbuj fakturę"}}})
+    out = parse_upstream_error(resp)
+    assert out["status"] == "error"
+    assert out["hint"] == "Spróbuj fakturę"
+
+
+def test_format_error_response():
+    text = format_chat_response(
+        "orchestrator-auto",
+        {"status": "error", "pipeline": "nlp2dsl", "error": "Nie rozpoznano intencji", "hint": "Spróbuj fakturę"},
+    )
+    assert "Wskazówka" in text
+    assert "Spróbuj fakturę" in text

todomat-0.2.1/tests/test_nlp2uri_engine.py

@@ -0,0 +1,21 @@
+"""nlp2uri engine mock tests."""
+
+import asyncio
+
+from todomat.domains.engines.nlp2uri import Nlp2uriEngine
+from todomat.domains.shared.config import EngineConfig
+
+
+def test_nlp2uri_engine_mock_desktop():
+    engine = Nlp2uriEngine(EngineConfig(mock=True, upstream_url=""))
+    result = asyncio.run(engine.process("otwórz firefox", execute=False))
+    assert result["status"] == "ok"
+    assert result["mock"] is True
+    assert "firefox" in result["plan"]["uri"]
+
+
+def test_nlp2uri_engine_mock_getv():
+    engine = Nlp2uriEngine(EngineConfig(mock=True, upstream_url=""))
+    result = asyncio.run(engine.process("pokaż GROQ_API_KEY z getv", execute=False))
+    assert result["source"] == "getv"
+    assert result["uri"].startswith("getv://")

todomat-0.2.1/tests/test_routing.py

@@ -0,0 +1,63 @@
+"""Routing logic tests — no MCP subprocess."""
+
+from todomat_mcp.routing import (
+    detect_pipeline,
+    downstream_target,
+    parse_execute_flag,
+    route_decision,
+    route_model,
+)
+
+
+def test_detect_curllm_online():
+    assert detect_pipeline("pobierz dane z https://example.com") == "online-auto"
+
+
+def test_detect_iterun_service():
+    assert detect_pipeline("utwórz mikroserwis fastapi z redis") == "iterun"
+
+
+def test_detect_iterun_web_contact_app():
+    assert detect_pipeline("stworz aplikacje web kontaktu dla firmy") == "iterun"
+    assert route_model("orchestrator-auto", "stworz aplikacje web kontaktu dla firmy") == "iterun"
+
+
+def test_detect_nlp2dsl_default():
+    assert detect_pipeline("wyślij fakturę do klienta po opłaceniu zamówienia") == "nlp2dsl"
+
+
+def test_downstream_after_web():
+    assert downstream_target("pobierz dane i wygeneruj stack docker") == "iterun"
+    assert downstream_target("pobierz dane i zautomatyzuj proces faktury") == "nlp2dsl"
+
+
+def test_route_model_mapping():
+    assert route_model("curllm-web-research", "x") == "curllm"
+    assert route_model("orchestrator-online", "x") == "online-auto"
+    assert route_model("iterun-service-builder", "x") == "iterun"
+
+
+def test_parse_execute_flag_default_execute():
+    text, execute = parse_execute_flag("wyślij fakturę do klienta")
+    assert execute is True
+    assert text == "wyślij fakturę do klienta"
+
+
+def test_parse_execute_flag_dry_run():
+    text, execute = parse_execute_flag("wyślij fakturę --dry-run")
+    assert execute is False
+    assert "--dry-run" not in text
+
+
+def test_detect_nlp2uri_desktop():
+    assert detect_pipeline("otwórz firefox") == "nlp2uri"
+
+
+def test_detect_nlp2uri_getv():
+    assert detect_pipeline("pokaż GROQ_API_KEY z getv") == "nlp2uri"
+
+
+def test_route_decision_auto():
+    d = route_decision("zbuduj api gateway", pipeline="auto")
+    assert d["pipeline"] == "iterun"
+    assert d["service_hints"] is True

todomat-0.2.1/todomat/__init__.py

@@ -0,0 +1,15 @@
+"""Todomat core — shared contracts, routing, engines, and orchestration."""
+
+from todomat.domains.shared.contracts import (
+    ProcessRequest,
+    TodoIntentRequest,
+    TodoPlan,
+    TodoResult,
+)
+
+__all__ = [
+    "ProcessRequest",
+    "TodoIntentRequest",
+    "TodoPlan",
+    "TodoResult",
+]

todomat-0.2.1/todomat/domains/__init__.py

@@ -0,0 +1 @@
+"""Domain layer — contracts, routing, engines, orchestration."""

todomat-0.2.1/todomat/domains/engines/__init__.py

@@ -0,0 +1,6 @@
+from todomat.domains.engines.curllm import CurllmEngine
+from todomat.domains.engines.iterun import IterunEngine
+from todomat.domains.engines.nlp2dsl import Nlp2dslEngine
+from todomat.domains.engines.nlp2uri import Nlp2uriEngine
+
+__all__ = ["CurllmEngine", "IterunEngine", "Nlp2dslEngine", "Nlp2uriEngine"]

todomat-0.2.1/todomat/domains/engines/curllm.py

@@ -0,0 +1,131 @@
+"""curllm web-research engine — light HTTP, upstream API, or mock."""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+import httpx
+from bs4 import BeautifulSoup
+
+from todomat.domains.shared.config import CurllmEngineConfig
+
+URL_RE = re.compile(r"https?://[^\s<>\"']+", re.I)
+
+
+def extract_url(text: str, explicit: str | None = None) -> str | None:
+    if explicit:
+        return explicit.strip()
+    match = URL_RE.search(text)
+    return match.group(0).rstrip(".,);]") if match else None
+
+
+def instruction_from_text(text: str, url: str) -> str:
+    cleaned = text.replace(url, "").strip()
+    if cleaned:
+        return cleaned
+    return "extract page title, main text summary and all links"
+
+
+def light_fetch(url: str, instruction: str) -> dict[str, Any]:
+    with httpx.Client(timeout=30.0, follow_redirects=True) as client:
+        resp = client.get(url, headers={"User-Agent": "todomat-curllm-adapter/0.1"})
+        resp.raise_for_status()
+        html = resp.text
+
+    soup = BeautifulSoup(html, "html.parser")
+    title = (soup.title.string or "").strip() if soup.title else ""
+    paragraphs = [p.get_text(" ", strip=True) for p in soup.find_all("p")[:8]]
+    text_summary = " ".join(p for p in paragraphs if p)[:2000]
+    links = []
+    for a in soup.find_all("a", href=True)[:30]:
+        href = a["href"]
+        if href.startswith("http"):
+            links.append({"text": a.get_text(strip=True)[:120], "href": href})
+
+    return {
+        "mode": "light_http",
+        "url": url,
+        "instruction": instruction,
+        "title": title,
+        "summary": text_summary or title,
+        "links": links,
+        "status_code": resp.status_code,
+    }
+
+
+async def curllm_fetch(url: str, instruction: str, upstream: str) -> dict[str, Any]:
+    async with httpx.AsyncClient(timeout=300.0) as client:
+        resp = await client.post(
+            f"{upstream.rstrip('/')}/api/execute",
+            json={
+                "url": url,
+                "data": instruction,
+                "visual_mode": False,
+                "stealth_mode": False,
+                "headers": {"Accept-Language": "pl-PL,pl;q=0.9"},
+            },
+        )
+        resp.raise_for_status()
+        data = resp.json()
+
+    return {
+        "mode": "curllm",
+        "url": url,
+        "instruction": instruction,
+        "success": data.get("success", True),
+        "result": data.get("result") or data,
+        "steps_taken": data.get("steps_taken"),
+        "run_log": data.get("run_log"),
+    }
+
+
+def context_block(web: dict[str, Any]) -> str:
+    payload = {k: v for k, v in web.items() if k not in {"raw"}}
+    return json.dumps(payload, ensure_ascii=False, indent=2)
+
+
+class CurllmEngine:
+    def __init__(self, config: CurllmEngineConfig) -> None:
+        self.config = config
+
+    async def fetch_web(
+        self,
+        text: str,
+        *,
+        url: str | None = None,
+        instruction: str | None = None,
+    ) -> dict[str, Any]:
+        target_url = extract_url(text, url)
+        if not target_url:
+            raise ValueError("Brak URL w prompcie — podaj https://...")
+
+        instr = instruction or instruction_from_text(text, target_url)
+
+        if self.config.mock or self.config.light_fetch:
+            try:
+                return light_fetch(target_url, instr)
+            except Exception as exc:
+                if self.config.mock:
+                    return {
+                        "mode": "mock",
+                        "url": target_url,
+                        "instruction": instr,
+                        "summary": f"Mock fetch dla {target_url}",
+                        "links": [],
+                        "error": str(exc),
+                    }
+                raise
+
+        return await curllm_fetch(target_url, instr, self.config.upstream_url)
+
+    async def process(self, text: str, *, execute: bool = False) -> dict[str, Any]:
+        web = await self.fetch_web(text)
+        return {
+            "status": "complete",
+            "summary": f"Pobrano dane online z {web.get('url')} ({web.get('mode')})",
+            "web_data": web,
+            "context": context_block(web),
+            "mock": web.get("mode") in {"mock", "light_http"},
+        }

todomat-0.2.1/todomat/domains/engines/errors.py

@@ -0,0 +1,44 @@
+"""Parse upstream HTTP errors into user-facing payloads."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+def normalize_nlp2dsl_prompt(text: str) -> str:
+    """Rewrite common Polish phrasing so NLP2DSL rules parser recognizes fields."""
+    import re
+
+    text = re.sub(r"\bz\s+treścią\s*:", "treść:", text, flags=re.IGNORECASE)
+    text = re.sub(r"\bz\s+trescia\s*:", "treść:", text, flags=re.IGNORECASE)
+    return text
+
+
+def parse_upstream_error(resp: httpx.Response) -> dict[str, Any]:
+    try:
+        data = resp.json()
+    except Exception:
+        return {"status": "error", "summary": (resp.text or "Błąd upstream")[:500]}
+
+    detail: Any = data
+    for _ in range(5):
+        if isinstance(detail, dict) and set(detail.keys()) == {"detail"}:
+            detail = detail["detail"]
+        else:
+            break
+
+    if isinstance(detail, dict):
+        error = detail.get("error")
+        hint = detail.get("hint")
+        summary = hint or error or detail.get("message") or str(detail)
+        return {
+            "status": "error",
+            "summary": summary,
+            "error": error,
+            "hint": hint,
+            "text": detail.get("text"),
+        }
+
+    return {"status": "error", "summary": str(detail)[:500]}