Update app.py

app.py

@@ -5,7 +5,6 @@ import uuid
 import logging
 import asyncio
 import hashlib
-import re
 import sqlite3
 from enum import Enum
 from concurrent.futures import ThreadPoolExecutor
@@ -15,28 +14,51 @@ import g4f
 from fastapi import FastAPI, HTTPException, Request
 from fastapi.responses import StreamingResponse, JSONResponse
 from pydantic import BaseModel, Field
-from jsonschema import Draft202012Validator
 
 logging.basicConfig(
-    level=logging.INFO,
-    format="%(asctime)s [%(levelname)s] %(message)s"
+    level=os.getenv("LOG_LEVEL", "INFO").upper(),
+    format="%(asctime)s [%(levelname)s] %(message)s",
 )
-logger = logging.getLogger("g4f-qwen-agent")
+logger = logging.getLogger("g4f-qwen-openai-agent")
 
-_POOL = ThreadPoolExecutor(max_workers=8)
+# =====================================================
+# CONFIG
+# =====================================================
+
+_POOL = ThreadPoolExecutor(
+    max_workers=int(os.getenv("WORKERS", "8"))
+)
 
 API_KEY = os.getenv("API_KEY", "mysecretkey123")
 DB_PATH = os.getenv("DB_PATH", "memory.db")
-MAX_TOOL_RETRIES = int(os.getenv("MAX_TOOL_RETRIES", "2"))
+
+CACHE_TTL = int(os.getenv("CACHE_TTL", "300"))
 MEMORY_LIMIT = int(os.getenv("MEMORY_LIMIT", "100"))
+MAX_TOOL_RETRIES = int(os.getenv("MAX_TOOL_RETRIES", "2"))
 
 # =====================================================
 # SQLITE MEMORY
 # =====================================================
 
+_DB_LOCK = asyncio.Lock()
+
+
+def _db_connect():
+    db = sqlite3.connect(
+        DB_PATH,
+        timeout=30,
+        check_same_thread=False,
+    )
+    db.execute("PRAGMA journal_mode=WAL")
+    db.execute("PRAGMA synchronous=NORMAL")
+    db.execute("PRAGMA busy_timeout=30000")
+    return db
+
+
 def init_db():
-    with sqlite3.connect(DB_PATH) as db:
-        db.execute("""
+    with _db_connect() as db:
+        db.execute(
+            """
             CREATE TABLE IF NOT EXISTS messages (
                 id INTEGER PRIMARY KEY AUTOINCREMENT,
                 conversation_id TEXT NOT NULL,
@@ -45,88 +67,204 @@ def init_db():
                 tool_call_id TEXT,
                 name TEXT,
                 tool_calls TEXT,
-                created_at REAL NOT NULL
+                message_hash TEXT NOT NULL,
+                created_at REAL NOT NULL,
+                UNIQUE(conversation_id, message_hash)
             )
-        """)
-        db.execute("""
+            """
+        )
+
+        db.execute(
+            """
             CREATE INDEX IF NOT EXISTS idx_messages_conversation
             ON messages(conversation_id, id)
-        """)
+            """
+        )
+
         db.commit()
 
 
-def save_message(conversation_id: str, message: Dict[str, Any]):
-    with sqlite3.connect(DB_PATH) as db:
+def _canonical_json(value: Any) -> str:
+    return json.dumps(
+        value,
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+        default=str,
+    )
+
+
+def _message_hash(message: Dict[str, Any]) -> str:
+    return hashlib.sha256(
+        _canonical_json(message).encode("utf-8")
+    ).hexdigest()
+
+
+def _encode_content(content: Any) -> str:
+    return _canonical_json(content)
+
+
+def _decode_content(content: Optional[str]) -> Any:
+    if content is None:
+        return None
+
+    try:
+        return json.loads(content)
+    except Exception:
+        return content
+
+
+def save_message_sync(
+    conversation_id: str,
+    message: Dict[str, Any],
+):
+    normalized = {
+        key: value
+        for key, value in message.items()
+        if value is not None
+    }
+
+    message_hash = _message_hash(normalized)
+
+    with _db_connect() as db:
         db.execute(
             """
-            INSERT INTO messages (
+            INSERT OR IGNORE INTO messages (
                 conversation_id,
                 role,
                 content,
                 tool_call_id,
                 name,
                 tool_calls,
+                message_hash,
                 created_at
             )
-            VALUES (?, ?, ?, ?, ?, ?, ?)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
             """,
             (
                 conversation_id,
-                message.get("role", "user"),
-                json.dumps(message.get("content"), ensure_ascii=False)
-                if not isinstance(message.get("content"), str)
-                else message.get("content"),
-                message.get("tool_call_id"),
-                message.get("name"),
-                json.dumps(message.get("tool_calls"), ensure_ascii=False)
-                if message.get("tool_calls")
+                normalized.get("role", "user"),
+                _encode_content(normalized.get("content")),
+                normalized.get("tool_call_id"),
+                normalized.get("name"),
+                _canonical_json(normalized.get("tool_calls"))
+                if normalized.get("tool_calls") is not None
                 else None,
+                message_hash,
                 time.time(),
             ),
         )
+
         db.commit()
 
 
-def load_memory(conversation_id: str, limit: int = MEMORY_LIMIT):
-    with sqlite3.connect(DB_PATH) as db:
+def save_messages_sync(
+    conversation_id: str,
+    messages: List[Dict[str, Any]],
+):
+    for message in messages:
+        save_message_sync(conversation_id, message)
+
+
+def load_memory_sync(
+    conversation_id: str,
+    limit: int = MEMORY_LIMIT,
+) -> List[Dict[str, Any]]:
+
+    with _db_connect() as db:
         rows = db.execute(
             """
-            SELECT role, content, tool_call_id, name, tool_calls
+            SELECT
+                role,
+                content,
+                tool_call_id,
+                name,
+                tool_calls
             FROM messages
             WHERE conversation_id = ?
             ORDER BY id DESC
             LIMIT ?
             """,
-            (conversation_id, limit),
+            (
+                conversation_id,
+                limit,
+            ),
         ).fetchall()
 
     rows.reverse()
 
-    messages = []
+    result = []
 
-    for role, content, tool_call_id, name, tool_calls in rows:
-        msg = {"role": role}
+    for (
+        role,
+        content,
+        tool_call_id,
+        name,
+        tool_calls,
+    ) in rows:
 
-        try:
-            msg["content"] = json.loads(content)
-        except Exception:
-            msg["content"] = content
+        message = {
+            "role": role,
+            "content": _decode_content(content),
+        }
 
         if tool_call_id:
-            msg["tool_call_id"] = tool_call_id
+            message["tool_call_id"] = tool_call_id
 
         if name:
-            msg["name"] = name
+            message["name"] = name
 
         if tool_calls:
             try:
-                msg["tool_calls"] = json.loads(tool_calls)
+                message["tool_calls"] = json.loads(tool_calls)
             except Exception:
                 pass
 
-        messages.append(msg)
+        result.append(message)
+
+    return result
+
+
+async def save_message(
+    conversation_id: str,
+    message: Dict[str, Any],
+):
+    loop = asyncio.get_running_loop()
+
+    await loop.run_in_executor(
+        _POOL,
+        save_message_sync,
+        conversation_id,
+        message,
+    )
+
+
+async def save_messages(
+    conversation_id: str,
+    messages: List[Dict[str, Any]],
+):
+    loop = asyncio.get_running_loop()
+
+    await loop.run_in_executor(
+        _POOL,
+        save_messages_sync,
+        conversation_id,
+        messages,
+    )
+
+
+async def load_memory(
+    conversation_id: str,
+) -> List[Dict[str, Any]]:
+
+    loop = asyncio.get_running_loop()
 
-    return messages
+    return await loop.run_in_executor(
+        _POOL,
+        load_memory_sync,
+        conversation_id,
+        MEMORY_LIMIT,
+    )
 
 
 init_db()
@@ -136,77 +274,109 @@ init_db()
 # =====================================================
 
 def _load_cookies_raw() -> Dict[str, Any]:
-    raw_env = (os.getenv("COOKIES_JSON") or "").strip()
+
+    raw_env = (
+        os.getenv("COOKIES_JSON")
+        or ""
+    ).strip()
 
     if raw_env:
         try:
             return json.loads(raw_env)
         except Exception as e:
-            logger.warning(e)
+            logger.warning(
+                "Invalid COOKIES_JSON: %s",
+                e,
+            )
 
     try:
         if os.path.exists("cookies.json"):
-            with open("cookies.json", "r", encoding="utf-8") as f:
-                return json.load(f)
+            with open(
+                "cookies.json",
+                "r",
+                encoding="utf-8",
+            ) as file:
+                return json.load(file)
+
     except Exception as e:
-        logger.warning(e)
+        logger.warning(
+            "cookies.json error: %s",
+            e,
+        )
 
     return {}
 
 
 def load_cookies() -> str:
+
     data = _load_cookies_raw()
 
     if not data:
-        return "⚠️ No Cookies"
+        return "No Cookies"
 
     try:
         from g4f.cookies import set_cookies
     except Exception:
-        return "⚠️ Cookies Found"
+        return "Cookies Found"
+
+    for domain, values in data.items():
 
-    for domain, vals in data.items():
         try:
-            dom = domain if "." in domain else f".{domain}.com"
-
-            if isinstance(vals, list):
-                vals = {
-                    x["name"]: x["value"]
-                    for x in vals
-                    if isinstance(x, dict)
-                    and "name" in x
-                    and "value" in x
+            normalized_domain = (
+                domain
+                if "." in domain
+                else f".{domain}.com"
+            )
+
+            if isinstance(values, list):
+                values = {
+                    item["name"]: item["value"]
+                    for item in values
+                    if isinstance(item, dict)
+                    and item.get("name")
+                    and "value" in item
                 }
 
-            if isinstance(vals, dict):
-                set_cookies(dom, vals)
+            if isinstance(values, dict):
+                set_cookies(
+                    normalized_domain,
+                    values,
+                )
 
         except Exception as e:
-            logger.warning(e)
+            logger.warning(
+                "Cookie load error for %s: %s",
+                domain,
+                e,
+            )
 
-    return "✅ Cookies Loaded"
+    return "Cookies Loaded"
 
 
 COOKIE_STATUS = load_cookies()
 
 # =====================================================
-# PROVIDER — QWEN ONLY
+# QWEN PROVIDER ONLY
 # =====================================================
 
 def get_provider(name: str):
+
     try:
-        return getattr(g4f.Provider, name)
+        return getattr(
+            g4f.Provider,
+            name,
+        )
     except Exception:
         return None
 
 
-REAL_PROVIDERS = {
-    "Qwen": get_provider("Qwen"),
-}
+QWEN_PROVIDER = get_provider("Qwen")
+
+if not QWEN_PROVIDER:
+    logger.warning(
+        "Qwen provider was not found in installed g4f version."
+    )
 
-REAL_PROVIDERS = {
-    k: v for k, v in REAL_PROVIDERS.items() if v
-}
 
 QWEN_WORKING_MODELS = [
     "qwen-max",
@@ -219,12 +389,19 @@ QWEN_WORKING_MODELS = [
     "",
 ]
 
-CLAUDE_MODEL_MAP = {
+
+MODEL_MAP = {
     "claude-opus-4-6": "qwen-max",
     "claude-sonnet-4-6": "qwen-max",
     "claude-haiku-4-5": "qwen-plus",
+    "qwen-max": "qwen-max",
+    "qwen-max-latest": "qwen-max-latest",
+    "qwen-plus": "qwen-plus",
+    "qwen-turbo": "qwen-turbo",
 }
 
+PUBLIC_MODELS = list(MODEL_MAP.keys())
+
 # =====================================================
 # CACHE
 # =====================================================
@@ -233,80 +410,213 @@ _CACHE: Dict[str, str] = {}
 _CACHE_TS: Dict[str, float] = {}
 
 
-def cache_get(key):
-    ts = _CACHE_TS.get(key)
+def cache_get(key: str) -> Optional[str]:
 
-    if ts and time.time() - ts < 300:
-        return _CACHE.get(key)
+    timestamp = _CACHE_TS.get(key)
 
-    return None
+    if timestamp is None:
+        return None
+
+    if time.time() - timestamp >= CACHE_TTL:
+        _CACHE.pop(key, None)
+        _CACHE_TS.pop(key, None)
+        return None
+
+    return _CACHE.get(key)
 
 
-def cache_set(key, value):
+def cache_set(
+    key: str,
+    value: str,
+):
     _CACHE[key] = value
     _CACHE_TS[key] = time.time()
 
 # =====================================================
-# STREAM CLEANER
+# G4F RESPONSE HELPERS
 # =====================================================
 
-def _clean_chunk(chunk) -> str:
+def _to_dict(value: Any) -> Any:
+
+    if isinstance(value, dict):
+        return value
+
+    if hasattr(value, "model_dump"):
+        try:
+            return value.model_dump()
+        except Exception:
+            pass
+
+    if hasattr(value, "to_json"):
+        try:
+            raw = value.to_json()
+
+            if isinstance(raw, str):
+                return json.loads(raw)
+
+        except Exception:
+            pass
+
+    return value
+
+
+def _clean_chunk(chunk: Any) -> str:
+
     try:
+        chunk = _to_dict(chunk)
+
         if isinstance(chunk, dict):
+
             choices = chunk.get("choices")
 
             if choices:
-                choice = choices[0]
 
-                delta = choice.get("delta") or {}
-                message = choice.get("message") or {}
+                choice = _to_dict(choices[0])
 
-                return (
-                    delta.get("content")
-                    or delta.get("text")
-                    or message.get("content")
-                    or ""
+                if not isinstance(choice, dict):
+                    return ""
+
+                delta = _to_dict(
+                    choice.get("delta")
+                    or {}
                 )
 
-            return chunk.get("content") or chunk.get("text") or ""
+                message = _to_dict(
+                    choice.get("message")
+                    or {}
+                )
 
-        if isinstance(chunk, str):
-            stripped = chunk.strip()
+                if isinstance(delta, dict):
 
-            if stripped.startswith("{"):
-                try:
-                    data = json.loads(chunk)
+                    content = (
+                        delta.get("content")
+                        or delta.get("text")
+                    )
 
-                    if data.get("code") == "Not_Found":
-                        return ""
+                    if content:
+                        return str(content)
 
-                    choices = data.get("choices")
+                if isinstance(message, dict):
 
-                    if choices:
-                        choice = choices[0]
-                        delta = choice.get("delta") or {}
-                        message = choice.get("message") or {}
+                    content = message.get("content")
 
-                        return (
-                            delta.get("content")
-                            or message.get("content")
-                            or ""
-                        )
+                    if content:
+                        return str(content)
 
-                    return data.get("content") or data.get("text") or ""
+                content = choice.get("text")
+
+                if content:
+                    return str(content)
+
+            content = (
+                chunk.get("content")
+                or chunk.get("text")
+            )
+
+            return (
+                str(content)
+                if content
+                else ""
+            )
+
+        if isinstance(chunk, str):
+
+            stripped = chunk.strip()
+
+            if stripped.startswith("{"):
+
+                try:
+                    parsed = json.loads(stripped)
+                    return _clean_chunk(parsed)
 
                 except Exception:
                     pass
 
-            return chunk.replace("\\n", "\n")
+            return chunk.replace(
+                "\\n",
+                "\n",
+            )
+
+        if chunk is None:
+            return ""
 
         return str(chunk)
 
     except Exception:
         return ""
 
+
+def _extract_native_tool_calls(
+    response: Any,
+) -> Optional[List[Dict[str, Any]]]:
+
+    payload = _to_dict(response)
+
+    if not isinstance(payload, dict):
+        return None
+
+    choices = payload.get("choices")
+
+    if not choices:
+        return None
+
+    choice = _to_dict(choices[0])
+
+    if not isinstance(choice, dict):
+        return None
+
+    message = _to_dict(
+        choice.get("message")
+        or choice.get("delta")
+        or {}
+    )
+
+    if not isinstance(message, dict):
+        return None
+
+    tool_calls = message.get("tool_calls")
+
+    return (
+        tool_calls
+        if isinstance(tool_calls, list)
+        else None
+    )
+
+# =====================================================
+# MODEL FALLBACK
+# =====================================================
+
+def resolve_model(
+    requested_model: str,
+) -> str:
+
+    return MODEL_MAP.get(
+        requested_model,
+        requested_model,
+    )
+
+
+def model_candidates(
+    requested_model: str,
+) -> List[str]:
+
+    target = resolve_model(
+        requested_model
+    )
+
+    result = []
+
+    for model in (
+        [target]
+        + QWEN_WORKING_MODELS
+    ):
+        if model not in result:
+            result.append(model)
+
+    return result
+
 # =====================================================
-# ORIGINAL ASK — MODEL MODE
+# ORIGINAL MODEL MODE ASK
 # =====================================================
 
 def ask(
@@ -315,331 +625,914 @@ def ask(
     provider_name: str,
     model_name: str,
 ):
-    message = (message or "").strip()
+
+    message = (
+        message
+        or ""
+    ).strip()
 
     if not message and not history:
         yield ""
         return
 
-    target_model = CLAUDE_MODEL_MAP.get(model_name, model_name)
+    cache_payload = {
+        "provider": provider_name,
+        "model": model_name,
+        "message": message,
+        "history": history[-20:],
+    }
+
+    cache_key = hashlib.sha256(
+        _canonical_json(
+            cache_payload
+        ).encode("utf-8")
+    ).hexdigest()
 
-    key = (
-        f"{provider_name}|"
-        f"{target_model}|"
-        f"{hash(json.dumps(message, ensure_ascii=False) + json.dumps(history[-3:] if history else [], ensure_ascii=False))}"
+    cached = cache_get(
+        cache_key
     )
 
-    cached = cache_get(key)
-
-    if cached:
+    if cached is not None:
         yield cached
         return
 
-    msgs = []
+    messages = []
+
+    for item in (
+        history[-20:]
+        if history
+        else []
+    ):
+
+        if not isinstance(item, dict):
+            continue
 
-    if history:
-        for item in history[-20:]:
-            if isinstance(item, dict):
-                role = item.get("role")
-                content = item.get("content")
+        role = item.get("role")
+        content = item.get("content")
 
-                if role and content and str(content).strip():
-                    msgs.append({
-                        "role": str(role),
-                        "content": str(content),
-                    })
+        if (
+            role
+            and content is not None
+            and str(content).strip()
+        ):
+            messages.append({
+                "role": str(role),
+                "content": str(content),
+            })
 
     if message:
-        msgs.append({
+        messages.append({
             "role": "user",
             "content": message,
         })
 
-    last_exc = None
+    last_error = None
 
-    provider = REAL_PROVIDERS.get("Qwen")
-
-    candidates = [target_model] + [
-        model
-        for model in QWEN_WORKING_MODELS
-        if model != target_model
-    ]
+    for candidate in model_candidates(
+        model_name
+    ):
 
-    for model in candidates:
         try:
             stream = g4f.ChatCompletion.create(
-                model=model,
-                provider=provider,
-                messages=msgs,
+                model=candidate,
+                provider=QWEN_PROVIDER,
+                messages=messages,
                 stream=True,
             )
 
-            text = ""
+            full_text = ""
 
             for chunk in stream:
-                content = _clean_chunk(chunk)
 
-                if content:
-                    text += content
-                    yield content
+                text = _clean_chunk(
+                    chunk
+                )
+
+                if text:
+                    full_text += text
+                    yield text
+
+            if full_text.strip():
+
+                cache_set(
+                    cache_key,
+                    full_text,
+                )
 
-            if text.strip():
-                cache_set(key, text)
                 return
 
         except Exception as e:
-            err = str(e)
+
+            error_text = str(e)
 
             if (
-                "Not_Found" in err
-                or "Model not found" in err
+                "Not_Found" in error_text
+                or "Model not found" in error_text
             ):
                 continue
 
-            last_exc = e
+            last_error = e
 
-    logger.error("Qwen failed: %s", last_exc)
+            logger.warning(
+                "Qwen model %r failed: %s",
+                candidate,
+                e,
+            )
 
     raise RuntimeError(
-        f"Qwen provider failed: {last_exc}"
+        f"Qwen provider failed: {last_error}"
     )
 
 # =====================================================
-# FULL MESSAGE ASK — AGENT MODE
+# FULL MESSAGE CALL — AGENT MODE
 # =====================================================
 
-def ask_messages(messages: List[Dict[str, Any]], model_name: str):
-    target_model = CLAUDE_MODEL_MAP.get(model_name, model_name)
-
-    provider = REAL_PROVIDERS.get("Qwen")
+def call_qwen_full_messages(
+    messages: List[Dict[str, Any]],
+    model_name: str,
+) -> Tuple[str, Optional[List[Dict[str, Any]]]]:
 
-    candidates = [target_model] + [
-        model
-        for model in QWEN_WORKING_MODELS
-        if model != target_model
-    ]
+    last_error = None
 
-    last_exc = None
+    for candidate in model_candidates(
+        model_name
+    ):
 
-    for model in candidates:
         try:
-            stream = g4f.ChatCompletion.create(
-                model=model,
-                provider=provider,
+
+            response = g4f.ChatCompletion.create(
+                model=candidate,
+                provider=QWEN_PROVIDER,
                 messages=messages,
-                stream=True,
+                stream=False,
             )
 
-            text = ""
-
-            for chunk in stream:
-                content = _clean_chunk(chunk)
+            native_tool_calls = (
+                _extract_native_tool_calls(
+                    response
+                )
+            )
 
-                if content:
-                    text += content
+            text = _clean_chunk(
+                response
+            )
 
-            if text.strip():
-                return text
+            if (
+                native_tool_calls
+                or text.strip()
+            ):
+                return (
+                    text,
+                    native_tool_calls,
+                )
 
         except Exception as e:
-            err = str(e)
+
+            error_text = str(e)
 
             if (
-                "Not_Found" in err
-                or "Model not found" in err
+                "Not_Found" in error_text
+                or "Model not found" in error_text
             ):
                 continue
 
-            last_exc = e
+            last_error = e
+
+            logger.warning(
+                "Qwen agent model %r failed: %s",
+                candidate,
+                e,
+            )
 
     raise RuntimeError(
-        f"Qwen provider failed: {last_exc}"
+        f"Qwen provider failed: {last_error}"
     )
 
 
-async def ask_messages_async(messages, model):
+async def call_qwen_full_messages_async(
+    messages: List[Dict[str, Any]],
+    model_name: str,
+):
+
     loop = asyncio.get_running_loop()
 
     return await loop.run_in_executor(
         _POOL,
-        ask_messages,
+        call_qwen_full_messages,
         messages,
-        model,
+        model_name,
     )
 
 # =====================================================
-# AGENT CONTRACTS
+# LIGHTWEIGHT JSON SCHEMA VALIDATION
+# NO EXTERNAL jsonschema DEPENDENCY
 # =====================================================
 
-class ToolDecisionStatus(str, Enum):
-    VALID = "valid"
-    REPAIRABLE = "repairable"
-    RETRY_REQUIRED = "retry_required"
-    BLOCK = "block"
-    NO_TOOL = "no_tool"
+def _matches_schema_type(
+    value: Any,
+    schema_type: str,
+) -> bool:
 
+    if schema_type == "object":
+        return isinstance(value, dict)
 
-class CanonicalToolCall(BaseModel):
-    id: str
-    name: str
-    arguments: Dict[str, Any] = Field(default_factory=dict)
+    if schema_type == "array":
+        return isinstance(value, list)
 
+    if schema_type == "string":
+        return isinstance(value, str)
 
-class ToolDecision(BaseModel):
-    status: ToolDecisionStatus
-    tool_calls: List[CanonicalToolCall] = Field(default_factory=list)
-    reason: Optional[str] = None
+    if schema_type == "boolean":
+        return isinstance(value, bool)
 
+    if schema_type == "integer":
+        return (
+            isinstance(value, int)
+            and not isinstance(value, bool)
+        )
 
-class ToolRegistry:
+    if schema_type == "number":
+        return (
+            isinstance(value, (int, float))
+            and not isinstance(value, bool)
+        )
 
-    def __init__(self, tools=None):
-        self.tools = {}
+    if schema_type == "null":
+        return value is None
 
-        for tool in tools or []:
-            if (
-                isinstance(tool, dict)
-                and tool.get("type") == "function"
-            ):
-                fn = tool.get("function", {})
-                name = fn.get("name")
+    return True
 
-                if name:
-                    self.tools[name] = tool
 
-    def has(self, name):
-        return name in self.tools
+def validate_schema(
+    value: Any,
+    schema: Dict[str, Any],
+    path: str = "$",
+) -> Optional[str]:
 
-    def schema(self, name):
-        tool = self.tools.get(name)
+    if not isinstance(schema, dict):
+        return None
 
-        if not tool:
-            return {}
+    schema_type = schema.get("type")
 
-        return (
-            tool
-            .get("function", {})
-            .get("parameters", {})
-        )
+    if isinstance(schema_type, list):
 
+        if not any(
+            _matches_schema_type(
+                value,
+                current_type,
+            )
+            for current_type in schema_type
+        ):
+            return (
+                f"{path}: expected one of "
+                f"{schema_type}"
+            )
 
-class ToolProcessor:
+    elif isinstance(schema_type, str):
 
-    def __init__(self, registry):
-        self.registry = registry
+        if not _matches_schema_type(
+            value,
+            schema_type,
+        ):
+            return (
+                f"{path}: expected "
+                f"{schema_type}"
+            )
 
-    def process(
+    if "enum" in schema:
+
+        if value not in schema["enum"]:
+            return (
+                f"{path}: value must be one of "
+                f"{schema['enum']}"
+            )
+
+    if isinstance(value, dict):
+
+        required = schema.get(
+            "required",
+            [],
+        )
+
+        for field_name in required:
+
+            if field_name not in value:
+                return (
+                    f"{path}: missing required "
+                    f"field '{field_name}'"
+                )
+
+        properties = schema.get(
+            "properties",
+            {},
+        )
+
+        for field_name, field_value in value.items():
+
+            field_schema = properties.get(
+                field_name
+            )
+
+            if isinstance(field_schema, dict):
+
+                error = validate_schema(
+                    field_value,
+                    field_schema,
+                    f"{path}.{field_name}",
+                )
+
+                if error:
+                    return error
+
+        if (
+            schema.get("additionalProperties")
+            is False
+        ):
+            allowed = set(
+                properties.keys()
+            )
+
+            unknown = (
+                set(value.keys())
+                - allowed
+            )
+
+            if unknown:
+                return (
+                    f"{path}: unknown fields "
+                    f"{sorted(unknown)}"
+                )
+
+    if isinstance(value, list):
+
+        min_items = schema.get(
+            "minItems"
+        )
+
+        max_items = schema.get(
+            "maxItems"
+        )
+
+        if (
+            isinstance(min_items, int)
+            and len(value) < min_items
+        ):
+            return (
+                f"{path}: requires at least "
+                f"{min_items} items"
+            )
+
+        if (
+            isinstance(max_items, int)
+            and len(value) > max_items
+        ):
+            return (
+                f"{path}: allows at most "
+                f"{max_items} items"
+            )
+
+        item_schema = schema.get(
+            "items"
+        )
+
+        if isinstance(item_schema, dict):
+
+            for index, item in enumerate(value):
+
+                error = validate_schema(
+                    item,
+                    item_schema,
+                    f"{path}[{index}]",
+                )
+
+                if error:
+                    return error
+
+    if isinstance(value, str):
+
+        min_length = schema.get(
+            "minLength"
+        )
+
+        max_length = schema.get(
+            "maxLength"
+        )
+
+        if (
+            isinstance(min_length, int)
+            and len(value) < min_length
+        ):
+            return (
+                f"{path}: string shorter than "
+                f"{min_length}"
+            )
+
+        if (
+            isinstance(max_length, int)
+            and len(value) > max_length
+        ):
+            return (
+                f"{path}: string longer than "
+                f"{max_length}"
+            )
+
+    return None
+
+# =====================================================
+# AGENT CONTRACTS
+# =====================================================
+
+class ToolDecisionStatus(
+    str,
+    Enum,
+):
+    VALID = "valid"
+    REPAIRABLE = "repairable"
+    RETRY_REQUIRED = "retry_required"
+    BLOCK = "block"
+    NO_TOOL = "no_tool"
+
+
+class CanonicalToolCall(BaseModel):
+    id: str
+    name: str
+    arguments: Dict[str, Any] = Field(
+        default_factory=dict
+    )
+
+
+class ToolDecision(BaseModel):
+    status: ToolDecisionStatus
+
+    tool_calls: List[
+        CanonicalToolCall
+    ] = Field(
+        default_factory=list
+    )
+
+    reason: Optional[str] = None
+
+
+class ToolRegistry:
+
+    def __init__(
         self,
-        raw_text: Optional[str],
-        native_calls: Optional[List[dict]] = None,
-    ) -> ToolDecision:
+        tools: Optional[
+            List[Dict[str, Any]]
+        ] = None,
+    ):
 
-        calls = []
+        self._tools: Dict[
+            str,
+            Dict[str, Any]
+        ] = {}
 
-        if native_calls:
-            for call in native_calls:
-                try:
-                    fn = call.get("function", {})
+        for tool in tools or []:
 
-                    arguments = fn.get("arguments", "{}")
+            if not isinstance(
+                tool,
+                dict,
+            ):
+                continue
 
-                    if isinstance(arguments, str):
-                        arguments = json.loads(arguments)
+            if tool.get("type") != "function":
+                continue
 
-                    calls.append(
-                        CanonicalToolCall(
-                            id=call.get("id")
-                            or f"call_{uuid.uuid4().hex[:12]}",
-                            name=fn.get("name", ""),
-                            arguments=arguments,
-                        )
-                    )
+            function = tool.get(
+                "function",
+                {},
+            )
+
+            name = function.get(
+                "name"
+            )
+
+            if name:
+                self._tools[name] = tool
+
+    def has(
+        self,
+        name: str,
+    ) -> bool:
+
+        return name in self._tools
+
+    def schema(
+        self,
+        name: str,
+    ) -> Dict[str, Any]:
+
+        tool = self._tools.get(
+            name
+        )
+
+        if not tool:
+            return {}
+
+        return (
+            tool
+            .get("function", {})
+            .get("parameters", {})
+        )
+
+    def names(self) -> List[str]:
+        return list(
+            self._tools.keys()
+        )
+
+
+def _extract_json_candidate(
+    text: str,
+) -> Optional[Any]:
+
+    if not text:
+        return None
+
+    stripped = text.strip()
+
+    if "```json" in stripped:
+
+        try:
+            stripped = (
+                stripped
+                .split("```json", 1)[1]
+                .split("```", 1)[0]
+                .strip()
+            )
+        except Exception:
+            pass
+
+    try:
+        return json.loads(
+            stripped
+        )
+    except Exception:
+        pass
+
+    decoder = json.JSONDecoder()
+
+    for index, character in enumerate(
+        stripped
+    ):
+
+        if character not in (
+            "{",
+            "[",
+        ):
+            continue
+
+        try:
+            parsed, _ = decoder.raw_decode(
+                stripped[index:]
+            )
+
+            return parsed
+
+        except Exception:
+            continue
+
+    return None
+
+
+class ToolProcessor:
+
+    def __init__(
+        self,
+        registry: ToolRegistry,
+    ):
+        self.registry = registry
+
+    def _normalize_native_calls(
+        self,
+        native_calls: List[Dict[str, Any]],
+    ) -> Tuple[
+        List[CanonicalToolCall],
+        Optional[str],
+    ]:
+
+        result = []
+
+        for call in native_calls:
+
+            call = _to_dict(
+                call
+            )
+
+            if not isinstance(
+                call,
+                dict,
+            ):
+                return (
+                    [],
+                    "Malformed native tool call",
+                )
+
+            function = _to_dict(
+                call.get("function")
+                or {}
+            )
+
+            if not isinstance(
+                function,
+                dict,
+            ):
+                return (
+                    [],
+                    "Malformed native function node",
+                )
+
+            name = (
+                function.get("name")
+                or ""
+            )
+
+            arguments = function.get(
+                "arguments",
+                {},
+            )
 
+            if isinstance(
+                arguments,
+                str,
+            ):
+                try:
+                    arguments = json.loads(
+                        arguments
+                    )
                 except Exception:
-                    return ToolDecision(
-                        status=ToolDecisionStatus.RETRY_REQUIRED,
-                        reason="Malformed native tool call",
+                    return (
+                        [],
+                        (
+                            f"Malformed JSON arguments "
+                            f"for tool '{name}'"
+                        ),
                     )
 
-        elif raw_text:
-            text = raw_text.strip()
+            if not isinstance(
+                arguments,
+                dict,
+            ):
+                return (
+                    [],
+                    (
+                        f"Arguments for tool "
+                        f"'{name}' must be object"
+                    ),
+                )
+
+            result.append(
+                CanonicalToolCall(
+                    id=(
+                        call.get("id")
+                        or
+                        f"call_{uuid.uuid4().hex[:24]}"
+                    ),
+                    name=name,
+                    arguments=arguments,
+                )
+            )
+
+        return result, None
 
-            try:
-                if "```json" in text:
-                    text = (
-                        text
-                        .split("```json", 1)[1]
-                        .split("```", 1)[0]
-                        .strip()
-                    )
+    def _normalize_emulated_calls(
+        self,
+        raw_text: str,
+    ) -> Tuple[
+        List[CanonicalToolCall],
+        Optional[str],
+    ]:
+
+        parsed = _extract_json_candidate(
+            raw_text
+        )
+
+        if parsed is None:
+            return [], None
+
+        calls = []
 
-                parsed = json.loads(text)
+        if isinstance(
+            parsed,
+            dict,
+        ):
 
-                raw_calls = []
+            if isinstance(
+                parsed.get("tool_calls"),
+                list,
+            ):
+                calls = parsed[
+                    "tool_calls"
+                ]
 
-                if isinstance(parsed, dict):
-                    if isinstance(parsed.get("tool_calls"), list):
-                        raw_calls = parsed["tool_calls"]
+            elif parsed.get("name"):
+                calls = [parsed]
 
-                    elif parsed.get("name"):
-                        raw_calls = [parsed]
+            else:
+                return [], None
 
-                for index, call in enumerate(raw_calls):
-                    arguments = call.get("arguments", {})
+        else:
+            return [], None
 
-                    if isinstance(arguments, str):
-                        arguments = json.loads(arguments)
+        normalized = []
 
-                    calls.append(
-                        CanonicalToolCall(
-                            id=call.get("id")
-                            or f"call_emu_{index}_{uuid.uuid4().hex[:8]}",
-                            name=call.get("name", ""),
-                            arguments=arguments,
-                        )
+        for index, call in enumerate(
+            calls
+        ):
+
+            if not isinstance(
+                call,
+                dict,
+            ):
+                return (
+                    [],
+                    "Malformed emulated tool call",
+                )
+
+            function_node = call.get(
+                "function"
+            )
+
+            if isinstance(
+                function_node,
+                dict,
+            ):
+                name = (
+                    function_node.get("name")
+                    or call.get("name")
+                    or ""
+                )
+
+                arguments = (
+                    function_node.get(
+                        "arguments",
+                        call.get(
+                            "arguments",
+                            {},
+                        ),
                     )
+                )
 
-            except Exception:
-                return ToolDecision(
-                    status=ToolDecisionStatus.NO_TOOL
+            else:
+                name = (
+                    call.get("name")
+                    or ""
+                )
+
+                arguments = call.get(
+                    "arguments",
+                    call.get(
+                        "input",
+                        {},
+                    ),
+                )
+
+            if isinstance(
+                arguments,
+                str,
+            ):
+
+                try:
+                    arguments = json.loads(
+                        arguments
+                    )
+
+                except Exception:
+                    return (
+                        [],
+                        (
+                            f"Malformed JSON arguments "
+                            f"for tool '{name}'"
+                        ),
+                    )
+
+            if not isinstance(
+                arguments,
+                dict,
+            ):
+                return (
+                    [],
+                    (
+                        f"Arguments for tool "
+                        f"'{name}' must be object"
+                    ),
+                )
+
+            normalized.append(
+                CanonicalToolCall(
+                    id=(
+                        call.get("id")
+                        or
+                        f"call_emu_{index}_{uuid.uuid4().hex[:16]}"
+                    ),
+                    name=name,
+                    arguments=arguments,
+                )
+            )
+
+        return normalized, None
+
+    def process(
+        self,
+        raw_text: Optional[str],
+        native_calls: Optional[
+            List[Dict[str, Any]]
+        ],
+    ) -> ToolDecision:
+
+        if native_calls:
+
+            calls, error = (
+                self._normalize_native_calls(
+                    native_calls
+                )
+            )
+
+        else:
+
+            calls, error = (
+                self._normalize_emulated_calls(
+                    raw_text or ""
                 )
+            )
+
+        if error:
+
+            return ToolDecision(
+                status=(
+                    ToolDecisionStatus
+                    .RETRY_REQUIRED
+                ),
+                reason=error,
+            )
 
         if not calls:
+
             return ToolDecision(
-                status=ToolDecisionStatus.NO_TOOL
+                status=(
+                    ToolDecisionStatus
+                    .NO_TOOL
+                )
             )
 
         for call in calls:
 
-            if not self.registry.has(call.name):
+            if not call.name:
+
                 return ToolDecision(
-                    status=ToolDecisionStatus.RETRY_REQUIRED,
-                    reason=f"Unknown tool: {call.name}",
+                    status=(
+                        ToolDecisionStatus
+                        .RETRY_REQUIRED
+                    ),
+                    reason=(
+                        "Tool name is missing"
+                    ),
                 )
 
-            if not isinstance(call.arguments, dict):
+            if not self.registry.has(
+                call.name
+            ):
+
                 return ToolDecision(
-                    status=ToolDecisionStatus.RETRY_REQUIRED,
-                    reason=f"Invalid arguments for {call.name}",
+                    status=(
+                        ToolDecisionStatus
+                        .RETRY_REQUIRED
+                    ),
+                    reason=(
+                        f"Unknown tool "
+                        f"'{call.name}'"
+                    ),
                 )
 
-            schema = self.registry.schema(call.name)
-
-            if schema:
-                validator = Draft202012Validator(schema)
+            schema = self.registry.schema(
+                call.name
+            )
 
-                errors = list(
-                    validator.iter_errors(call.arguments)
+            validation_error = (
+                validate_schema(
+                    call.arguments,
+                    schema,
                 )
+            )
 
-                if errors:
-                    return ToolDecision(
-                        status=ToolDecisionStatus.RETRY_REQUIRED,
-                        reason=errors[0].message,
-                    )
+            if validation_error:
+
+                return ToolDecision(
+                    status=(
+                        ToolDecisionStatus
+                        .RETRY_REQUIRED
+                    ),
+                    reason=(
+                        f"Tool '{call.name}' "
+                        f"schema violation: "
+                        f"{validation_error}"
+                    ),
+                )
 
         return ToolDecision(
-            status=ToolDecisionStatus.VALID,
+            status=(
+                ToolDecisionStatus
+                .VALID
+            ),
             tool_calls=calls,
         )
 
@@ -653,26 +1546,37 @@ _HEDGE_PATTERNS = (
     "دعني أتحقق",
     "دعني أتأكد",
     "سأحاول",
+    "سأعمل على",
     "سأنشئ",
     "سأبحث",
     "انتظر",
     "لحظة من فضلك",
+    "امنحني لحظة",
     "let me check",
     "let me verify",
     "i will",
     "i'll",
     "hold on",
     "give me a moment",
+    "i am going to",
+    "i'm going to",
     "please wait",
+    "one moment",
 )
 
 
-def looks_like_unfulfilled_intent(text):
+def looks_like_unfulfilled_intent(
+    text: Optional[str],
+) -> bool:
+
     if not text:
         return False
 
     lowered = text.strip().lower()
 
+    if not lowered:
+        return False
+
     if len(lowered) > 500:
         return False
 
@@ -681,172 +1585,353 @@ def looks_like_unfulfilled_intent(text):
         for pattern in _HEDGE_PATTERNS
     )
 
-# =====================================================
-# TOOL HISTORY SANITIZER
-# =====================================================
+# =====================================================
+# TOOL HISTORY SANITIZER
+# =====================================================
+
+def content_to_text(
+    content: Any,
+) -> str:
+
+    if content is None:
+        return ""
+
+    if isinstance(content, str):
+        return content
+
+    if isinstance(content, list):
+
+        parts = []
+
+        for block in content:
+
+            if not isinstance(
+                block,
+                dict,
+            ):
+                parts.append(
+                    str(block)
+                )
+                continue
+
+            block_type = block.get(
+                "type"
+            )
+
+            if block_type in (
+                "text",
+                "input_text",
+                "output_text",
+            ):
+                parts.append(
+                    str(
+                        block.get(
+                            "text",
+                            ""
+                        )
+                    )
+                )
+
+            elif block_type == "tool_result":
+
+                parts.append(
+                    (
+                        "[Tool Result "
+                        f"{block.get('tool_use_id', '')}] "
+                        f"{block.get('content', '')}"
+                    )
+                )
+
+        return "\n".join(
+            part
+            for part in parts
+            if part
+        )
+
+    return str(content)
+
+
+def sanitize_tool_history(
+    messages: List[Dict[str, Any]],
+) -> List[Dict[str, str]]:
 
-def sanitize_tool_history(messages):
     output = []
 
     for message in messages:
+
         role = message.get("role")
 
         if role == "tool":
+
             output.append({
                 "role": "user",
                 "content": (
-                    f"[Tool Result]\n"
-                    f"Tool: {message.get('name', 'tool')}\n"
-                    f"Tool Call ID: {message.get('tool_call_id', '')}\n"
-                    f"Result: {message.get('content', '')}\n\n"
-                    "Decide immediately whether another tool is required. "
-                    "If another tool is needed, output JSON tool_calls only. "
-                    "Otherwise return the complete final answer."
+                    "[TOOL EXECUTION RESULT]\n"
+                    f"Tool name: {message.get('name', 'tool')}\n"
+                    f"Tool call id: {message.get('tool_call_id', '')}\n"
+                    f"Result:\n{content_to_text(message.get('content'))}\n\n"
+                    "Continue the task now. "
+                    "If another tool is required, "
+                    "call it immediately using the required JSON format. "
+                    "If the task is complete, provide the final answer."
                 ),
             })
 
-        elif (
+            continue
+
+        if (
             role == "assistant"
             and message.get("tool_calls")
         ):
+
             reconstructed = []
 
-            for call in message["tool_calls"]:
-                fn = call.get("function", {})
+            for tool_call in (
+                message.get("tool_calls")
+                or []
+            ):
 
-                arguments = fn.get("arguments", "{}")
+                if not isinstance(
+                    tool_call,
+                    dict,
+                ):
+                    continue
 
-                try:
-                    if isinstance(arguments, str):
-                        arguments = json.loads(arguments)
-                except Exception:
-                    arguments = {}
+                function = tool_call.get(
+                    "function",
+                    {},
+                )
+
+                arguments = function.get(
+                    "arguments",
+                    {},
+                )
+
+                if isinstance(
+                    arguments,
+                    str,
+                ):
+                    try:
+                        arguments = json.loads(
+                            arguments
+                        )
+                    except Exception:
+                        arguments = {}
 
                 reconstructed.append({
-                    "name": fn.get("name"),
+                    "name": function.get(
+                        "name",
+                        "",
+                    ),
                     "arguments": arguments,
                 })
 
             output.append({
                 "role": "assistant",
-                "content": json.dumps(
-                    {"tool_calls": reconstructed},
-                    ensure_ascii=False,
-                ),
+                "content": _canonical_json({
+                    "tool_calls": reconstructed
+                }),
             })
 
-        else:
-            output.append({
-                "role": role,
-                "content": message.get("content", ""),
-            })
+            continue
+
+        output.append({
+            "role": (
+                role
+                if role in (
+                    "system",
+                    "user",
+                    "assistant",
+                )
+                else "user"
+            ),
+            "content": content_to_text(
+                message.get("content")
+            ),
+        })
 
     return output
 
 # =====================================================
-# AGENT DIRECTIVES
+# AGENT DIRECTIVE
 # =====================================================
 
-def build_agent_directive(tools, tool_choice=None):
+def build_agent_directive(
+    tools: List[Dict[str, Any]],
+    tool_choice: Optional[Any],
+) -> Dict[str, str]:
 
-    specs = []
+    tool_specs = []
 
     for tool in tools:
-        fn = tool.get("function", {})
 
-        specs.append(
-            f"TOOL NAME: {fn.get('name')}\n"
-            f"DESCRIPTION: {fn.get('description', '')}\n"
-            f"JSON SCHEMA:\n"
-            f"{json.dumps(fn.get('parameters', {}), ensure_ascii=False)}"
+        if not isinstance(
+            tool,
+            dict,
+        ):
+            continue
+
+        function = tool.get(
+            "function",
+            {},
+        )
+
+        name = function.get(
+            "name",
+            "unknown_tool",
+        )
+
+        description = function.get(
+            "description",
+            "",
+        )
+
+        parameters = function.get(
+            "parameters",
+            {
+                "type": "object",
+                "properties": {},
+            },
+        )
+
+        tool_specs.append(
+            f"TOOL: {name}\n"
+            f"DESCRIPTION: {description}\n"
+            f"ARGUMENT SCHEMA:\n"
+            f"{json.dumps(parameters, ensure_ascii=False, indent=2)}"
         )
 
     forced = ""
 
     if tool_choice == "required":
+
         forced = (
-            "\nYou MUST call at least one tool now."
+            "\nIMPORTANT: You MUST call "
+            "at least one available tool now."
         )
 
-    elif isinstance(tool_choice, dict):
-        name = (
+    elif isinstance(
+        tool_choice,
+        dict,
+    ):
+
+        forced_name = (
             tool_choice
             .get("function", {})
             .get("name")
         )
 
-        if name:
+        if forced_name:
+
             forced = (
-                f"\nYou MUST call tool '{name}' now."
+                "\nIMPORTANT: You MUST call "
+                f"the tool '{forced_name}' now."
             )
 
     return {
         "role": "system",
         "content": (
-            "You are an execution agent.\n"
-            "You can execute actions through external tools.\n\n"
+            "You are an execution agent with access to external tools.\n"
+            "You are not merely a conversational model.\n\n"
+
+            "When the user request requires an external action, "
+            "use an available tool immediately.\n"
 
-            "When an action requires a tool, output ONLY valid JSON:\n"
+            "When calling tools, output ONLY one valid JSON object "
+            "and no other text before or after it.\n\n"
 
-            '{"tool_calls":[{"name":"tool_name","arguments":{}}]}\n\n'
+            "Required format:\n"
+            '{"tool_calls":[{"name":"tool_name","arguments":{"key":"value"}}]}\n\n'
 
-            "Never describe that you will execute something later.\n"
-            "Never promise to use a tool.\n"
-            "Either call the tool immediately or provide the complete final answer.\n\n"
+            "RULES:\n"
+            "1. Never promise future execution.\n"
+            "2. Never say you will check, create, search, wait, or verify "
+            "without actually calling a tool.\n"
+            "3. Tool names and arguments must exactly match the schemas.\n"
+            "4. Multiple tools may be requested in tool_calls when appropriate.\n"
+            "5. After receiving a tool result, decide immediately whether another "
+            "tool call is required or whether the final answer can be returned.\n"
+            "6. If no tool is needed, return the complete final answer as normal text.\n\n"
 
             "AVAILABLE TOOLS:\n\n"
-            + "\n\n".join(specs)
+            + "\n\n".join(
+                tool_specs
+            )
             + forced
         ),
     }
 
 
 def build_agent_reminder(
-    tools,
-    tool_choice=None,
-    retry_note=None,
-):
+    tools: List[Dict[str, Any]],
+    tool_choice: Optional[Any],
+    retry_note: Optional[str] = None,
+) -> Dict[str, str]:
 
-    names = [
-        t.get("function", {}).get("name")
-        for t in tools
-        if isinstance(t, dict)
-    ]
+    names = []
+
+    for tool in tools:
+
+        if not isinstance(
+            tool,
+            dict,
+        ):
+            continue
+
+        name = (
+            tool
+            .get("function", {})
+            .get("name")
+        )
+
+        if name:
+            names.append(name)
 
     forced = ""
 
     if tool_choice == "required":
-        forced = "\nAt least one tool call is required."
 
-    elif isinstance(tool_choice, dict):
-        name = (
+        forced = (
+            "\nAt least one tool call "
+            "is mandatory in this turn."
+        )
+
+    elif isinstance(
+        tool_choice,
+        dict,
+    ):
+
+        forced_name = (
             tool_choice
             .get("function", {})
             .get("name")
         )
 
-        if name:
+        if forced_name:
+
             forced = (
-                f"\nCall tool '{name}' now."
+                f"\nCall '{forced_name}' now."
             )
 
     retry = ""
 
     if retry_note:
-        retry = f"\nERROR TO FIX: {retry_note}"
+
+        retry = (
+            "\nPREVIOUS OUTPUT ERROR: "
+            f"{retry_note}\n"
+            "Correct the error now."
+        )
 
     return {
         "role": "system",
         "content": (
-            "FINAL AGENT REMINDER:\n"
-
-            f"Available tools: {', '.join(names)}\n"
-
-            "If an action is required, output JSON tool_calls only.\n"
-
-            "If no tool is required, return the complete final answer now.\n"
-
-            "Never promise future execution."
+            "IMMEDIATE AGENT REMINDER:\n"
+            f"Available tools: {', '.join(names)}.\n"
+            "If execution is required, output ONLY "
+            '{"tool_calls":[...]} as valid JSON.\n'
+            "If execution is not required, return the complete final answer now.\n"
+            "Do not promise future action."
             + forced
             + retry
         ),
@@ -861,27 +1946,37 @@ class ChatMessage(BaseModel):
     content: Any = None
     tool_call_id: Optional[str] = None
     name: Optional[str] = None
-    tool_calls: Optional[List[dict]] = None
+    tool_calls: Optional[
+        List[Dict[str, Any]]
+    ] = None
 
 
 class ChatRequest(BaseModel):
     model: str = "claude-sonnet-4-6"
     messages: List[ChatMessage]
+
     stream: bool = False
 
     temperature: Optional[float] = 0.7
     max_tokens: Optional[int] = None
 
-    tools: Optional[List[dict]] = None
+    tools: Optional[
+        List[Dict[str, Any]]
+    ] = None
+
     tool_choice: Optional[Any] = None
 
+    user: Optional[str] = None
+
     conversation_id: Optional[str] = None
 
 # =====================================================
 # AUTH
 # =====================================================
 
-def verify(request: Request):
+def verify(
+    request: Request,
+):
 
     auth = request.headers.get(
         "Authorization",
@@ -892,60 +1987,164 @@ def verify(request: Request):
         auth.startswith("Bearer ")
         and auth[7:] == API_KEY
     ):
-        return
+        return True
 
     if (
-        request.headers.get("X-API-Key")
+        request.headers.get(
+            "X-API-Key",
+            "",
+        )
         == API_KEY
     ):
-        return
+        return True
 
     raise HTTPException(
         status_code=401,
-        detail="Invalid or missing API key",
+        detail=(
+            "Invalid or missing API key"
+        ),
+    )
+
+# =====================================================
+# CONVERSATION HELPERS
+# =====================================================
+
+def get_conversation_id(
+    body: ChatRequest,
+    request: Request,
+) -> str:
+
+    return (
+        body.conversation_id
+        or request.headers.get(
+            "X-Conversation-ID"
+        )
+        or body.user
+        or "default"
+    )
+
+
+def merge_memory_and_incoming(
+    stored: List[Dict[str, Any]],
+    incoming: List[Dict[str, Any]],
+) -> List[Dict[str, Any]]:
+
+    if not stored:
+        return incoming
+
+    if not incoming:
+        return stored
+
+    stored_hashes = {
+        _message_hash({
+            key: value
+            for key, value in message.items()
+            if value is not None
+        })
+        for message in stored
+    }
+
+    merged = list(stored)
+
+    for message in incoming:
+
+        normalized = {
+            key: value
+            for key, value in message.items()
+            if value is not None
+        }
+
+        digest = _message_hash(
+            normalized
+        )
+
+        if digest not in stored_hashes:
+            merged.append(
+                normalized
+            )
+            stored_hashes.add(
+                digest
+            )
+
+    return merged
+
+
+def usage_payload(
+    prompt_text: str,
+    completion_text: str,
+) -> Dict[str, int]:
+
+    prompt_tokens = (
+        len(prompt_text) // 4
+        if prompt_text
+        else 0
+    )
+
+    completion_tokens = (
+        len(completion_text) // 4
+        if completion_text
+        else 0
     )
 
+    return {
+        "prompt_tokens": prompt_tokens,
+        "completion_tokens": completion_tokens,
+        "total_tokens": (
+            prompt_tokens
+            + completion_tokens
+        ),
+    }
+
 # =====================================================
 # APP
 # =====================================================
 
 app = FastAPI(
-    title="G4F Qwen OpenAI Agent Gateway"
+    title="G4F Qwen OpenAI-Compatible Agent Gateway",
+    version="1.0.0",
 )
 
 # =====================================================
 # ROOT
 # =====================================================
 
-@app.get("/")
+@app.api_route(
+    "/",
+    methods=["GET", "HEAD"],
+)
 async def root():
-    return {
+
+    return JSONResponse({
         "status": "running",
         "provider": "Qwen",
         "cookies": COOKIE_STATUS,
         "memory": "SQLite",
-    }
+        "api": "OpenAI Chat Completions",
+    })
 
 # =====================================================
 # MODELS
 # =====================================================
 
 @app.get("/v1/models")
-async def models(request: Request):
+async def list_models(
+    request: Request,
+):
 
     verify(request)
 
-    return {
+    return JSONResponse({
         "object": "list",
         "data": [
             {
-                "id": name,
+                "id": model,
                 "object": "model",
+                "created": 0,
                 "owned_by": "qwen",
             }
-            for name in CLAUDE_MODEL_MAP
+            for model in PUBLIC_MODELS
         ],
-    }
+    })
 
 # =====================================================
 # CHAT COMPLETIONS
@@ -959,70 +2158,55 @@ async def chat_completions(
 
     verify(request)
 
+    if not body.messages:
+
+        raise HTTPException(
+            status_code=400,
+            detail="messages required",
+        )
+
     request_id = (
-        f"chatcmpl-{uuid.uuid4().hex[:24]}"
+        "chatcmpl-"
+        + uuid.uuid4().hex[:24]
+    )
+
+    created = int(
+        time.time()
     )
 
-    created = int(time.time())
+    conversation_id = (
+        get_conversation_id(
+            body,
+            request,
+        )
+    )
 
     incoming_messages = [
-        message.model_dump(exclude_none=True)
+        message.model_dump(
+            exclude_none=True
+        )
         for message in body.messages
     ]
 
-    conversation_id = (
-        body.conversation_id
-        or request.headers.get("X-Conversation-ID")
-        or "default"
+    stored_memory = await load_memory(
+        conversation_id
     )
 
-    stored_memory = load_memory(conversation_id)
-
-    # منع تكرار الرسائل عند إرسال العميل
-    # تاريخ المحادثة كاملاً في كل طلب.
-    if stored_memory and incoming_messages:
-
-        incoming_hashes = {
-            hashlib.sha256(
-                json.dumps(
-                    message,
-                    sort_keys=True,
-                    ensure_ascii=False,
-                ).encode()
-            ).hexdigest()
-            for message in stored_memory
-        }
-
-        new_messages = []
-
-        for message in incoming_messages:
-
-            digest = hashlib.sha256(
-                json.dumps(
-                    message,
-                    sort_keys=True,
-                    ensure_ascii=False,
-                ).encode()
-            ).hexdigest()
-
-            if digest not in incoming_hashes:
-                new_messages.append(message)
-
-        incoming_messages = (
-            stored_memory + new_messages
+    merged_messages = (
+        merge_memory_and_incoming(
+            stored_memory,
+            incoming_messages,
         )
+    )
 
-    elif stored_memory:
-        incoming_messages = stored_memory
-
-    for message in body.messages:
-        save_message(
-            conversation_id,
-            message.model_dump(exclude_none=True),
-        )
+    await save_messages(
+        conversation_id,
+        incoming_messages,
+    )
 
     # =================================================
-    # MODEL MODE — ORIGINAL STREAMING BEHAVIOR
+    # MODEL MODE
+    # No tools -> preserve original streaming behavior.
     # =================================================
 
     if not body.tools:
@@ -1030,59 +2214,104 @@ async def chat_completions(
         last_user_index = None
 
         for index in range(
-            len(incoming_messages) - 1,
+            len(merged_messages) - 1,
             -1,
             -1,
         ):
+
             if (
-                incoming_messages[index].get("role")
+                merged_messages[index]
+                .get("role")
                 == "user"
             ):
                 last_user_index = index
                 break
 
         if last_user_index is None:
+
             raise HTTPException(
                 status_code=400,
-                detail="User message required",
+                detail=(
+                    "At least one user "
+                    "message is required"
+                ),
+            )
+
+        last_user_message = (
+            merged_messages[
+                last_user_index
+            ]
+        )
+
+        last_user_text = (
+            content_to_text(
+                last_user_message.get(
+                    "content"
+                )
             )
+        )
 
-        last_user = str(
-            incoming_messages[last_user_index]
-            .get("content", "")
+        history = (
+            merged_messages[
+                :last_user_index
+            ]
         )
 
-        history = incoming_messages[:last_user_index]
+        # =============================================
+        # MODEL MODE STREAM
+        # =============================================
 
         if body.stream:
 
-            async def model_stream():
+            async def generate_model_stream():
 
                 queue = asyncio.Queue()
-                loop = asyncio.get_running_loop()
+                loop = (
+                    asyncio.get_running_loop()
+                )
 
                 def producer():
+
                     try:
-                        for chunk in ask(
-                            last_user,
+
+                        for text in ask(
+                            last_user_text,
                             history,
                             "Qwen",
                             body.model,
                         ):
+
                             asyncio.run_coroutine_threadsafe(
-                                queue.put(("chunk", chunk)),
+                                queue.put(
+                                    (
+                                        "chunk",
+                                        text,
+                                    )
+                                ),
                                 loop,
                             )
 
                     except Exception as e:
+
                         asyncio.run_coroutine_threadsafe(
-                            queue.put(("error", e)),
+                            queue.put(
+                                (
+                                    "error",
+                                    e,
+                                )
+                            ),
                             loop,
                         )
 
                     finally:
+
                         asyncio.run_coroutine_threadsafe(
-                            queue.put(("done", None)),
+                            queue.put(
+                                (
+                                    "done",
+                                    None,
+                                )
+                            ),
                             loop,
                         )
 
@@ -1091,19 +2320,23 @@ async def chat_completions(
                     producer,
                 )
 
-                full = ""
+                full_text = ""
 
                 while True:
 
-                    kind, value = await queue.get()
+                    event_type, value = (
+                        await queue.get()
+                    )
 
-                    if kind == "chunk":
+                    if event_type == "chunk":
 
-                        full += value
+                        full_text += value
 
-                        payload = {
+                        chunk = {
                             "id": request_id,
-                            "object": "chat.completion.chunk",
+                            "object": (
+                                "chat.completion.chunk"
+                            ),
                             "created": created,
                             "model": body.model,
                             "choices": [{
@@ -1118,39 +2351,52 @@ async def chat_completions(
                         yield (
                             "data: "
                             + json.dumps(
-                                payload,
+                                chunk,
                                 ensure_ascii=False,
                             )
                             + "\n\n"
                         )
 
-                    elif kind == "error":
+                    elif event_type == "error":
+
+                        error_chunk = {
+                            "error": {
+                                "message": str(
+                                    value
+                                ),
+                                "type": (
+                                    "upstream_error"
+                                ),
+                            }
+                        }
 
                         yield (
                             "data: "
-                            + json.dumps({
-                                "error": {
-                                    "message": str(value)
-                                }
-                            })
+                            + json.dumps(
+                                error_chunk,
+                                ensure_ascii=False,
+                            )
                             + "\n\n"
                         )
 
-                    elif kind == "done":
+                    elif event_type == "done":
                         break
 
-                if full:
-                    save_message(
+                if full_text:
+
+                    await save_message(
                         conversation_id,
                         {
                             "role": "assistant",
-                            "content": full,
+                            "content": full_text,
                         },
                     )
 
                 final_chunk = {
                     "id": request_id,
-                    "object": "chat.completion.chunk",
+                    "object": (
+                        "chat.completion.chunk"
+                    ),
                     "created": created,
                     "model": body.model,
                     "choices": [{
@@ -1162,38 +2408,96 @@ async def chat_completions(
 
                 yield (
                     "data: "
-                    + json.dumps(final_chunk)
+                    + json.dumps(
+                        final_chunk,
+                        ensure_ascii=False,
+                    )
                     + "\n\n"
                 )
 
                 yield "data: [DONE]\n\n"
 
             return StreamingResponse(
-                model_stream(),
-                media_type="text/event-stream",
+                generate_model_stream(),
+                media_type=(
+                    "text/event-stream"
+                ),
                 headers={
-                    "Cache-Control": "no-cache",
-                    "Connection": "keep-alive",
-                    "X-Accel-Buffering": "no",
+                    "Cache-Control": (
+                        "no-cache"
+                    ),
+                    "Connection": (
+                        "keep-alive"
+                    ),
+                    "X-Accel-Buffering": (
+                        "no"
+                    ),
                 },
             )
 
-        response_text = await ask_messages_async(
-            incoming_messages,
-            body.model,
-        )
+        # =============================================
+        # MODEL MODE NON-STREAM
+        # =============================================
+
+        try:
+
+            response_text, _ = (
+                await call_qwen_full_messages_async(
+                    [
+                        {
+                            "role": (
+                                message.get(
+                                    "role",
+                                    "user",
+                                )
+                            ),
+                            "content": (
+                                content_to_text(
+                                    message.get(
+                                        "content"
+                                    )
+                                )
+                            ),
+                        }
+                        for message in merged_messages
+                        if message.get("role")
+                        in (
+                            "system",
+                            "user",
+                            "assistant",
+                        )
+                    ],
+                    body.model,
+                )
+            )
+
+        except Exception as e:
+
+            raise HTTPException(
+                status_code=502,
+                detail=(
+                    f"Qwen failed: {e}"
+                ),
+            )
 
         assistant_message = {
             "role": "assistant",
             "content": response_text,
         }
 
-        save_message(
+        await save_message(
             conversation_id,
             assistant_message,
         )
 
-        return {
+        prompt_text = "\n".join(
+            content_to_text(
+                message.get("content")
+            )
+            for message in merged_messages
+        )
+
+        return JSONResponse({
             "id": request_id,
             "object": "chat.completion",
             "created": created,
@@ -1202,62 +2506,81 @@ async def chat_completions(
                 "index": 0,
                 "message": assistant_message,
                 "finish_reason": "stop",
+                "logprobs": None,
             }],
-            "usage": {
-                "prompt_tokens": 0,
-                "completion_tokens": len(response_text) // 4,
-                "total_tokens": len(response_text) // 4,
-            },
-        }
+            "usage": usage_payload(
+                prompt_text,
+                response_text,
+            ),
+        })
 
     # =================================================
     # AGENT MODE
+    # tools present -> full-message agent path.
     # =================================================
 
-    registry = ToolRegistry(body.tools)
-    processor = ToolProcessor(registry)
+    registry = ToolRegistry(
+        body.tools
+    )
+
+    processor = ToolProcessor(
+        registry
+    )
 
-    agent_messages = sanitize_tool_history(
-        incoming_messages
+    sanitized_history = (
+        sanitize_tool_history(
+            merged_messages
+        )
     )
 
     agent_messages = (
-        [build_agent_directive(
-            body.tools,
-            body.tool_choice,
-        )]
-        + agent_messages
-        + [build_agent_reminder(
-            body.tools,
-            body.tool_choice,
-        )]
+        [
+            build_agent_directive(
+                body.tools,
+                body.tool_choice,
+            )
+        ]
+        + sanitized_history
+        + [
+            build_agent_reminder(
+                body.tools,
+                body.tool_choice,
+            )
+        ]
     )
 
-    retries = 0
+    runtime_attempts = 0
 
     while True:
 
         try:
-            response_text = (
-                await ask_messages_async(
+
+            (
+                response_text,
+                native_tool_calls,
+            ) = (
+                await call_qwen_full_messages_async(
                     agent_messages,
                     body.model,
                 )
             )
 
         except Exception as e:
+
             raise HTTPException(
                 status_code=502,
-                detail=f"Qwen failed: {e}",
+                detail=(
+                    f"Qwen failed: {e}"
+                ),
             )
 
         decision = processor.process(
             raw_text=response_text,
-            native_calls=None,
+            native_calls=native_tool_calls,
         )
 
         # =============================================
-        # INVALID TOOL CALL → RETRY
+        # INVALID TOOL CALL -> RETRY
         # =============================================
 
         if (
@@ -1265,46 +2588,59 @@ async def chat_completions(
             == ToolDecisionStatus.RETRY_REQUIRED
         ):
 
-            retries += 1
+            runtime_attempts += 1
+
+            if (
+                runtime_attempts
+                > MAX_TOOL_RETRIES
+            ):
 
-            if retries > MAX_TOOL_RETRIES:
                 raise HTTPException(
                     status_code=502,
                     detail=(
-                        "Model failed to produce "
-                        "a valid tool call"
+                        "Qwen failed to produce "
+                        "a valid tool call after "
+                        "bounded retries."
                     ),
                 )
 
             agent_messages.append({
                 "role": "assistant",
-                "content": response_text,
+                "content": (
+                    response_text
+                    or "[Invalid tool call]"
+                ),
             })
 
             agent_messages.append(
                 build_agent_reminder(
                     body.tools,
                     body.tool_choice,
-                    retry_note=decision.reason,
+                    retry_note=(
+                        decision.reason
+                        or
+                        "Invalid tool call."
+                    ),
                 )
             )
 
             continue
 
         # =============================================
-        # HEDGING → RETRY
+        # HEDGING DETECTION -> RETRY
         # =============================================
 
         if (
             decision.status
             == ToolDecisionStatus.NO_TOOL
+            and runtime_attempts
+            < MAX_TOOL_RETRIES
             and looks_like_unfulfilled_intent(
                 response_text
             )
-            and retries < MAX_TOOL_RETRIES
         ):
 
-            retries += 1
+            runtime_attempts += 1
 
             agent_messages.append({
                 "role": "assistant",
@@ -1316,9 +2652,11 @@ async def chat_completions(
                     body.tools,
                     body.tool_choice,
                     retry_note=(
-                        "Do not promise execution. "
-                        "Call the required tool now "
-                        "or return the final answer."
+                        "You promised or delayed "
+                        "execution without calling "
+                        "a tool. Execute now using "
+                        "tool_calls JSON, or return "
+                        "the complete final answer."
                     ),
                 )
             )
@@ -1327,6 +2665,7 @@ async def chat_completions(
 
         # =============================================
         # VALID TOOL CALLS
+        # Return to OpenAI client for execution.
         # =============================================
 
         if (
@@ -1338,7 +2677,7 @@ async def chat_completions(
             and decision.tool_calls
         ):
 
-            tool_calls = [
+            openai_tool_calls = [
                 {
                     "id": call.id,
                     "type": "function",
@@ -1347,39 +2686,60 @@ async def chat_completions(
                         "arguments": json.dumps(
                             call.arguments,
                             ensure_ascii=False,
+                            separators=(
+                                ",",
+                                ":",
+                            ),
                         ),
                     },
                 }
-                for call in decision.tool_calls
+                for call
+                in decision.tool_calls
             ]
 
             assistant_message = {
                 "role": "assistant",
                 "content": None,
-                "tool_calls": tool_calls,
+                "tool_calls": (
+                    openai_tool_calls
+                ),
             }
 
-            save_message(
+            await save_message(
                 conversation_id,
                 assistant_message,
             )
 
-            return {
+            prompt_text = "\n".join(
+                content_to_text(
+                    message.get(
+                        "content"
+                    )
+                )
+                for message
+                in merged_messages
+            )
+
+            return JSONResponse({
                 "id": request_id,
                 "object": "chat.completion",
                 "created": created,
                 "model": body.model,
                 "choices": [{
                     "index": 0,
-                    "message": assistant_message,
-                    "finish_reason": "tool_calls",
+                    "message": (
+                        assistant_message
+                    ),
+                    "finish_reason": (
+                        "tool_calls"
+                    ),
+                    "logprobs": None,
                 }],
-                "usage": {
-                    "prompt_tokens": 0,
-                    "completion_tokens": 0,
-                    "total_tokens": 0,
-                },
-            }
+                "usage": usage_payload(
+                    prompt_text,
+                    response_text,
+                ),
+            })
 
         # =============================================
         # FINAL ANSWER
@@ -1390,12 +2750,19 @@ async def chat_completions(
             "content": response_text,
         }
 
-        save_message(
+        await save_message(
             conversation_id,
             assistant_message,
         )
 
-        return {
+        prompt_text = "\n".join(
+            content_to_text(
+                message.get("content")
+            )
+            for message in merged_messages
+        )
+
+        return JSONResponse({
             "id": request_id,
             "object": "chat.completion",
             "created": created,
@@ -1404,18 +2771,13 @@ async def chat_completions(
                 "index": 0,
                 "message": assistant_message,
                 "finish_reason": "stop",
+                "logprobs": None,
             }],
-            "usage": {
-                "prompt_tokens": 0,
-                "completion_tokens": (
-                    len(response_text) // 4
-                ),
-                "total_tokens": (
-                    len(response_text) // 4
-                ),
-            },
-        }
-
+            "usage": usage_payload(
+                prompt_text,
+                response_text,
+            ),
+        })
 
 # =====================================================
 # RUN
@@ -1436,4 +2798,8 @@ if __name__ == "__main__":
         app,
         host="0.0.0.0",
         port=port,
+        log_level=os.getenv(
+            "LOG_LEVEL",
+            "INFO",
+        ).lower(),
     )