Feature/repeat flag

[vincent5678]

Summary

Add repeat flag to aggregate trace results on repeated runs

Related Issue

Link the related issue if available.

Implements #18

Type of Change

• Bug fix
• New feature
• Refactor
• Documentation update
• CLI behavior change

What Changed

List the key changes in a few bullets.

• Added repeat flag
• Can compare against repeated runs and save repeated runs to json
• Will not print aggregated results to console for repeated runs

Validation

Describe how you validated this change.

CLI smoke check

oracletrace --help

Functional trace run

oracletrace your_script.py

JSON export and compare flow

oracletrace your_script.py --json baseline.json
oracletrace your_script.py --json current.json --compare baseline.json

CSV, ignore, and top flags

oracletrace your_script.py --csv trace.csv
oracletrace your_script.py --ignore "helper_function,debug_*"
oracletrace your_script.py --top 10

Docs build (if docs changed)

mkdocs build -f docs/mkdocs.yml

Checklist

• The code follows style conventions.
• I added unit tests for the new functionality.
• CI (GitHub Actions) is green.
• I updated documentation/README when needed.

Before/After Output (if applicable)

Include relevant CLI output snippets when behavior or formatting changed.

Before

After

Additional Notes

Function results become the average of results. For example:

            "name": "test.py:main",
            "total_time": 5.118640708737075,
            "call_count": 1,
            "avg_time": 5.118640708737075,
            "callees": [
                "test.py:process_data",
                "test.py:newfunc",
                "test.py:calculate_results"
            ]

call_count becomes the average amount of times this function is called per run. total_time becomes the average of total time the function spends in each run. avg_time is still the avg_time the individual function takes to run

[KaykCaputo]

I like the approach, we just need to get the tests passing.
Merging this will make it much easier for me to implement the warmup feature.

[KaykCaputo]

Actually, we should use the median instead of the average for these calculations. In a benchmarking context, the median is much more resilient to outliers—like random spikes in CI resource usage—providing far greater precision and reliability for our users.