Agnes AI Usage Analysis — User Guide

1. Overview

Agnes AI Usage Analysis is a browser-side analytics tool for Agnes usage exports. Upload one Agnes usage CSV and you can immediately inspect text tokens, image counts, video seconds, requests, cost, key-level breakdowns, custom project grouping, and daily trends.

• The three core metrics always stay side by side: Total Text Tokens, Generated Images, and Video Length (s)
• Overview and Trends now use Relative Comparison charts so different units can be compared together while hover still shows real values
• Cost is shown in US dollars ($), converted from `Consumption Amount(cents)`
• By Key and By Custom Projects support sorting by text, image, video, cost, and requests, and cost values can be copied in one click
• Share cards support all four tabs and automatically follow the current locale and theme
• All CSV parsing, aggregation, and chart rendering stay in the browser and never upload your raw file

2. Quick Start

1. Sign in to the Agnes AI console and open the usage or billing page.
2. Export a single usage CSV file.
3. Make sure the CSV includes Type, Secret Key Name, Consumption Model, Consumption Amount(cents), Consumption Quantity, Consumption Time, and Consumption Status.
4. Drag the CSV into the homepage uploader, or click the uploader to choose the file manually.
5. Wait for parsing to finish. The page automatically switches from the landing page into dashboard mode.

The current version supports one CSV file only, with a 50 MB limit per file. No ZIP extraction and no amount/cost file pairing are required. Only rows with `Consumption Status=success` are counted, and the dashboard stays fixed to four tabs: Overview, By Custom Projects, By Key, and Trends.

3. Navigation And Base Layout

Before upload, the landing page now follows the sequence Upload Area → How It Works → FAQ → About, and the earlier extra three-metric showcase block has been removed. After a CSV is parsed successfully, the page switches into dashboard mode. The action bar shows the current filename and date range, plus actions for loading another file or clearing the result.

Error banners are used for blocking issues such as empty files, missing columns, or malformed amount values. Warning banners are used for partial quantity parsing or ignored non-success statuses.

4. KPI Strip And Filtering

When the CSV contains multiple models, a model filter appears below the tab bar. You can switch between All Models and a single model to inspect the same core metrics, tables, and comparisons from a narrower scope.

The three-metric hero now uses a more restrained centered layout: there is no eyebrow label anymore, and auxiliary notes sit on one line below the metric grid.

5. Views And Project Setup

• Overview: the hero always keeps the three core metrics visible together, and both charts below now stay in Relative Comparison mode instead of switching through one core metric at a time.
• By Key: supports sorting by text tokens, image counts, video seconds, cost, and requests; the table header, top sorting pills, and progress bars all stay linked to the same active metric.
• By Custom Projects: lets you aggregate multiple Secret Keys into business projects, while any remaining keys fall back to Uncategorized.
• Trends: keeps the hero fixed and uses one combined three-line chart to compare relative changes across units, instead of returning to the older single-metric trend flow.

1. Open the By Custom Projects tab and click `Configure`.
2. Add project names or remove projects you no longer need.
3. Drag keys from the Unassigned Keys area into a target project, or assign them through the dropdown next to each unassigned key.
4. Click `Save` to persist the project configuration into local browser storage.

The cost column in both By Key and By Custom Projects can be clicked to copy the displayed value, which is convenient for reporting and follow-up analysis.

6. Share Cards

1. Click the Share button on the right side of the tab bar.
2. Enter a signature name (required) and optionally add a short message.
3. Review the live preview inside the modal. Export actions stay disabled until the charts are ready.
4. Copy the image to clipboard or download a PNG file.

• The current version supports Overview, By Custom Projects, By Key, and Trends.
• Share cards follow the current locale and theme, and the hero metrics on the card update with the active filtered result.
• Overview and Trends share cards include Relative Comparison context plus static annotations such as peak, lowest, or daily average so the image still reads clearly outside hover interactions.
• The QR code still points to the existing site domain. This external link remains intentionally preserved for now.

7. CSV Schema Notes

• Typical text quantity value: `input:142064/output:85`
• Typical image quantity value: `images:3`
• Typical video quantity value: `video_seconds:180`
• If only part of a quantity string can be parsed, the valid part is still counted and a warning is emitted.

8. Privacy And Troubleshooting