feat: Enhance profile and comparison report formatting in sparkle-cli (…

[janoamaral]

This pull request introduces a new non-interactive "direct" mode for sparkle-cli, adds a runtime profiling and metrics system, and refactors internal components to support these features. The documentation is updated to reflect the new usage patterns, and profiling hooks are integrated throughout the codebase for performance analysis.

Key changes include:

New Features

• Direct (Non-Interactive) Mode:
  Adds a direct subcommand to sparkle-cli for automation, scripts, and integrations, providing a single final response on stdout. This mode supports both normal and reasoning (with thinking as an alias) and is documented in both README.md and user docs. [1] [2] [3] [4]

• Profiling and Metrics System:
  Introduces a runtime profiler that tracks step durations, token usage, and throughput. Profiling can be enabled via config or CLI flag, and includes summary and comparison reporting. New files implement the profiler's types, token estimation, and output formatting. [1] [2] [3] [4] [5] [6] [7]

Internal Refactoring and Instrumentation

• Profiler Integration in Search Service:
  The internal/search package is refactored to accept a profiler.Tracker and instrument key steps (embedding_retrieval, rerank) with profiling spans and metadata. [1] [2] [3] [4] [5] [6] [7]

API Enhancements

• Ollama Client and Stream Stats:
  The Ollama client and stream parser are extended to return token usage statistics (PromptEvalCount, EvalCount) from streamed responses, supporting more detailed profiling. [1] [2] [3] [4]

Documentation

• Updated Configuration and Usage Docs:
  Adds documentation for the new profiler option in the example config and describes the new direct mode and profiling features in the CLI and user guides. [1] [2] [3] [4]

---

Most important changes:

New CLI Modes and Profiling

• Adds a direct subcommand to sparkle-cli for non-interactive, single-response usage, with documentation and flag parsing logic. [1] [2] [3] [4]
• Implements a runtime profiler system, including CLI flags, config options, summary reporting, and historical comparison. [1] [2] [3] [4] [5] [6] [7]

Instrumentation and Internal Refactoring

• Refactors the search service to accept and use a profiler tracker, adding profiling spans and metadata to key search steps. [1] [2] [3] [4] [5] [6] [7]

API and Stats Enhancements

• Extends the Ollama client and stream parser to provide token usage statistics, enabling fine-grained profiling of LLM interactions. [1] [2] [3] [4]

Documentation

• Updates documentation and example configuration to describe new CLI modes and profiling options. [1] [2] [3] [4]