Overwriting the file as intended to improve the repository presentation.
👻 GhostTrace
GhostTrace is a lightweight Python library designed to record the "roads not taken" by your AI agents. It captures rejected alternatives (phantom branches), tracks their latency, and estimates API costs, providing deep insights into your agent's decision-making process.
✨ Features
- 🛤️ Phantom Branch Tracking: Record every alternative decision your agent considered but rejected.
- 💰 Cost Estimation: Automatically calculate estimated USD costs for various LLM models (GPT-4, Claude-3, etc.).
- ⏱️ Latency Monitoring: Measure the time taken for each decision branch.
- 📄 JSON Exports: Save traces to a structured
.ghost.jsonformat for later analysis or replaying. - 💻 Interactive CLI: Replay agent sessions in your terminal with rich, formatted output.
🚀 Installation
Install GhostTrace via pip:
pip install ghosttrace
🛠️ Quick Start
Basic Usage
from ghosttrace.ghost_writer import GhostWriter
# Initialize the writer
writer = GhostWriter(output_dir='.')
def my_evaluate_fn(decision, context):
# Your logic to evaluate a decision
if "risky" in decision:
return {"status": "rejected", "reason": "Too risky for production"}
return {"status": "accepted"}
# Evaluate and record a decision with tracking
result = writer.evaluate_and_record(
decision="Update database schema directly",
evaluate_fn=my_evaluate_fn,
context={"env": "production"},
input_tokens=1200,
output_tokens=400,
model="gpt-4-turbo"
)
Using the CLI
GhostTrace comes with a built-in CLI to replay your agent's traces:
# Run a mock recording session
ghosttrace record --goal "Refactor auth module"
# Replay the session
ghosttrace replay <session_id>.ghost.json
# Show phantom branches (the roads not taken)
ghosttrace replay <session_id>.ghost.json --show-phantoms
📊 Supported Models for Cost Tracking
GhostTrace supports cost estimation for popular models including:
- OpenAI:
gpt-4,gpt-4-turbo,gpt-3.5-turbo - Anthropic:
claude-3-opus,claude-3-sonnet,claude-3-haiku - Custom: Default pricing available for other models.
🤝 Contributing
Contributions are welcome! Feel free to open an issue or submit a pull request to help improve GhostTrace.
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
Made with 👻 by Ahmed Allam
Metadata
Release files for ghosttrace 0.3.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ghosttrace-0.3.1.tar.gz | 9.2 kB | Without provenance | Details for ghosttrace-0.3.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ghosttrace-0.3.1-py3-none-any.whl | Python 3 | none | any | Details for ghosttrace-0.3.1-py3-none-any.whl |
Total release size: 18.9 kB
Release files / ghosttrace-0.3.1.tar.gz
| Download URL | ghosttrace-0.3.1.tar.gz |
|---|---|
| Size | 9.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1897af8c35e7ee6245c7ce626cde5da9b8bde4ea8c0d7e1dc3878ffb1af118fc
|
|
BLAKE2b-256 checksum How to use checksums |
147835c55ac464be4dade84796399584a7f6b388a35b03ca1dbac1f19db37649
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.0rc1
|
Release files / ghosttrace-0.3.1-py3-none-any.whl
| Download URL | ghosttrace-0.3.1-py3-none-any.whl |
|---|---|
| Size | 9.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d7f6f4c534e762f9108f2eba7676d2b71d717b0db131f20c9a74ed9bb318b18f
|
|
BLAKE2b-256 checksum How to use checksums |
87f01c99a5262df1d014ac1494881073a158958b9c705bbed3d8287bfcfd2796
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.0rc1
|
Security for ghosttrace 0.3.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.