oskaragent 0.1.38a0__py3-none-any.whl

oskaragent/helpers.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, reveal_type
+import secrets
+import string
+from datetime import datetime
+from typing import Optional, Callable
+from colorama import Fore, Style, init as colorama_init
+from dataclasses import dataclass, field
+
+
+# Initialize colorama once
+colorama_init(autoreset=True)
+
+
+_COLOR_MAP = {
+    "BLUE": Fore.BLUE,
+    "MAGENTA": Fore.MAGENTA,
+    "GREEN": Fore.GREEN,
+    "YELLOW": Fore.YELLOW,
+    "RED": Fore.RED,
+    "CYAN": Fore.CYAN,
+    "WHITE": Fore.WHITE,
+    "RESET": Style.RESET_ALL,
+}
+
+# Types
+ToolFn = Callable[..., Any]
+
+
+def log_msg(message: str, *, func: str = "", action: str = "", color: str = "MAGENTA") -> None:
+    """Log a colorized message with contextual metadata.
+
+    Args:
+        message (str): Texto principal que será impresso no log.
+        func (str, optional): Nome da função que originou o log. Defaults to "".
+        action (str, optional): Identificador adicional para a ação relacionada. Defaults to "".
+        color (str, optional): Código de cor aceito por `colorama` para o texto. Defaults to "MAGENTA".
+
+    Returns:
+        None: Esta função não retorna valor; apenas escreve na saída padrão.
+    """
+    try:
+        ts = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        col = _COLOR_MAP.get(color.upper(), Fore.BLUE)
+        reset = Style.RESET_ALL
+        func_part = f" [func={func}]" if func else ""
+        action_part = f" [action={action}]" if action else ""
+        print(f"{col}[{ts}]{func_part}{action_part} {message}{reset}")
+
+    except Exception:
+        # Fallback to plain print if anything goes wrong
+        ts = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        print(f"[{ts}] {message}")
+
+
+def gen_randon_filename(name_length: int = 10, prefix: str = "") -> str:
+    """Generate a random filename composed of ASCII letters and digits.
+
+    Args:
+        name_length (int, optional): Quantidade de caracteres aleatórios desejada. Defaults to 10.
+        prefix (str, optional): Texto opcional a ser prefixado ao nome gerado. Defaults to "".
+
+    Returns:
+        str: Nome de arquivo construído a partir do prefixo (quando fornecido) seguido dos caracteres randômicos.
+    """
+    chars = string.ascii_letters + string.digits
+    base_name = ''.join(secrets.choice(chars) for _ in range(name_length))
+    return prefix + base_name
+
+
+@dataclass
+class ToolContext:
+    session_id: str
+    message_id: str
+    agent_id: str
+    is_verbose: bool = False
+    input_data: dict[str, Any] = field(default_factory=dict)
+    subordinate_agents: list[Any] = field(default_factory=list)
+    mcp_tools_schema: list[dict] = field(default_factory=dict)
+    external_tools_schema: list[dict] = field(default_factory=dict)
+    retrievers: list[Any] = field(default_factory=list)
+    working_folder: Optional[str] = None
+    knowledge_base: Optional[list[dict[str, Any]]] = None
+
+
+def vlog(ctx: "ToolContext | None", message: str, *, func: str = "") -> None:
+    """Print verbose diagnostic logs when the tool context requires it.
+
+    Args:
+        ctx (ToolContext | None): Contexto da execução da ferramenta, contendo flag `is_verbose`.
+        message (str): Texto que será emitido no log.
+        func (str, optional): Nome da função geradora da mensagem. Defaults to "".
+
+    Returns:
+        None: Apenas encaminha mensagens para `log_msg` quando habilitado.
+    """
+    if ctx and getattr(ctx, "is_verbose", False):
+        log_msg(message, func=func or "tool", action="tool", color="MAGENTA")
+
+
+def render_file_as_content_blocks(file_path: str) -> list[dict[str, Any]]:
+    """Converte um arquivo em blocos compatíveis com a Responses API.
+
+    Args:
+        file_path (str): Caminho absoluto ou relativo para o arquivo de entrada.
+
+    Returns:
+        list[dict[str, Any]]: Coleção de blocos estruturados (`input_text` ou `input_image`).
+
+    Raises:
+        ValueError: Quando o arquivo não pode ser lido, excede limites ou possui tipo não suportado.
+    """
+    # Extract filename from path
+    filename = os.path.basename(file_path)
+
+    # 1. Carregar o JSON como texto puro
+    with open(file_path, "r", encoding="utf-8") as f:
+        text = f.read()
+
+    # 2. Definir tamanho dos pedaços (chunks)
+    CHUNK_SIZE = 50_000
+
+    chunks = [
+        text[i:i + CHUNK_SIZE]
+        for i in range(0, len(text), CHUNK_SIZE)
+    ]
+
+    # 3. Construir as mensagens a serem enviadas
+    messages = [
+        {
+            "type": "input_text",
+            "text": (
+                f"Vou enviar o conteúdo de do arquivo '{filename}' em múltiplas partes. "
+                "Não responda ainda. Apenas armazene cada parte. "
+                "Quando eu enviar a mensagem FINAL, você terá o arquivo inteiro."
+            )
+        }
+    ]
+
+    # Inserir cada pedaço como mensagem separada
+    for i, chunk in enumerate(chunks):
+        messages.append(
+            {
+                "type": "input_text",
+                "text": f"[PARTE {i + 1}/{len(chunks)}]\n{chunk}"
+            }
+        )
+    # Mensagem final instruindo o modelo a analisar os dados
+    messages.append({
+        "type": "input_text",
+        "text": (
+            f"FINAL. Agora que você recebeu todas as partes do arquivo {filename}, "
+            "analise o conteúdo completo e produza a resposta solicitada."
+        )
+    })
+
+    return messages
+
+
+def get_working_folder_path(base_folder: Path, session_id: str) -> Path:
+    # cria o nome da pasta de trabalho se uma sessão
+    if base_folder.resolve().as_posix().endswith(session_id):
+        # o base_folder já é a pasta de trabalho
+        return base_folder
+    return Path(base_folder if base_folder else Path("_oskar_working_folder")) / "oskar_sessions"/ session_id
+
+
+def create_working_folder(base_folder: Path | None, session_id: str) -> str:
+    # cria uma pasta de trabalho para manter os arquivos temporários, se a pasta não existir
+    session_dir = get_working_folder_path(base_folder, session_id)
+    session_dir.mkdir(parents=True, exist_ok=True)
+    return session_dir.resolve().as_posix()

oskaragent-0.1.38a0.dist-info/METADATA

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: oskaragent
+Version: 0.1.38a0
+Summary: Plataforma de agente conversacional Oskar.
+Author: José Carlos Cordeiro
+License-Expression: MIT
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: openai==2.9.0
+Requires-Dist: mcp==1.25.0
+Requires-Dist: faiss-cpu==1.13.1
+Requires-Dist: numpy==2.3.5
+Requires-Dist: pandas==2.3.3
+Requires-Dist: pyodbc==5.3.0
+Requires-Dist: pyyaml==6.0.3
+Requires-Dist: pypdf==6.4.1
+Requires-Dist: pdfkit==1.0.0
+Requires-Dist: pdfminer.six==20251107
+Requires-Dist: python-docx==1.2.0
+Requires-Dist: python-pptx==1.0.2
+Requires-Dist: pillow==12.0.0
+Requires-Dist: lxml==6.0.2
+Requires-Dist: markdown2==2.5.4
+Requires-Dist: beautifulsoup4==4.14.3
+Requires-Dist: matplotlib==3.10.8
+Requires-Dist: seaborn==0.13.2
+Requires-Dist: tabulate==0.9.0
+Requires-Dist: colorama==0.4.6
+Dynamic: license-file

oskaragent-0.1.38a0.dist-info/RECORD

@@ -0,0 +1,30 @@
+oskaragent/__init__.py,sha256=R1R-z9EYLQBy_wRaa79kO_jRTTCidqpLqMKsUIwq6l0,1121
+oskaragent/agent.py,sha256=B7KwPxGiNw40A0TpUPFHftU2hwqLC0w8sY6_dclAYX4,85449
+oskaragent/agent_config.py,sha256=CYDSsJFfdrFTU-9UeonZhjzBocOXbUu5IjhM6jYxhl8,10320
+oskaragent/agent_mcp_tools.py,sha256=LGRiecH-gBMsS2I1L7aGrZiWwc2R8gp8lN3aJpWlveY,4338
+oskaragent/agent_tools.py,sha256=TowXGkclirnZq9u6_-QOq6jzbJYS3Uv3xU5YqgyExOU,39020
+oskaragent/helpers.py,sha256=J53QnC9-y4PiEBoFsfpWWeL1zouWLlqfEMmZE8KyTsM,6113
+oskaragent-0.1.38a0.dist-info/licenses/LICENSE,sha256=cdONOmAtqpa6SxVG7sCcw-2czBq0iuD9Exn7YQLP6Ek,1075
+tests/1a_test_basico.py,sha256=kuaHOJk5nGkSuuXwvGPzIPtvJREyEIkU2WX-8OyHKRI,1255
+tests/1b_test_history.py,sha256=4NDvs1hCCgi2U5GrAhiPE0EO2MVzY5qbZPdS11DZ0zM,2318
+tests/1c_test_basico.py,sha256=ZcpzUI1b8cz7m0dYT6SqpGWjY_-KpT7mtCHfYIAw8kQ,2073
+tests/2a_test_tool_python.py,sha256=9cHp8oxHEbBfPdp_F4JxBu2zBOfEeSn07YHuKLkoCrA,1671
+tests/2b_test_tool_calculator.py,sha256=Nau_tW4XIpXp-QE74tVhK2n8Bbh26c_wHinigu8wS3A,1771
+tests/2c_test_tool_savefile.py,sha256=CahDZwKafXCGetY73eW5WKhpGP12D9EmiCkHKa6zWuU,1560
+tests/3a_test_upload_md.py,sha256=ReHXFQMdSzEftqvCFUZZLFauqQBMcREVPwrgGhrA7I4,1259
+tests/3b_test_upload_img.py,sha256=3uvZIDAwhvtu_FFeVL0QRQg_6xbzH9fEA_IWwD1cZfI,1184
+tests/3c_test_upload_pdf_compare.py,sha256=-AUdOo1otw0gHZJjm18qywk9AiTjrfDR5hVFFLKTbm4,1350
+tests/4_test_RAG.py,sha256=hSj_oMK5hKCnqcVXZK4BBZH6eif7_bkPPwxklJQdF_M,1884
+tests/5_test_MAS.py,sha256=1VuZKroJR032wAbPIxGLvTh6nz2YmCv0wKX-3hrKXrU,2127
+tests/6a_test_MCP_tool_CRM.py,sha256=mZOSe6FWmOFnIk9LdJCxFDWVMnCfmuudsBV0bEtzi-c,3908
+tests/6b_test_MCP_tool_ITSM.py,sha256=BOeA3ALeehHm_EdJtalZoauDmmOIeQl2aFauD_5ZuM4,2826
+tests/6c_test_MCP_tool_SQL.py,sha256=VPi2E91DKF6jp2uGGdVH_6eDY_Et5cV9eU40p_Btlso,2531
+tests/6d_test_MCP_tool_DOC_SQL.py,sha256=Ft9e1jwWlcwcpl3mXd6u_o-adj7fFP6Hc8JqU1R-pwA,1336
+tests/7a_test_BI_CSV.py,sha256=RN4ksfgItBHrn8Ve_Eyo7ecbm4NgOMulCrLcVMv2fXA,1087
+tests/7b_test_BI_SQL.py,sha256=AyCWfTQ_1EYB7lPg8CKULTxaOdUG273yKuyqgR9UiM4,2268
+tests/8a_test_external_tool.py,sha256=Mkmm5yx3ByVpwyq5o1LFOHtUfQf6DeED3Bn-4sxgFfA,8507
+tests/helpers.py,sha256=6MsTer0ANW3Dwir5_-meb1ctpJ_MeM4t6mNLW2K0Xbg,1374
+oskaragent-0.1.38a0.dist-info/METADATA,sha256=1G6-_3gYh4Yp6m6i7PCo-WuOdtfLUWXWLuyz88IojPQ,881
+oskaragent-0.1.38a0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+oskaragent-0.1.38a0.dist-info/top_level.txt,sha256=P6Ksple4IyvbBAIrSJ71dP2j_jRntW4z8XLmou9TEfE,17
+oskaragent-0.1.38a0.dist-info/RECORD,,

oskaragent-0.1.38a0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

oskaragent-0.1.38a0.dist-info/licenses/LICENSE

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

oskaragent-0.1.38a0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+oskaragent
+tests

tests/1a_test_basico.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from typing import Any
+import json
+
+from oskaragent.agent import Oskar
+from oskaragent.agent_config import AgentConfig
+from tests.helpers import set_key
+
+
+def _response_log(assistant_message_struct: dict[str, Any]):
+    usage = assistant_message_struct.get("usage", {}) or {}
+    print(
+            f"[callback] message_id={assistant_message_struct.get('message_id')} "
+            f"tokens={{'input_tokens': {usage.get('input_tokens')}, 'output_tokens': {usage.get('output_tokens')}, 'total_tokens': {usage.get('total_tokens')}}}"
+    )
+
+
+def main() -> int:
+    # Set OpenAI API key
+    set_key()
+
+    ag_cfg = AgentConfig(
+            model="gpt-5",
+            model_settings={
+                "history_window_size": 5,  # parametrizável
+            },
+    )
+
+    agent = Oskar(agent_config=ag_cfg, response_callback=_response_log, is_verbose=True)
+
+    # No explicit question provided: run a quick test prompt and exit
+    test_q = "Quem é o presidente do Brasil?"
+    res = agent.answer(test_q)
+
+    print(test_q)
+    # Ensure UTF-8 characters are printed properly (no ASCII escapes)
+    print(json.dumps(res, indent=2, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tests/1b_test_history.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from tests.helpers import set_key
+from oskaragent.agent import Oskar
+from oskaragent.agent_config import AgentConfig
+
+
+def _response_log(assistant_message_struct: dict[str, Any]):
+    usage = assistant_message_struct.get("usage", {}) or {}
+    print(
+        f"[callback] message_id={assistant_message_struct.get('message_id')} "
+        f"tokens={{'input_tokens': {usage.get('input_tokens')}, 'output_tokens': {usage.get('output_tokens')}, 'total_tokens': {usage.get('total_tokens')}}}"
+    )
+
+
+def main() -> int:
+    # Set OpenAI API key
+    set_key()
+
+    # Build initial agent configuration
+    ag_cfg = AgentConfig(
+        model_settings={"history_window_size": 5},
+        system_prompt=(
+            "Você é um assistente prestativo chamado oskaragent. Mantenha e use o histórico para responder coerentemente."
+        ),
+    )
+
+    # Create the agent and send the first prompt
+    agent = Oskar(agent_config=ag_cfg, response_callback=_response_log, is_verbose=True)
+    q1 = "Minha cor preferida é azul. Qual é sua cor preferida?"
+    print(f"\n[teste] Enviando primeira pergunta: {q1}")
+    r1 = agent.answer(q1)
+    print("[teste] Resposta 1:")
+    print(r1['content'])
+
+    # Export agent to JSON
+    j = agent.to_json()
+
+    # Destroy the agent (drop the reference)
+    del agent
+
+    # Recreate a new agent importing the exported JSON
+    print("[teste] Recriando agente a partir do JSON exportado…")
+    agent2 = Oskar.from_json(j, working_folder="./output")
+
+    # Send the second prompt which relies on remembered history
+    q2 = "Qual é minha cor preferida?"
+    print(f"\n[teste] Enviando segunda pergunta: {q2}")
+    r2 = agent2.answer(q2)
+    print("[teste] Resposta 2:")
+    print(r2['content'])
+
+    # Simple check: expect the model/agent to answer "azul"
+    content = (r2 or {}).get("content", "")
+    ok = isinstance(content, str) and ("azul" in content.lower())
+    status = "OK" if ok else "ATENÇÃO"
+    print(f"\n[verificação] Esperado conter 'azul' → {status}")
+
+    print('-' * 40)
+    print(json.dumps(j, indent=2, ensure_ascii=False))
+
+    print('-' * 40)
+    print(json.dumps(agent2.to_json(), indent=2, ensure_ascii=False))
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tests/1c_test_basico.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from textwrap import dedent
+from typing import Any
+
+from oskaragent.agent import Oskar
+from oskaragent.agent_config import AgentConfig
+from tests.helpers import set_key
+
+
+def _response_log(assistant_message_struct: dict[str, Any]):
+    usage = assistant_message_struct.get("usage", {}) or {}
+    print(
+            f"[callback] message_id={assistant_message_struct.get('message_id')} "
+            f"tokens={{'input_tokens': {usage.get('input_tokens')}, 'output_tokens': {usage.get('output_tokens')}, 'total_tokens': {usage.get('total_tokens')}}}"
+    )
+
+
+def main() -> int:
+    # Set OpenAI API key
+    set_key()
+
+    ag_cfg = AgentConfig(
+        model="gpt-5",
+        model_settings={
+            "history_window_size": 5,  # parametrizável
+        }
+    )
+
+    agent = Oskar(agent_config=ag_cfg, response_callback=_response_log, is_verbose=True)
+
+    # No explicit question provided: run a quick test prompt and exit
+    test_q = dedent("""
+        Estou desenvolvendo um programa CLI em Python para conversar com agentes de IA.
+        
+        Quero que você:
+        
+        1. Defina uma arquitetura de alto nível para o programa.
+        2. Proponha a estrutura de diretórios e arquivos.
+        3. Explique o fluxo de execução principal.
+        4. Indique como persistir histórico de conversas por agente.
+        5. Liste riscos técnicos e como mitigá-los.
+        
+        Restrições:
+        - O programa deve funcionar no Windows.
+        - Deve ser compatível com Python 3.12+.
+        - O design deve permitir adicionar novos agentes sem alterar o núcleo.
+        - A resposta deve ser estruturada em seções claras.
+        
+        Não escreva código agora. Foque apenas em arquitetura e decisões técnicas.
+        """)
+    res = agent.answer(test_q)
+
+    print(test_q)
+    # Ensure UTF-8 characters are printed properly (no ASCII escapes)
+    print(res['content'])
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tests/2a_test_tool_python.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from tests.helpers import set_key
+from oskaragent.agent import Oskar
+from oskaragent.agent_config import AgentConfig
+
+
+def _response_log(assistant_message_struct: dict[str, Any]):
+    usage = assistant_message_struct.get("usage", {}) or {}
+    print(
+        f"[callback] message_id={assistant_message_struct.get('message_id')} "
+        f"tokens={{'input_tokens': {usage.get('input_tokens')}, 'output_tokens': {usage.get('output_tokens')}, 'total_tokens': {usage.get('total_tokens')}}}"
+    )
+
+
+def main() -> int:
+    # Set OpenAI API key
+    set_key()
+
+    # Allow tools we might want the model to call; not strictly required for this test
+    ag_cfg = AgentConfig(
+        tools_names=[
+            "execute_python_code_tool",
+        ],
+        system_prompt=(
+            "Você é um assistente com capacidade para executar código python usando a ferramenta 'execute_python_code_tool'."
+        ),
+    )
+
+    agent = Oskar(agent_config=ag_cfg, response_callback=_response_log, is_verbose=True)
+
+    question = (
+        "Crie um bloco de código Python para gerar um gráfico de barras simples usando matplotlib com três categorias (A, B, C) e valores, "
+        "adicionar rótulos de eixos e título, e chamar plt.show() no final. "
+        "Execute o código gerado usando a ferramenta execute_python_code_tool e retorne apenas o resultado final."
+    )
+
+    res = agent.answer(question)
+
+    # Ensure UTF-8 characters are printed properly (no ASCII escapes)
+    print(json.dumps(res, indent=2, ensure_ascii=False))
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tests/2b_test_tool_calculator.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from tests.helpers import set_key
+from oskaragent.agent import Oskar
+from oskaragent.agent_config import AgentConfig
+
+
+def _response_log(assistant_message_struct: dict[str, Any]):
+    usage = assistant_message_struct.get("usage", {}) or {}
+    print(
+        f"[callback] message_id={assistant_message_struct.get('message_id')} "
+        f"tokens={{'input_tokens': {usage.get('input_tokens')}, 'output_tokens': {usage.get('output_tokens')}, 'total_tokens': {usage.get('total_tokens')}}}"
+    )
+
+
+def main() -> int:
+    # Set OpenAI API key
+    set_key()
+
+    # Allow the calculator tool explicitly (defaults are included, but we state intent)
+    ag_cfg = AgentConfig(
+        tools_names=[
+            "calculator_tool",
+        ],
+        system_prompt=(
+            "Você é um assistente focado em cálculos. Sempre que houver uma expressão matemática, "
+            "use a ferramenta 'calculator_tool' para avaliar e retorne apenas o número final."
+        ),
+    )
+
+    agent = Oskar(agent_config=ag_cfg, response_callback=_response_log, is_verbose=True)
+
+    # Expression chosen to exercise math functions available to the tool
+    # expression = "2**10 + sqrt(144) + sin(pi/2)"  # 1024 + 12 + 1 = 1037.0
+    expression = "1024 + 12 + 1"  # 1024 + 12 + 1 = 1037.0
+    question = (
+        "Calcule a expressão a seguir usando a ferramenta calculator_tool e retorne apenas o número final: "
+        f"{expression}"
+    )
+
+    res = agent.answer(question, action='tool:calculator_tool')
+
+    # Ensure UTF-8 characters are printed properly (no ASCII escapes)
+    print(json.dumps(res, indent=2, ensure_ascii=False))
+
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tests/2c_test_tool_savefile.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from tests.helpers import set_key
+from oskaragent.agent import Oskar
+from oskaragent.agent_config import AgentConfig
+
+
+def _response_log(assistant_message_struct: dict[str, Any]):
+    usage = assistant_message_struct.get("usage", {}) or {}
+    print(
+        f"[callback] message_id={assistant_message_struct.get('message_id')} "
+        f"tokens={{'input_tokens': {usage.get('input_tokens')}, 'output_tokens': {usage.get('output_tokens')}, 'total_tokens': {usage.get('total_tokens')}}}"
+    )
+
+
+def main() -> None:
+    # Set OpenAI API key
+    set_key()
+
+    # Habilita explicitamente a ferramenta de escrita em arquivo
+    ag_cfg = AgentConfig(
+        tools_names=[
+            "write_file_tool",
+        ],
+        system_prompt=(
+            "Você é um agente chamado oskaragent. Quando solicitado a salvar conteúdo, "
+            "use a ferramenta 'write_file_tool'."
+        ),
+    )
+
+    agent = Oskar(agent_config=ag_cfg, response_callback=_response_log, is_verbose=True)
+
+    # 1) Expressão regular para telefone internacional
+    q1 = "Gere um diagrama plantuml de uma expressão regular para telefone internacional."
+    agent.answer(q1)
+    print("[q1] enviado")
+
+    # 3) Solicitar que o agente salve o diagrama em arquivo (sem ação explícita)
+    q3 = "Salve o diagrama plantuml num arquivo."
+    r3 = agent.answer(q3)
+
+    # Imprime o JSON completo da última resposta
+    print(json.dumps(r3, indent=2, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()

tests/3a_test_upload_md.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from oskaragent.agent import Oskar
+from oskaragent.agent_config import AgentConfig
+from tests.helpers import set_key
+
+
+def main() -> None:
+    # Set OpenAI API key
+    set_key()
+
+    # Caminho do arquivo Markdown a ser resumido
+    md_path = Path("sources/cristianismo.md").resolve()
+    if not md_path.exists():
+        raise FileNotFoundError(f"Arquivo não encontrado: {md_path}")
+
+    # Instancia o agente oskaragent (com configurações padrão)
+    agent_cfg = AgentConfig(
+        model_settings={
+            "history_window_size": 5,  # parametrizável
+        },
+    )
+    agent = Oskar(agent_config=agent_cfg, is_verbose=True)
+
+    # Pergunta ao agente para fazer um resumo do arquivo
+    question = (
+        "Por favor, leia o arquivo anexo e produza um resumo objetivo em português, "
+        "destacando as ideias principais em 5–7 linhas."
+    )
+    result: dict[str, Any] = agent.answer(
+        question=question,
+        attached_files=str(md_path)
+    )
+
+    # Extrai e imprime o conteúdo da resposta (resumo)
+    content = (result or {}).get("content") or ""
+    print("Resumo gerado:\n")
+    print(content)
+
+
+if __name__ == "__main__":
+    main()
+