docs updated

Author: igorbenav

docs/changelog.md

@@ -6,6 +6,36 @@ The Changelog documents all notable changes made to FastroAI. This includes new
 
 ---
 
+## [0.4.0] - Dec 19, 2025
+
+#### Added
+- **Enhanced Cost Tracking** by [@igorbenav](https://github.com/igorbenav)
+  - Cache token tracking (`cache_read_tokens`, `cache_write_tokens`) for accurate cost calculation with prompt caching
+  - Audio token tracking for multimodal models
+  - Request count tracking (`request_count`) for API call monitoring
+  - Tool call count tracking (`tool_call_count`) for agentic behavior metrics
+  - Provider-specific usage details (`usage_details` dict) for reasoning tokens, etc.
+
+- **Accurate Prompt Caching Costs**
+  - Cached tokens are now priced at 90% discount (Anthropic) automatically
+  - `CostCalculator.calculate_cost()` accepts optional `cache_read_tokens`, `cache_write_tokens` parameters
+  - Pricing overrides support cache token rates via `add_pricing_override(cache_read_per_mtok=..., cache_write_per_mtok=...)`
+  - Fixes cost overreporting when prompt caching is enabled (~18% more accurate)
+
+#### Changed
+- All Pydantic schemas now use `Field(description=...)` for better API documentation
+- `ChatResponse`, `StepUsage`, and `PipelineUsage` include new usage fields with sensible defaults
+- Backward compatible - existing code continues to work without changes
+
+#### Documentation
+- Updated FastroAgent guide with new response fields
+- Added Prompt Caching section to Cost Calculator guide
+- Updated API reference with enhanced schemas
+
+**Full Changelog**: https://github.com/benavlabs/fastroai/compare/v0.3.0...v0.4.0
+
+---
+
 ## [0.3.0] - Dec 17, 2025
 
 #### Added

docs/guides/cost-calculator.md

@@ -47,6 +47,27 @@ print(f"Session cost: ${calc.microcents_to_dollars(total_cost):.4f}")
 
 After 10,000 additions, you have an exact count. No cumulative rounding errors.
 
+## Prompt Caching
+
+Anthropic and OpenAI support prompt caching, where repeated system prompts are stored and reused at a significant discount - typically 90% cheaper for cached tokens. FastroAI automatically tracks cache tokens and factors them into cost calculations.
+
+When you use FastroAgent, cache tokens are tracked automatically:
+
+```python
+response = await agent.run("What's the weather?")
+
+print(f"Input tokens: {response.input_tokens}")
+print(f"Cached tokens: {response.cache_read_tokens}")  # Tokens from cache (90% discount)
+print(f"Cost: ${response.cost_dollars:.6f}")  # Accurate cost with cache discount
+```
+
+If you're using a long system prompt that gets cached, subsequent requests to the same agent will show cache hits. The cost calculation automatically applies the discounted rate for cached tokens.
+
+**Requirements for prompt caching:**
+
+- **Anthropic:** Prompts >= 1024 tokens with cache_control markers
+- **OpenAI:** Prompts >= 1024 tokens on gpt-4o models
+
 ## Direct Calculator Usage
 
 Sometimes you need cost calculation without running an agent - estimating costs upfront, building dashboards, or custom tracking:
@@ -66,6 +87,18 @@ print(f"Cost: {cost} microcents")  # 7500 microcents
 print(f"Cost: ${calc.microcents_to_dollars(cost):.6f}")  # $0.007500
 ```
 
+For accurate costs with prompt caching, pass cache tokens:
+
+```python
+cost = calc.calculate_cost(
+    model="claude-3-5-sonnet",
+    input_tokens=1000,
+    output_tokens=500,
+    cache_read_tokens=800,  # 800 of 1000 input tokens were cached
+)
+# Cost is lower because 800 tokens are priced at 90% discount
+```
+
 Model names get normalized automatically. Both `"gpt-4o"` and `"openai:gpt-4o"` work.
 
 ### Conversion Methods
@@ -111,6 +144,20 @@ calc.add_pricing_override(
 )
 ```
 
+You can also specify cache token rates for models that support prompt caching:
+
+```python
+calc.add_pricing_override(
+    model="my-cached-model",
+    input_per_mtok=3.00,
+    output_per_mtok=15.00,
+    cache_read_per_mtok=0.30,   # 90% discount for cached tokens
+    cache_write_per_mtok=3.75,  # 25% premium for cache writes
+)
+```
+
+If you don't specify cache rates, default discounts apply (90% for reads, 25% premium for writes) when cache tokens are passed to `calculate_cost()`.
+
 Overrides take precedence over genai-prices. Prices are in dollars per million tokens (the standard unit providers use).
 
 ### Using Custom Pricing with Agents

docs/guides/fastro-agent.md

@@ -102,14 +102,21 @@ print(f"Time: {response.processing_time_ms}ms")
 | `model` | `str` | Model that generated the response |
 | `input_tokens` | `int` | Prompt tokens consumed |
 | `output_tokens` | `int` | Completion tokens generated |
+| `cache_read_tokens` | `int` | Tokens read from prompt cache (typically 90% cheaper) |
+| `cache_write_tokens` | `int` | Tokens written to prompt cache |
 | `cost_microcents` | `int` | Cost in 1/1,000,000 of a dollar (for calculations) |
 | `cost_dollars` | `float` | Cost in dollars (for display) |
 | `processing_time_ms` | `int` | Wall-clock time |
 | `tool_calls` | `list` | Tools invoked during generation |
+| `tool_call_count` | `int` | Number of tool invocations |
+| `request_count` | `int` | Number of API requests (increases with tool use) |
 | `trace_id` | `str` | Tracing correlation ID |
+| `usage_details` | `dict` | Provider-specific details (e.g., reasoning tokens) |
 
 Use `cost_microcents` when you need to aggregate costs across many calls - integer math won't drift. Use `cost_dollars` when displaying to users.
 
+When prompt caching is enabled (Anthropic, OpenAI with long prompts), `cache_read_tokens` shows how many tokens came from cache at a 90% discount. This is automatically factored into `cost_microcents`.
+
 ## Structured Output
 
 Getting strings back means you have to parse them. For anything structured - extracting entities, classifying content, generating schemas - use Pydantic models instead: