Upload 6 files

llm_services/__init__.py

@@ -0,0 +1 @@
+"""Optional external LLM services for WaterScopeAI-Search."""

llm_services/agent_prompts.py

@@ -0,0 +1,58 @@
+"""Exact WaterScopeAI agent prompt text copied from the public model Space app.py.
+Source: EnvironmentalAI/WaterScopeAI, commit b248182, app.py agent_run().
+Do not edit text without incrementing the prompt version.
+"""
+import hashlib
+import json
+
+PROMPT_VERSION = "waterscope-agent-b248182"
+AGENT_APPLICATIONS = {
+    "general_qa": {"label": "General environmental QA", "instruction": "Answer the technical question directly. Distinguish facts, assumptions, and recommendations."},
+    "document_qa": {"label": "Document-grounded QA", "instruction": "Use the supplied context as the only source for document-specific claims. State clearly when the context does not support an answer."},
+    "paper_synthesis": {"label": "Multi-paper synthesis", "instruction": "Compare the supplied papers with explicit source attribution. Preserve key methods and quantitative findings and do not mix evidence among papers."},
+    "method_recommendation": {"label": "Method recommendation", "instruction": "Recommend a method using explicit evidence, implementation constraints, limitations, and uncertainty. Do not claim superiority unless the supplied evidence directly supports it."},
+    "research_gaps": {"label": "Research-gap identification", "instruction": "Identify evidence-grounded research gaps. Link every gap to a specific limitation or unresolved issue in the supplied context."},
+    "claim_check": {"label": "Unsupported-claim check", "instruction": "Evaluate whether the requested claim is supported. Refuse to invent a paper, method, value, causal relationship, or percentage."},
+}
+
+def build_agent_messages(application: str, context: str, question: str) -> list[dict[str, str]]:
+    """Mirrors WaterScopeAI app.py agent_run() system/user message construction."""
+    if application not in AGENT_APPLICATIONS:
+        raise ValueError(f"Unknown application: {application}")
+    if not isinstance(question, str) or not question.strip():
+        raise ValueError("question must be nonempty")
+    application_config = AGENT_APPLICATIONS[application]
+    system_prompt = f"""
+You are WaterScope-AI, an expert scientific agent for water, wastewater,
+environmental engineering, and sustainability.
+
+Application: {application_config["label"]}
+Task behavior: {application_config["instruction"]}
+
+Core requirements:
+- Answer the user's actual task directly.
+- Preserve important quantitative values and units.
+- Preserve proper nouns, geographic names, paper titles, symbols, and
+non-ASCII scientific notation exactly as they appear in the supplied context.
+- Do not translate or anglicize geographic names unless the user asks.
+- Attribute document-specific evidence clearly.
+- Separate evidence from inference and recommendation.
+- Never invent papers, citations, numerical values, standards, or findings.
+- When evidence is insufficient, say exactly what cannot be concluded.
+- Avoid repeated sentences or sections and stop when complete.
+""".strip()
+    context = (context or "").strip()
+    user_content = question.strip()
+    if context:
+        user_content = (
+            "SUPPLIED CONTEXT\n"
+            "================\n"
+            f"{context}\n\n"
+            "USER TASK\n"
+            "=========\n"
+            f"{question.strip()}"
+        )
+    return [{"role": "system", "content": system_prompt}, {"role": "user", "content": user_content}]
+
+def prompt_sha256(messages: list[dict]) -> str:
+    return hashlib.sha256(json.dumps(messages, ensure_ascii=False, sort_keys=True).encode('utf-8')).hexdigest()

llm_services/llm_client.py

@@ -0,0 +1,25 @@
+"""Unified optional external-model call; no changes to HF inference routing."""
+import os
+import time
+from .agent_prompts import build_agent_messages, prompt_sha256, PROMPT_VERSION
+from .llm_usage import usage_summary
+
+def generate(messages, *, provider='azure', model=None, max_completion_tokens=1200):
+    if os.getenv("ENABLE_EXTERNAL_LLM", "false").lower() not in {"1", "true", "yes"}:
+        raise RuntimeError("External LLM calls are disabled (ENABLE_EXTERNAL_LLM=false)")
+    if provider != "azure":
+        raise ValueError(f"Unsupported provider: {provider}. Azure is implemented in Stage 1.")
+    from .providers.azure import complete
+    started = time.monotonic()
+    result = complete(messages, model=model, max_completion_tokens=max_completion_tokens)
+    result['elapsed_s'] = round(time.monotonic() - started, 3)
+    result['metering'] = usage_summary(result)
+    return result
+
+def run_application(*, application, context, question, provider='azure', model=None, max_completion_tokens=1200):
+    messages = build_agent_messages(application, context, question)
+    result = generate(messages, provider=provider, model=model, max_completion_tokens=max_completion_tokens)
+    result['application'] = application
+    result['prompt_version'] = PROMPT_VERSION
+    result['prompt_sha256'] = prompt_sha256(messages)
+    return result

llm_services/llm_usage.py

@@ -0,0 +1,30 @@
+"""Safe usage summaries; no prompts or credential values are stored.
+Provide provider-specific prices through environment variables if desired;
+otherwise estimated_cost_usd is None (not an asserted price).
+"""
+import os
+
+def estimate_cost_usd(provider: str, usage: dict):
+    prefix = provider.upper()
+    in_price = os.getenv(f"{prefix}_INPUT_USD_PER_M")
+    out_price = os.getenv(f"{prefix}_OUTPUT_USD_PER_M")
+    if not in_price or not out_price:
+        return None
+    n_in = usage.get("input_tokens")
+    n_out = usage.get("output_tokens")
+    if n_in is None or n_out is None:
+        return None
+    try:
+        cost = (n_in * float(in_price) + n_out * float(out_price)) / 1_000_000
+        return round(cost, 8)
+    except (ValueError, TypeError):
+        return None
+
+def usage_summary(result: dict):
+    return {
+        "provider": result["provider"],
+        "model": result["model_requested"],
+        "elapsed_s": result.get("elapsed_s"),
+        "usage": result.get("usage", {}),
+        "estimated_cost_usd": estimate_cost_usd(result["provider"], result.get("usage", {})),
+    }

llm_services/providers/__init__.py

@@ -0,0 +1 @@
+"""Provider adapters."""

llm_services/providers/azure.py

@@ -0,0 +1,37 @@
+"""Azure Chat Completions adapter. Secrets never appear in responses/logs."""
+import os
+from openai import AzureOpenAI
+
+def create_client():
+    endpoint = os.environ["AZURE_OPENAI_ENDPOINT"]
+    key = os.environ["AZURE_OPENAI_API_KEY"]
+    return AzureOpenAI(
+        azure_endpoint=endpoint,
+        api_key=key,
+        api_version=os.getenv("AZURE_OPENAI_API_VERSION", "2024-12-01-preview"),
+        timeout=float(os.getenv("EXTERNAL_LLM_TIMEOUT_S", "120")),
+        max_retries=1,
+    )
+
+def complete(messages, *, model=None, max_completion_tokens=1200):
+    deployment = model or os.getenv("AZURE_LLM_DEPLOYMENT", "gpt-5.4-mini")
+    response = create_client().chat.completions.create(
+        model=deployment,
+        messages=messages,
+        max_completion_tokens=max_completion_tokens,
+    )
+    choice = response.choices[0]
+    usage = response.usage
+    details = getattr(usage, "prompt_tokens_details", None) if usage else None
+    return {
+        "answer": choice.message.content or "",
+        "provider": "azure", "model_requested": deployment,
+        "model_returned": response.model,
+        "finish_reason": choice.finish_reason,
+        "usage": {
+            "input_tokens": usage.prompt_tokens if usage else None,
+            "output_tokens": usage.completion_tokens if usage else None,
+            "total_tokens": usage.total_tokens if usage else None,
+            "cached_input_tokens": getattr(details, "cached_tokens", None),
+        },
+    }