[API] Add /llms.txt endpoint for AI agent orientation

Serve a plain-text orientation document at GET /llms.txt following the
llms.txt convention (analogous to robots.txt). Helps AI agents quickly
understand LNT's domain concepts, API structure, and common workflows.

Content includes: what LNT is, key concepts (test suite, machine, order,
run, test, sample, regression, field change), endpoint listing, pagination
format, links to Swagger UI and OpenAPI spec, and common workflows.

- Registered as a plain Flask blueprint (not flask-smorest) to stay out
  of the OpenAPI spec
- Static content with Cache-Control (24h) and ETag headers
- Points to OpenAPI spec for full write endpoint documentation

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

Author: ldionne

docs/design/v5-api.md

@@ -180,3 +180,14 @@ R9: Not in Scope (Deferred)
 - Run comparison / derived analytics endpoints
 - Report endpoints (daily, summary, latest runs)
 - Machine merge
+
+R10: AI Agent Orientation
+
+- Serve a plain-text orientation document at GET /llms.txt (following the
+  llms.txt convention, analogous to robots.txt)
+- Content: what LNT is, key domain concepts, API structure, common workflows,
+  and links to Swagger UI / OpenAPI spec
+- Static content, no authentication required
+- Served as text/plain with UTF-8 charset
+- Registered as a plain Flask blueprint (not flask-smorest) so it does not
+  appear in the OpenAPI spec

docs/v5-api-implementation-plan.md

@@ -630,6 +630,26 @@ DELETE /api/v5/admin/api-keys/{prefix}     — Revoke key by prefix (admin)
 - DELETE sets is_active=False (soft delete for audit trail)
 - Auth: admin scope required for all.
 
+### 5.13 AI Agent Orientation (`GET /llms.txt`)
+
+**File**: `lnt/server/api/v5/endpoints/agents.py`
+
+Serves a plain-text orientation document at `GET /llms.txt` following the llms.txt
+convention (analogous to robots.txt). Helps AI agents understand what LNT is, its
+domain concepts, and how to navigate the API.
+
+**Key design decisions:**
+- Plain Flask blueprint (not flask-smorest) — keeps it out of the OpenAPI spec
+- Registered on the Flask app directly in `create_v5_api()`
+- Static content defined as a Python string constant — no template or DB access
+- Content-Type: `text/plain; charset=utf-8`
+- No authentication required
+- Outside the `/api/v5/` prefix for conventional discoverability
+
+Content includes: LNT description, key concepts (test suite, machine, order, run,
+test, sample, regression, field change), endpoint listing, pagination format,
+links to Swagger UI and OpenAPI spec, and common workflows.
+
 ---
 
 ## 6. Testing Strategy

lnt/server/api/v5/__init__.py

@@ -32,4 +32,7 @@ def create_v5_api(app):
     from .endpoints import register_all_endpoints
     register_all_endpoints(smorest_api)
 
+    from .endpoints.agents import llms_txt_bp
+    app.register_blueprint(llms_txt_bp)
+
     return smorest_api

lnt/server/api/v5/endpoints/agents.py

@@ -0,0 +1,133 @@
+"""llms.txt endpoint: GET /llms.txt
+
+Serves a plain-text orientation document for AI agents, following the
+llms.txt convention (analogous to robots.txt). Describes what LNT is,
+its domain concepts, API structure, and common workflows.
+
+Registered as a plain Flask blueprint (not flask-smorest) so it does not
+appear in the OpenAPI spec.
+"""
+
+from flask import Blueprint, make_response
+import hashlib
+
+llms_txt_bp = Blueprint('llms_txt', __name__)
+
+LLMS_TEXT = """\
+# LNT — LLVM Nightly Test Infrastructure
+
+LNT is a performance testing infrastructure designed for tracking software
+performance over time. It collects benchmark results from test runs, detects
+regressions, and provides tools for performance analysis. Originally built
+for the LLVM compiler project, it can be used for any software project.
+
+## Key Concepts
+
+- **Test Suite**: A schema defining what metrics to collect (e.g., "nts" for
+  the LLVM nightly test suite). Each suite has its own set of machines, orders,
+  runs, and tests. All data queries are scoped to a specific test suite.
+
+- **Machine**: A build/test environment identified by name (e.g.,
+  "clang-x86_64-linux"). Machines have key-value info fields describing
+  their configuration.
+
+- **Order**: A point in the revision history (e.g., a commit hash or revision
+  number). Orders define the sequence for time-series analysis. They may have
+  multiple fields (e.g., primary revision + dependent project revisions).
+
+- **Run**: A single test execution on a machine at a specific order. Contains
+  samples (individual test results) with metric values. Identified by UUID.
+
+- **Test**: A named benchmark or test case (e.g., "SingleSource/Benchmarks/
+  Dhrystone/dry"). Tests are created implicitly when runs are submitted.
+
+- **Sample**: A single data point: one test's metric values from one run.
+  Each sample records values for the metrics defined by the test suite schema
+  (e.g., execution_time, compile_time, code_size).
+
+- **Regression**: A detected performance change, grouping one or more field
+  changes. Has a state (detected, active, fixed, ignored, etc.), optional
+  title, and optional bug tracker link.
+
+- **Field Change**: A statistically significant change in a metric value
+  between two orders for a specific test on a specific machine.
+
+## REST API (v5)
+
+Base URL: /api/v5/
+Authentication: Bearer token in Authorization header. Reads are unauthenticated
+by default. Write operations require tokens with appropriate scopes
+(submit, triage, manage, admin).
+
+### Discovery
+
+  GET /api/v5/                  List test suites and API links
+
+### Per-Suite Endpoints (replace {ts} with suite name, e.g., "nts")
+
+  GET    /api/v5/{ts}/machines              List machines
+  GET    /api/v5/{ts}/machines/{name}       Machine detail
+  GET    /api/v5/{ts}/orders                List orders
+  GET    /api/v5/{ts}/orders/{value}        Order detail (with prev/next)
+  GET    /api/v5/{ts}/runs                  List runs
+  POST   /api/v5/{ts}/runs                  Submit a run
+  GET    /api/v5/{ts}/runs/{uuid}           Run detail
+  GET    /api/v5/{ts}/tests                 List tests
+  POST   /api/v5/{ts}/query                 Query time-series data
+  GET    /api/v5/{ts}/regressions           List regressions
+  GET    /api/v5/{ts}/field-changes         List unassigned field changes
+
+### Global Endpoints
+
+  GET    /api/v5/test-suites               List all test suites
+  GET    /api/v5/test-suites/{name}        Suite detail (schema + metrics)
+  GET    /api/v5/admin/api-keys            List API keys (admin)
+
+The endpoints above cover the most common read operations. The API also
+supports write operations (creating/updating/deleting machines, orders,
+runs, regressions, field changes, test suites, and API keys) which require
+appropriate authentication scopes. See the OpenAPI spec or Swagger UI for
+the complete endpoint list including all write operations.
+
+### Interactive Documentation
+
+  OpenAPI spec:  /api/v5/openapi/openapi.json
+  Swagger UI:    /api/v5/openapi/swagger-ui
+
+### Pagination
+
+List endpoints return cursor-paginated responses:
+  { "items": [...], "cursor": { "next": "...", "previous": null } }
+Pass cursor=<next> to get the next page. Use limit= to control page size.
+
+### Common Workflows
+
+1. Discover available data: GET /api/v5/ to list test suites, then
+   GET /api/v5/{ts}/machines to see what machines exist.
+
+2. Query performance history: POST /api/v5/{ts}/query with
+   { "metric": "execution_time", "machine": "machine-name",
+     "test": ["test/name"] } to get time-series data points.
+
+3. Submit a run: POST /api/v5/{ts}/runs with the LNT JSON report format.
+   Requires a token with "submit" scope.
+
+4. Check for regressions: GET /api/v5/{ts}/regressions?state=detected
+   to find new regressions. PATCH to update state, title, or bug link.
+
+5. Inspect a specific order: GET /api/v5/{ts}/orders/{value} returns
+   the order detail with previous/next navigation links.
+"""
+
+_ETAG = hashlib.md5(LLMS_TEXT.encode()).hexdigest()
+
+
+@llms_txt_bp.route('/llms.txt')
+def llms_txt():
+    """Serve the LNT orientation document for AI agents."""
+    resp = make_response(LLMS_TEXT)
+    resp.mimetype = 'text/plain'
+    resp.charset = 'utf-8'
+    resp.headers['Cache-Control'] = 'public, max-age=86400'
+    resp.headers['ETag'] = _ETAG
+    return resp

tests/server/api/v5/test_agents.py

@@ -0,0 +1,61 @@
+# Tests for the /llms.txt endpoint (AI agent orientation).
+#
+# RUN: rm -rf %t.instance %t.pg.log
+# RUN: %{utils}/with_postgres.sh %t.pg.log \
+# RUN:     %{utils}/with_temporary_instance.py %t.instance \
+# RUN:         -- python %s %t.instance
+# END.
+
+import sys
+import os
+import unittest
+
+sys.path.insert(0, os.path.dirname(__file__))
+from v5_test_helpers import create_app, create_client
+
+
+class TestLlmsTxt(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        super().setUpClass()
+        cls.app = create_app(sys.argv[1])
+        cls.client = create_client(cls.app)
+
+    def test_returns_200(self):
+        resp = self.client.get('/llms.txt')
+        self.assertEqual(resp.status_code, 200)
+
+    def test_content_type_is_text_plain(self):
+        resp = self.client.get('/llms.txt')
+        self.assertTrue(resp.content_type.startswith('text/plain'))
+
+    def test_contains_lnt_description(self):
+        resp = self.client.get('/llms.txt')
+        text = resp.get_data(as_text=True)
+        self.assertIn('LNT', text)
+        self.assertIn('performance testing infrastructure', text)
+
+    def test_contains_key_concepts(self):
+        resp = self.client.get('/llms.txt')
+        text = resp.get_data(as_text=True)
+        self.assertIn('Key Concepts', text)
+        self.assertIn('Test Suite', text)
+        self.assertIn('Machine', text)
+        self.assertIn('Regression', text)
+
+    def test_contains_api_links(self):
+        resp = self.client.get('/llms.txt')
+        text = resp.get_data(as_text=True)
+        self.assertIn('/api/v5/openapi/swagger-ui', text)
+        self.assertIn('/api/v5/openapi/openapi.json', text)
+
+    def test_contains_endpoint_listing(self):
+        resp = self.client.get('/llms.txt')
+        text = resp.get_data(as_text=True)
+        self.assertIn('/api/v5/{ts}/machines', text)
+        self.assertIn('/api/v5/{ts}/runs', text)
+        self.assertIn('/api/v5/{ts}/query', text)
+
+
+if __name__ == '__main__':
+    unittest.main(argv=[sys.argv[0]], exit=True)