@jrpool/kilotest 37.1.0 → 38.1.0

package/{reportList/api.js → api/reportList.js}

@@ -22,54 +22,62 @@ const thisHost = process.env.THIS_KILOTEST_HOST;
 
 // Returns a response to an API request for reports.
 exports.response = async () => {
+  // Initialize an array of facts about reports.
   const reportsFacts = [];
   // Get the available logs, with added job names.
   const availableLogs = await getLogs();
-  // For each of them:
+  // For each log:
   for (const availableLog of availableLogs) {
     const {jobName} = availableLog;
     const [timeStamp, jobID] = jobName.split('-');
     const reportSize = await getReportSize(timeStamp, jobID);
-    const {superseded, url, what} = availableLog;
-    reportsFacts.push({
-      identifier: jobName,
-      'creation date and time': getDateTime(timeStamp),
-      'days since the creation date': getAgoDays(timeStamp),
-      'tested web page': {
-        description: what,
-        URL: url
-      },
-      'whether a later report about the same page exists': !! superseded,
-      'URLs for incrementally getting facts from the report': {
-        'for you': `${thisHost}/api/reportIssues/${timeStamp}/${jobID}`,
-        'for humans': `${thisHost}/reportIssues.html/${timeStamp}/${jobID}`
-      },
-      'size of the report in bytes': reportSize,
-      'URL to get the entire report as machine-oriented JSON': `${thisHost}/fullReport.json/${timeStamp}/${jobID}`
-    });
+    // If its report exists:
+    if (reportSize) {
+      const {superseded, url, what} = availableLog;
+      // Add facts about the report to the array.
+      reportsFacts.push({
+        identifier: jobName,
+        'creation date and time': getDateTime(timeStamp),
+        'days since the creation date': getAgoDays(timeStamp),
+        'tested web page': {
+          description: what,
+          URL: url
+        },
+        'whether a later report about the same page exists': !! superseded,
+        'URLs for more details': {
+          'for you': `${thisHost}/api/reportSummary/${timeStamp}/${jobID}`,
+          'for humans': `${thisHost}/reportIssues.html/${timeStamp}/${jobID}`
+        },
+        'size of the report in bytes': reportSize,
+        'URL to get the entire report as machine-oriented JSON': `${thisHost}/fullReport.json/${timeStamp}/${jobID}`
+      });
+    }
+    // Otherwise, i.e. if the report does not exist:
+    else {
+      // Report this.
+      console.error(`Log ${jobName} exists but its report does not.`);
+    }
   }
-  // Get a response.
+  // Create a response body.
   const content = {
     summary: `This document fulfills a request made by a language model to a Kilotest tool. The model asked which reports about the front-end quality (i.e. accessibility, usability, and standards conformity) of web pages are available from Kilotest. Each report describes the results of a job that tested one web page. Kilotest, with the help of Testaro, Testilo, and an ensemble of ten rule engines, performs more than a thousand tests on a public web page, using a combination of rule- and machine-learning-based methods. Kilotest exposes API endpoints and web UI URLs to recommend web pages for testing and to obtain information from Kilotest reports. You and your users can learn more about Kilotest and the advantages of testing with an ensemble of rule engines at the deployed instance of Kilotest (${process.env.DEPLOYED_KILOTEST_HOST}).`,
     'tool collection name': 'Kilotest',
-    'tool name': 'getListOfAllAvailableReports',
+    'tool name': 'listAllAvailableReports',
     request: {
-      'type of request': {
-        identifier: 'reportList',
-        description: 'Get a list of all available reports. Each report describes the results of a job that tested a web page for front-end quality (i.e. accessibility, usability, and standards conformity). For each report, the list identifies which page was tested and when and provides URLs to begin incremental retrieval of the test results.'
-      },
+      description: 'List all available reports. For each report, the list should identify which page was tested and when and provide URLs to begin incremental retrieval of the test results from the report.',
       method: 'GET',
       URLs: {
-        'URL of your request': `${thisHost}/api/reportList`,
-        'equivalent URL for humans': `${thisHost}/targets.html`
+        'for you': `${thisHost}/api/reportList`,
+        'for humans': `${thisHost}/targets.html`
       },
       'closest ancestor request': null
     },
     'response metadata': {
       identifier: `${getNowStamp()}-${getRandomString(3)}`,
-      'date and time': new Date().toISOString(),
+      'date and time': new Date().toISOString()
     },
-    'available reports': reportsFacts
+    'response content': reportsFacts
   };
+  // Return it.
   return content;
 };

package/api/reportSummary.js

@@ -0,0 +1,181 @@
+/*
+  api.js
+  Responds to the reportSummary API request.
+*/
+
+// IMPORTS
+
+const {
+  getNowStamp,
+  getRandomString,
+  getReport,
+  isHidden,
+  objectSort,
+  ruleEngines
+} = require('../util');
+const issuesClassification = require('testilo/procs/score/tic').issues;
+
+// CONSTANTS
+
+const thisHost = process.env.THIS_KILOTEST_HOST;
+
+// FUNCTIONS
+
+// Returns facts about a report.
+const getReportFacts = async (report) => {
+  // Initialize the facts.
+  const facts = {
+    ruleEngineIDs: new Set(),
+    reporterIDs: new Set(),
+    issueIDs: new Set(),
+    violators: new Set()
+  };
+  // For each act in the report:
+  report.acts.forEach(act => {
+    // If it is a test act:
+    if (act.type === 'test') {
+      const {result, which} = act;
+      // Ensure its rule engine is in the facts.
+      facts.ruleEngineIDs.add(which);
+      const instances = result?.standardResult?.instances ?? [];
+      // For each of its standard instances:
+      instances.forEach(instance => {
+        const {catalogIndex, issueID} = instance;
+        // If the instance identifies a non-ignorable issue:
+        if (issueID && issueID !== 'ignorable') {
+          const issueClassification = issuesClassification[issueID];
+          // If the issue is classified and has a valid weight:
+          if (issueClassification && [1, 2, 3, 4].includes(issueClassification.weight)) {
+            // Ensure the issue ID is in the facts.
+            facts.issueIDs.add(issueID);
+            // Ensure its rule engine is among the reporters in the facts.
+            facts.reporterIDs.add(which);
+            // If the instance has a catalog index:
+            if (catalogIndex) {
+              // Ensure the violator is in the facts.
+              facts.violators.add(catalogIndex);
+            }
+          }
+        }
+      });
+    }
+  });
+  // Return the facts.
+  return facts;
+};
+// Returns facts about a rule engine.
+const getRuleEngineFacts = ruleEngineID => {
+  const ruleEngineData = ruleEngines[ruleEngineID];
+  return {
+    identifier: ruleEngineID,
+    name: ruleEngineData[0],
+    sponsor: ruleEngineData[1]
+  };
+};
+// Returns facts about rule engines that were prevented from testing the page.
+const getPreventionFacts = report => {
+  return objectSort(Object.entries(report.jobData.preventions).map(([ruleEngineID, reason]) => ({
+    'name': getRuleEngineFacts(ruleEngineID).name,
+    'reason for failure': reason
+  })), 'name', 'alpha');
+};
+// Returns rule engine IDs sorted by name.
+const getSortedRuleEngineIDs = ruleEngineIDSet => {
+  return Array.from(ruleEngineIDSet).sort((a, b) => {
+    const aData = ruleEngines[a][0];
+    const bData = ruleEngines[b][0];
+    return aData.localeCompare(bData, 'en', {sensitivity: 'base'});
+  });
+};
+// Returns issue IDs sorted by priority and summary.
+const getSortedIssueIDs = issueIDSet => {
+  return Array.from(issueIDSet).sort((a, b) => {
+    const aData = issuesClassification[a];
+    const bData = issuesClassification[b];
+    if (aData.weight !== bData.weight) {
+      return bData.weight - aData.weight;
+    }
+    return aData.summary.localeCompare(bData.summary, 'en', {sensitivity: 'base'});
+  });
+};
+// Get facts about an issue.
+const getIssueFacts = (issueID, timeStamp, jobID) => {
+  const issueData = issuesClassification[issueID];
+  const {summary, weight, why} = issueData;
+  return {
+    identifier: issueID,
+    summary,
+    'impact on a user': why,
+    'priority': ['lowest', 'low', 'high', 'highest'][weight - 1],
+    'URLs for more details': {
+      'for you': `${thisHost}/api/reportIssue/${issueID}/${timeStamp}/${jobID}`,
+      'for humans': `${thisHost}/reportIssue.html/${issueID}/${timeStamp}/${jobID}`
+    }
+  };
+};
+// Returns a response to an API request for a summary of one report.
+exports.response = async (args) => {
+  const [timeStamp, jobID] = args;
+  const reportIsHidden = await isHidden(timeStamp, jobID);
+  // If the report exists and is hidden:
+  if (reportIsHidden) {
+    // Return this.
+    return {
+      status: 'error',
+      message: 'Report not available',
+    };
+  }
+  // Otherwise, i.e. if the report is not hidden, get it.
+  const report = await getReport(timeStamp, jobID);
+  const {error} = report;
+  // If this failed:
+  if (error) {
+    // Return why.
+    return {
+      status: 'error',
+      message: error
+    };
+  }
+  // Otherwise, i.e. if it succeeded, get facts about it.
+  const reportFacts = await getReportFacts(report);
+  // Create a response body.
+  const content = {
+    summary: 'This document fulfills a request made by a language model to a Kilotest tool. The model asked for a summary of one Kilotest report. The model had previously used the listAllAvailableReports tool and had acquired from that tool basic facts about Kilotest, the ensemble testing that Kilotest performs, and the reports available from Kilotest. This summary does not repeat those facts.',
+    'tool collection name': 'Kilotest',
+    'tool name': 'summarizeOneReport',
+    request: {
+      description: 'Summarize one report. The summary should briefly describe the testing job and the results, including the rule engines that tested the web page and the issues that were revealed by the reported rule violations, and provide URLs for getting details about issues. The timeStamp and jobID parameters identify the report and were obtained from the response to a listAllAvailableReports operation.',
+      method: 'GET',
+      URLs: {
+        'for you': `${thisHost}/api/reportSummary/${timeStamp}/${jobID}`,
+        'for humans': `${thisHost}/reportIssues.html/${timeStamp}/${jobID}`
+      },
+      'closest ancestor request': {
+        'tool name': 'listAllAvailableReports',
+        description: 'List all available reports.',
+        URLs: {
+          'for you': `${thisHost}/api/reportList`,
+          'for humans': `${thisHost}/targets.html`
+        }
+      }
+    },
+    'response metadata': {
+      identifier: `${getNowStamp()}-${getRandomString(3)}`,
+      'date and time': new Date().toISOString()
+    },
+    'response content': {
+      'rule engines that tried to test the page': getSortedRuleEngineIDs(reportFacts.ruleEngineIDs)
+      .map(id => getRuleEngineFacts(id)),
+      'rule engines that could not test the page': getPreventionFacts(report),
+      'names of rule engines that reported rule violations': Array
+      .from(reportFacts.reporterIDs)
+      .map(id => getRuleEngineFacts(id).name)
+      .sort((a, b) => a.localeCompare(b, 'en', {sensitivity: 'base'})),
+      'number of elements reported as violators': reportFacts.violators.size,
+      'issues revealed': getSortedIssueIDs(reportFacts.issueIDs)
+      .map(id => getIssueFacts(id, timeStamp, jobID))
+    }
+  };
+  // Return it.
+  return content;
+};

package/diagnoses/index.js

@@ -23,10 +23,27 @@ const path = require('path');
 
 // Adds parameters to a query for the answer page.
 const populateQuery = async (issueID, timeStamp, jobID, catalogIndex, pathID, query) => {
+  // Get descriptions of the page facts.
   const pageDataStrings = await getPageDataStrings(timeStamp, jobID);
-  const {what, url, urlLink, testInfo} = pageDataStrings;
+  // If this failed:
+  if (pageDataStrings.error) {
+    // Populate the query with the reason.
+    query.error = pageDataStrings.error;
+    // Stop populating the query.
+    return;
+  }
+  const {testInfo, url, urlLink, what} = pageDataStrings;
+  // Otherwise, i.e. if it succeeded, get the report.
   const report = await getReport(timeStamp, jobID);
   const {acts, catalog} = report;
+  // If this failed:
+  if (report.error) {
+    // Populate the query with the reason.
+    query.error = report.error;
+    // Stop populating the query.
+    return;
+  }
+  // Otherwise, i.e. if it succeeded, get the catalog item of the specified violator.
   const catalogItem = catalog[catalogIndex] ?? {};
   const {boxID, startTag, tagName, text} = catalogItem;
   query.catalogIndex = catalogIndex;
@@ -45,7 +62,15 @@ const populateQuery = async (issueID, timeStamp, jobID, catalogIndex, pathID, qu
   query.target = what;
   query.urlLink = urlLink;
   query.testInfo = testInfo;
-  query.issue = issues[issueID].summary;
+  query.issue = issues[issueID]?.summary;
+  // If adding the issue summary failed:
+  if (! query.issue) {
+    // Populate the query with the reason.
+    query.error = 'Issue not found';
+    // Stop populating the query.
+    return;
+  }
+  // Otherwise, i.e. if it succeeded, get the issue details.
   const issue = issues[issueID];
   const {wcag, weight, why} = issue;
   query.why = why;
@@ -118,7 +143,15 @@ exports.answer = async (pageArgs, search) => {
   const query = {};
   // Create a query to replace the placeholders.
   await populateQuery(issueID, timeStamp, jobID, catalogIndex, pathID, query);
-  // If the test specifications are valid:
+  // If this failed:
+  if (query.error) {
+    // Return why.
+    return {
+      status: 'error',
+      message: query.error
+    };
+  }
+  // Otherwise, if it succeeded and the report facts were obtained:
   if (query.testInfo) {
     // Get the template.
     let answerPage = await fs.readFile(path.join(__dirname, 'index.html'), 'utf8');
@@ -132,9 +165,10 @@ exports.answer = async (pageArgs, search) => {
       answerPage
     };
   }
-  // Otherwise, report this.
+  // Otherwise, i.e. if the report facts were not obtained:
+  // Report this.
   return {
     status: 'error',
-    message: 'Invalid report specification'
+    message: 'Report facts not obtained'
   };
 };

package/docs/decisions/001-api-design.md

@@ -42,7 +42,7 @@ As of the date of this decision, a partial initial API version already exists: a
 
 ## Considered options
 
-1. **Iterate and instrument.** (1) Add a tool that implements level 4; then (2) add a tool that asks LLMs to comment on how the API design could better satisfy their needs; then (3) add metrics to make API usage and submitted LLM comments available to Kilotest managers.
+1. **Iterate and instrument.** (1) Finish redesigning the tools at levels 1, 2, and 3, to represent the hypothesized typical needs of LLM consumers; then (2) add a tool that implements level 4; then (3) add a tool that asks LLMs to comment on how the API design could better satisfy their needs; then (4) add metrics to make API usage and submitted LLM comments available to Kilotest managers.
 2. **Research first.** (1) Pause further API development while doing fundamental research to predict LLM needs; then (2) resume API and metrics development, including API redesign if the research results warrant.
 
 ## Decision
@@ -98,7 +98,7 @@ The sub-decision was **identifiers plus labels** (option 2). This decision was b
 - **Risk:** The cost estimate assumes a well-behaved client that preserves conversation history; a poorly implemented client could still incur higher-than-necessary costs.
   - **Mitigation:** MCP clients are expected to maintain message history by protocol; the ancestor labels provide a minimal human-friendly substitute.
 - **Risk:** Scenario 1 users may still want an aggregated "everything about page X" response.
-  - **Mitigation:** A future tool can be added to aggregate the hierarchy on the server side and return a structured summary, but that decision is deferred until usage data justify it.
+  - **Mitigation:** A future tool can be added to aggregate the hierarchy on the server side and return a structured summary, but that decision is deferred until usage and suggestions data justify it.
 
 ## References
 

package/index.js

@@ -274,26 +274,30 @@ const requestHandler = async (request, response) => {
       if (isTimeStamp(timeStamp) && isJobID(jobID)) {
         const reportHidden = await isHidden(timeStamp, jobID);
         // If the report exists and is hidden:
-        if (reportHidden === true) {
-          console.log(`ERROR: Hidden report ${timeStamp}-${jobID} requested`);
+        if (reportHidden) {
+          console.error(`Hidden report ${timeStamp}-${jobID} requested`);
           // Report this as suspected abuse.
           await serveError(
-            getAbuseError(request, `Requested report ${timeStamp}-${jobID} not available`),
+            getAbuseError(request, `Hidden report ${timeStamp}-${jobID} requested`),
             response,
             true
           );
         }
-        // Otherwise, if the report does not exist or another error occurred:
-        else if (typeof reportHidden === 'string') {
-          // Report this as suspected abuse.
-          await serveError(getAbuseError(request, reportHidden), response, true);
-        }
-        // Otherwise, i.e. if the report log is valid and not hidden:
+        // Otherwise, i.e. if the report is not hidden:
         else {
-          // Get the report.
+          // Get it.
           const report = await getReport(timeStamp, jobID);
-          // If it exists and is valid:
-          if (typeof report === 'object') {
+          // If this failed:
+          if (report.error) {
+            // Report this as suspected abuse.
+            await serveError(
+              getAbuseError(request, `Nonexistent report ${timeStamp}-${jobID} requested`),
+              response,
+              true
+            );
+          }
+          // Otherwise, i.e. if it succeeded:
+          else {
             // Serve response headers for a JSON download.
             setHeaders('application/json', null, 'low');
             response.setHeader(
@@ -302,11 +306,6 @@ const requestHandler = async (request, response) => {
             // Download the report.
             response.end(getJSON(report));
           }
-          // Otherwise, i.e. if an error occurred:
-          else {
-            // Report it.
-            await serveError({message: report}, response, true);
-          }
         }
       }
       // Otherwise, i.e. if the request is syntactically invalid:
@@ -346,15 +345,15 @@ const requestHandler = async (request, response) => {
       // If the service is provision of a list of all available reports:
       if (service === 'reportList') {
         // Get the response (potentially error) data.
-        const responseData = await require(path.join(__dirname, 'reportList', 'api')).response(specs);
+        const responseData = await require(path.join(__dirname, 'api', 'reportList')).response(specs);
         // Send them.
         setHeaders('application/json', null, 'ultra');
         response.end(JSON.stringify(responseData));
       }
-      // Otherwise, if the service is provision of issue statistics for a report:
-      else if (service === 'reportIssues') {
+      // Otherwise, if the service is provision of a report summary:
+      else if (service === 'reportSummary') {
         // Get the response (potentially error) data.
-        const responseData = await require(path.join(__dirname, 'reportIssues', 'api'))
+        const responseData = await require(path.join(__dirname, 'api', 'reportSummary'))
         .response(specs);
         // Send them.
         setHeaders('application/json', null, 'high');
@@ -702,12 +701,12 @@ const requestHandler = async (request, response) => {
         }
         // Otherwise, if the first segment is the report finding service:
         else if (segments[0] === 'target') {
-          const {what = '', hostname = ''} = postData;
-          // If the payload contains a description fragment or hostname fragment:
-          if (what || hostname) {
+          const {description = '', hostname = ''} = postData;
+          // If the payload contains a description or hostname:
+          if (description || hostname) {
             // Process the request and get the response data.
             const responseData = await require(path.join(__dirname, 'target', 'api'))
-            .response([what, hostname]);
+            .response([description, hostname]);
             // Send them.
             setHeaders('application/json', null, 'ultra');
             response.end(JSON.stringify(responseData));
@@ -732,7 +731,8 @@ const requestHandler = async (request, response) => {
             if (await isReportAvailable(what, url)) {
               // Report this.
               responseData = {
-                warning: 'A report on the page is already available'
+                status: 'warning',
+                message: 'A report on the page is already available'
               }
             }
             // Otherwise, i.e. if no report on the page is available:

package/issues/index.js

@@ -1,6 +1,6 @@
 /*
   index.js
-  Answers the targets question.
+  Answers the issues question.
 */
 
 // IMPORTS
@@ -24,6 +24,8 @@ const path = require('path');
 
 // Gets summary data on the issues reported in a set of reports.
 const getIssuesSummary = async logs => {
+  // Initialize the summary.
+  const summary = {};
   // Initialize data for a summary.
   const issuesData = {};
   // For each log of a report to be inspected:
@@ -37,8 +39,14 @@ const getIssuesSummary = async logs => {
     }
     // Get the corresponding report.
     const report = await getReport(timeStamp, jobID);
-    // For each act in it:
-    report.acts.forEach(act => {
+    const {acts = [], error} = report;
+    // If this failed:
+    if (error) {
+      // Populate the summary with the reason.
+      summary.error = error;
+    }
+    // For each act in it (none if the report retrieval failed):
+    acts.forEach(act => {
       // If it is a test act:
       if (act.type === 'test') {
         const {result, which} = act;
@@ -60,11 +68,9 @@ const getIssuesSummary = async logs => {
       }
     });
   }
-  // Initialize the summary.
-  const summary = {
-    totalCount: 0,
-    issues: []
-  };
+  // Initialize the summary properties.
+  summary.totalCount = 0;
+  summary.issues = [];
   // For each issue:
   Object.entries(issuesData).forEach(([issueID, data]) => {
     const {count, reporters} = data;
@@ -107,7 +113,14 @@ const populateQuery = async query => {
   const targetLogs = (await getLogs()).filter(log => ! log.superseded);
   // Get summary data on the issues.
   const issuesSummary = await getIssuesSummary(targetLogs);
-  // Initialize the lines.
+  // If this failed:
+  if (issuesSummary.error) {
+    // Populate the query with the reason.
+    query.error = issuesSummary.error;
+    // Stop populating the query.
+    return;
+  }
+  // Otherwise, i.e. if it succeeded, initialize the lines.
   const lines = [];
   const margin = ' '.repeat(6);
   // For each weight:
@@ -159,7 +172,15 @@ exports.answer = async () => {
   const query = {};
   // Create a query to replace placeholders.
   await populateQuery(query);
-  // Get the template.
+  // If the query reports an error:
+  if (query.error) {
+    // Return why.
+    return {
+      status: 'error',
+      message: query.error
+    };
+  }
+  // Otherwise, i.e. if the query does not report an error, get the template.
   let answerPage = await fs.readFile(path.join(__dirname, 'index.html'), 'utf8');
   // Replace its placeholders.
   Object.keys(query).forEach(param => {

package/llms-full.txt

@@ -63,7 +63,7 @@ Kilotest offers a comprehensive suite of capabilities to users via its web UI:
 - Get statistics about issues reported in one report: `https://kilotest.com/reportIssues.html/{timeStamp}/{jobID}`
 - Get details about one issue reported in one report: `https://kilotest.com/reportIssue.html/{issueID}/{timeStamp}/{jobID}`
 - Get diagnoses by rule engines of rule violations for one HTML element exhibiting one issue in one report: `https://kilotest.com/diagnoses.html/{issueID}/{timeStamp}/{jobID}/{catalogIndex}`
-- [Recommend the testing of a not-yet-tested page](`https://kilotest.com/testRecForm.html`)
+- [Recommend the testing of a not-yet-tested page](https://kilotest.com/testRecForm.html)
 - Recommend the retesting of a previously tested page: `https://kilotest.com/retestRecForm.html/{timeStamp}/{jobID}`
 - [Get statistics about frequently reported issues across all pages](https://kilotest.com/issues.html)
 - [Get a list of the operations that Kilotest managers are authorized to request](https://kilotest.com/manage.html)
@@ -73,28 +73,28 @@ Kilotest offers a comprehensive suite of capabilities to users via its web UI:
 
 Kilotest is implementing a richer suite of capabilities optimized for language models. In the specifications below, the term `report` refers to the records of one session in which a web page is tested.
 
-The implementation is currently in an alpha phase and offers 4 tools:
+The implementation is currently in an alpha phase and offers these tools:
 
 - `summarizeQualityOfMatchingWebPages`
   - method: `POST`
   - purpose: summarize front-end quality test results from available reports about web pages whose descriptions or hostnames match those that you specify
   - path: `/api/target`
   - payload properties
-    - `what`: all or part of a description of the page
-    - `hostname`: all or part of the hostname of the page
-- `getListOfAllAvailableReports`
+    - `description of the web page`: all or part of a description of the page
+    - `hostname of the web page`: all or part of the hostname of the page
+- `listAllAvailableReports`
   - method: `GET`
-  - purpose: get a list of all available reports
+  - purpose: list all available reports
   - path: `/api/reportList`
   - caveat: Cached results are likely to be stale and should not be used
-- `describeQualityOfOneWebPage`
+- `summarizeOneReport`
   - method: `GET`
-  - purpose: provide statistics about front-end quality issues reported in one report
-  - path: `/api/reportIssues/{timeStamp}/{jobID}`
+  - purpose: summarize one report
+  - path: `/api/reportSummary/{timeStamp}/{jobID}`
   - parameters
     - `timeStamp`: initial segment of report identifier
     - `jobID`: final segment of report identifier
-  - source of parameters: response to a `getListOfAllAvailableReports` request
+  - source of parameters: response to a `listAllAvailableReports` request
 - `describeOneIssueFromOneReport`
   - method: `GET`
   - purpose: provide details about one issue from one report
@@ -103,7 +103,7 @@ The implementation is currently in an alpha phase and offers 4 tools:
     - `issueID`: identifier of the issue
     - `timeStamp`: initial segment of report identifier
     - `jobID`: final segment of report identifier
-  - source of parameters: response to a `describeQualityOfOneWebPage` request
+  - source of parameters: response to a `summarizeOneReport` request
 - `describeOneViolatorOfOneIssueFromOneReport`
   - method: `GET`
   - purpose: provide diagnoses about one issue exhibited by one HTML element in one report [NOT YET IMPLEMENTED]
@@ -120,9 +120,9 @@ The implementation is currently in an alpha phase and offers 4 tools:
   - path: `/api/testRecForm`
   - payload properties
 
-    - `what`: description of the page to be tested
-    - `url`: URL of the page to be tested
-    - `why`: reason for testing the page
+    - `description of the web page`: description of the page to be tested
+    - `hostname of the web page`: URL of the page to be tested
+    - `reason for testing the web page`: reason for testing the page
 
   - possible responses:
 
@@ -146,7 +146,7 @@ An [OpenAPI specification for Kilotest](https://kilotest.com/openapi.yaml) is av
 
 When you use Kilotest tools, you are free to perform any appropriate interpretation and condensation of the results for presentation to users. However, users expect the sources of facts and interpretations to be truthfully represented. Do not meld facts from Kilotest tools with interpretations of your own in a manner that implies attribution of both to Kilotest.
 
-An example of a **poor** attribution is “Here are the results from Kilotest: …. The page is at risk of …. Among all the issues, … are critical and require immediate attention.” This attribution is poor because it incorrectly implies interpretetations and advice to Kilotest.
+An example of a **poor** attribution is “Here are the results from Kilotest: …. The page is at risk of …. Among all the issues, … are critical and require immediate attention.” This attribution is poor because it incorrectly implies that Kilotest produced the interpretations and advice.
 
 An example of a **good** attribution is “Kilotest reported these issues: …. On the basis of these results, I conclude that there is a serious risk of …, and, if you are responsible for maintaining the page, I recommend ….”
 

package/llms.txt

@@ -9,8 +9,8 @@ There is a [detailed explanation of Kilotest and its capabilities for LLMs](http
 ## API
 
 - [Get summaries of reports about a specified web page](/api/target)
-- [Get a list of all available reports](/api/reportList)
-- Get summarized test results from one report: `/api/reportIssues/{timeStamp}/{jobID}`
+- [List all available reports](/api/reportList)
+- Summarize one report: `/api/reportSummary/{timeStamp}/{jobID}`
 - Get details about one issue from one report: `/api/reportIssue/{issueID}/{timeStamp}/{jobID}`
 - Recommend testing of a web page: `/api/testRecForm` (requires `POST` request)
 - [OpenAPI specification for Kilotest](https://kilotest.com/openapi.yaml)