feat: record token counts on tasks for energy-per-token reporting

[davidberenstein1957]

What this adds

Energy per run is not a comparable number for an LLM: it depends entirely on how many prompts happened to be sent. Energy per output token is. CodeCarbon already measures the power draw over a task; the only missing ingredient was the token counter, which only the caller knows.

This PR lets the caller hand that counter over, and carries it through the existing task machinery to the output handlers.

User-facing surface

Three new fields on TaskEmissionsData, all defaulting to 0: input_tokens, output_tokens, n_requests. They are plain stored counters. No derived properties are exposed — an earlier version of this description claimed energy_per_output_token and emissions_per_request were added, and that was wrong. TaskEmissionsData.values is built from __dict__, so a property reaches no output method, and both figures are one division away from the columns above. See the comment at codecarbon/output_methods/emissions_data.py:115-117.

One recording entry point, on the tracker and mirrored on TaskEmissionsTracker:

with TaskEmissionsTracker(task_name="llama3.1:8b", tracker=tracker) as task:
    for prompt in prompts:
        response = client.chat.completions.create(...)
        task.record_tokens(
            input_tokens=response.usage.prompt_tokens,
            output_tokens=response.usage.completion_tokens,
        )

That is the whole API. CodeCarbon does not inspect the response object: the caller reads its own client's usage fields, which it already knows how to do, and no inference library is imported or added as a dependency. (A response= argument that duck-typed OpenAI / Ollama / vLLM payloads was in an earlier revision and has been removed — vendor response shapes drift, and each drift would land here as a silent zero.)

Counts accumulate over the life of one task; recording with no active task logs a warning and is otherwise a no-op.

The three fields flow through Task.out() and appear as three extra columns in the per-task CSV. Note that the task CSV is rewritten in full on each run (FileOutput.task_out writes a fresh dataframe to a per-run-id path), so there is no header-migration concern for existing files.

Verification

tests/test_token_tracking.py: accumulation across several record_tokens calls in one task, recording with no active task, and an end-to-end check that the columns land in the task CSV with the right values. tests/test_tracking_inference.py and test_docs_examples.py still pass.

uv run pytest tests/test_token_tracking.py tests/test_tracking_inference.py tests/test_docs_examples.py -q
15 passed

ruff format / ruff check are clean on the touched files (the repo-wide task lint / task format were not run — they currently churn ~120 unrelated files).

Deliberately left out

• No response-object introspection for any serving stack.
• No derived per-token / per-request properties; the raw counters and the existing energy columns are enough to compute them.
• No prefill/decode split — attributing those needs sub-second sampling the current scheduler cannot deliver.
• No per-request task granularity. A single request is typically far shorter than measure_power_secs, so per-request tasks would be dominated by measurement noise.
• Token counts stay task-level and do not propagate to run-level EmissionsData, since a run may mix inference with other work.
• Continuous batching makes per-request attribution physically meaningless; that is documented as a limitation rather than papered over.

Docs updated: an "LLM inference, energy per token" section in docs/tutorials/python-api.md and the three task columns in docs/reference/output.md.

Closes #1347

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.62%. Comparing base (065d0e6) to head (579cb92).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1362      +/-   ##
==========================================
+ Coverage   91.39%   91.62%   +0.22%     
==========================================
  Files          49       49              
  Lines        5056     5074      +18     
==========================================
+ Hits         4621     4649      +28     
+ Misses        435      425      -10     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.