applications AGENTS.md

Agent.md — Python + uv

Purpose

• This repository uses Python managed by uv for dependency resolution, virtual environments, locking, and execution. Always prefer uv subcommands (add/remove/run/sync/export) over raw pip/venv commands.

Core rules

• Use uv add to add or upgrade dependencies so that both pyproject.toml and uv.lock stay in sync; do not use pip install directly.
• Keep runtime dependencies in [project.dependencies] and development-only tools in the dev group via uv add --dev ....
• Use uv run to execute Python, test, and tooling commands without manually activating a virtual environment.

Project bootstrap

• New project (scaffold files): uv init
• First install or clean install: uv sync
• Run the app: uv run python -m <your_module> or uv run main.py
• REPL: uv run python
• Scripts in pyproject: prefer uv run <command> to ensure the correct environment is used

Managing dependencies

• Add runtime dependency: uv add <name> (e.g., uv add httpx)
• Add dev dependencies: uv add --dev pytest ruff
• Pin/upgrade by constraint: uv add "httpx>=0.27" or adjust pyproject.toml and then uv sync
• Remove dependency: uv remove <name>
• Export lock for external tooling: uv export --format requirements-txt --output-file requirements.txt

Locking and environments

• uv run and uv sync will ensure the environment matches pyproject.toml and uv.lock
• Avoid manual pip install or manual venv activation; let uv manage the environment
• Commit uv.lock to version control for reproducible installs

pyproject guidance

• Dependencies live under [project] → dependencies = [...]
• Development-only tooling should go under a dev group (e.g., uv add --dev ruff pytest) for clean separation
• Keep requires-python current (e.g., >=3.12) to match the team’s baseline

Usage in this repo

• When adding libraries or changing versions, propose uv add ... changes that update both pyproject.toml and uv.lock, then run uv run pytest -q to validate
• Prefer minimal diffs, explain the plan, apply changes, and run tests/tooling via uv run
• If build/test fails, inspect error context, adjust constraints or code, and re-run via uv run

Common commands (copy/paste)

• Initialize: uv init | Install deps: uv sync
• Add runtime: uv add <pkg> | Add dev: uv add --dev <pkg>
• Remove: uv remove <pkg>
• Run app: uv run python -m <your_module> or uv run main.py
• Tests: uv run pytest -q
• Lint/format: uv run ruff check . and/or uv run ruff format .
• Export: uv export --format requirements-txt --output-file requirements.txt

Of course. Based on your request and the example app.py you provided, here is a new section that you can append to your gemini.md file. This section provides clear guidance on how to write effective tool names and descriptions, using the Perplexity chat function as a concrete example.

The proposed changes will make the function's purpose much clearer, especially its ability to access and cite real-time web information, which is a key feature.

---