AGENTS.md

Repository Guidelines

Project Structure & Modules

• Root app: app.py (agent wiring, Langfuse tracing, Gradio launch).
• UI: Gradio_UI.py (streaming chat, message formatting).
• Tools: tools/ (final_answer.py, web_search.py, visit_webpage.py). Add new tools here.
• Prompts & config: prompts.yaml, agent.json.
• Dependencies: requirements.txt; example script: test.py.

Build, Test, and Run

• Create env and install deps:
  • python -m venv .venv && source .venv/bin/activate
  • pip install -r requirements.txt
• Required env vars:
  • OPENAI_API_KEY (required), optional: LLM_MODEL_ID, LLM_API_BASE, LLM_MAX_TOKENS, LLM_TEMPERATURE, LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY.
• Run locally (starts Gradio UI):
  • python app.py
• Quick smoke test:
  • python test.py

Coding Style & Conventions

• Python 3.11, PEP 8, 4‑space indentation, limit lines to ~100 chars.
• Naming: modules and functions snake_case; classes CamelCase; constants UPPER_SNAKE_CASE.
• Tools: subclass smolagents.tools.Tool, define name, description, inputs, output_type, and implement forward(self, ...).
  • Example file path: tools/my_tool.py; import and register in app.py.
• Prefer type hints and concise docstrings. Keep external calls isolated for easy mocking.

Testing Guidelines

• Current repo includes test.py for a basic check. Prefer pytest for new tests.
• Place tests in tests/ as test_*.py; name fixtures clearly.
• Mock network and external APIs (OpenAI, DuckDuckGo, Langfuse, Jaqpot).
• Aim for coverage on tool forward() logic and critical agent wiring.

Commit & Pull Requests

• Commits: imperative mood and scoped, e.g., feat(tool): add qsar parser.
• PRs must include:
  • Clear description, rationale, and linked issues.
  • Steps to run/test, environment variables touched.
  • Screenshots/GIFs for UI changes (Gradio).
  • Updates to requirements.txt and docs when deps or behavior change.

Security & Configuration

• Never commit secrets; use environment variables. Validate required keys at startup.
• Prefer qsartoolbox-based predictions over web search for accuracy (see prompts).
• Networked tools must handle timeouts and errors; return user‑friendly messages.