# 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.