# AGENTS.md

## Purpose

This document outlines general practices and expectations for AI agents assisting with the development of `ngxstat`, a hybrid log analytics tool for Nginx. The agent’s role includes writing code, testing functionality, and generating documentation, with particular attention to the following technologies and design choices.

## Project Overview

**Project Name**: `ngxstat`
**Goal**: Per-domain log analysis for Nginx with a hybrid of statically generated reports and lightweight live JSON API endpoints.

---

## Stack & Tooling

### Python
- Version: 3.10+ recommended
- Project isolation: Use `venv`
  ```bash
  python -m venv .venv
  source .venv/bin/activate
  pip install -r requirements.txt
  ```
  The `run-import.sh` script can initialize this environment automatically.
  Always activate the virtual environment before running scripts or tests.

* Before committing code run `black` for consistent formatting and execute
  the test suite with `pytest`. All tests should pass.

* Dependency management: Use `requirements.txt` or `pip-tools`
* Use standard libraries where feasible (e.g., `sqlite3`, `argparse`, `datetime`)
* Adopt `typer` for CLI command interface (if CLI ergonomics matter)

### SQLite

* Used for log ingestion and aggregation
* Prefer raw SQL or use lightweight ORM (e.g., `dataset`, `sqlite-utils`) only if necessary
* Index columns used in groupings (e.g., timestamp, domain, status, cache result)

### Charting: Chart.js

* Use latest CDN version for embedded dashboards
* Charts should be rendered from pre-generated JSON blobs in `/json/`

### Tables: DataTables

* Use DataTables via CDN for reports with `chart: table`
* Requires jQuery from a CDN
* Table data comes from the same `/json/` files as charts

### Styling: Bulma CSS

* Use via CDN or vendored minified copy (to keep reports fully static)
* Stick to default components (columns, cards, buttons, etc.)
* No JS dependencies from Bulma

### Icon Set: [Free CC0 Icons (CC0)](https://cc0-icons.jonh.eu/)

* License: MIT / CC0-like
* Use SVG versions
* Download as:

  * Individual SVGs in `/static/icons/`, or
  * Pre-bundled sprite/minified set if needed

---

## 📄 File Structure Guidelines

```plaintext
ngxstat/
├── scripts/            # Log importers, SQLite tools
├── templates/          # Jinja2 templates for static page generation
├── static/             # CSS, JS, icons (Chart.js, Bulma, icons)
├── output/             # Generated reports
├── database/           # SQLite DBs and schema migrations
├── api/                # Lightweight live API server (Flask/FastAPI)
├── AGENTS.md           # This file
├── README.md
```

---

## Agentic Behavior Expectations

* **Code must be modular and documented.**
* **Use consistent naming and formatting.**
* **Err on the side of clarity over cleverness.**
* **Avoid introducing unnecessary dependencies.**
* **Validate SQL statements when modifying schema.**
* **Verify that logs parse cleanly and reject malformed lines.**

If uncertain, the agent should prompt the human for clarification before making architectural assumptions.

## Testing

Use `pytest` for automated tests. Run the suite from an activated virtual environment and ensure all tests pass before committing:

```bash
pytest -q
```

---

## Future Capabilities

As the project matures, agents may also:

* Suggest aggregation logic (e.g., bot detection, per-path stats)
* Help build a Dockerized deployable version
* Expand dashboard with new view types or filters
* Integrate log format autodetection heuristics

---

## Changelog

* **2025-07-17**: Initial version by Jordan + ChatGPT
* **2025-07-17**: Expanded virtual environment usage guidance