No project description provided
Project description
Impulse
This is a minimalist (but powerful) tracing framework for building Python applications, particularly those involving LLMs and AI features. We built this while refining LLM applications to be production-ready, and we didn't want to commit to opinionated, lock-in frameworks from other solution providers. We will pull more features from our stack into this if there is interest. Feel free to file issues or provide feedback: sudowoodo200 [at] gmail [dot] com.
Quickstart
Installation
- Install from PyPI:
pip install impulse_core
- Direct install:
make install
. Note that this is not an editable installation
Usage
This initializes the objects with default settings
tracer
will use aLocalLogger
, which writes json records to a file at.impulselogs/logs_{timestamp}.json
- Currently, this supports logging to a MongoDB database out of the box.
tracer.hook()
will be set to the default thread at"default"
from impulse_core import ImpulseTracer
tracer = ImpulseTracer()
@tracer.hook()
def some_function(x: int, y: str = 2) -> str:
return f"{str(x)} - {y}"
some_function(1)
tracer.shutdown() ## needed for local logger to flush the write buffer
The record will capture information (under the "payload"
field of the json record) during the call:
{
"function": {
"name" : "some_function",
...
},
"call_id": "asfda2323-52sdfasd",
"timestamps": {
"start": "2023-08-20 22:05:55.000000",
"end": "2023-08-20 22:05:56.123456",
"start_to_end_seconds": "1.123456"
},
"arguments": {
"x": 1,
"y": 2
},
"status": "success",
"output": "1 - 2",
...
}
This works with functions, methods, classmethods, staticmethods, coroutines, and async generators. If an exception occurs, logging will still happen.
You can trace nested calls by decorating the relevant functions. For instance:
@tracer.hook()
def top_level():
return intermediate()
def intermediate():
return some_function(1,1)
The log records will preserve the parent-child relationship between some_function(x,y)
and top_level()
in the stack_trace
field. For instance, this will be captured in the top_level()
's record:
{
"function": {
"name" : "top_level",
...
},
"call_id": "asdfasdf-2352dsafsa",
...
"stack_trace": {
"parents": [
...
],
"children": [
{
"fn_name": "some_function",
"call_id": "asfda2323-52sdfasd" ,
"trace_module": { ... }
},
]
}
...
}
{
"function": {
"name" : "some_function",
...
},
"call_id": "asfda2323-52sdfasd",
...
"stack_trace": {
"parents": [
{
"fn_name": "top_level",
"call_id": "asdfasdf-2352dsafsa",
"trace_module": { ... }
},
],
"children": [
...
]
}
// ...
}
Each @trace.hook()
creates a context until superceded by a nested hook. A simple by powerful feature is the ability to log arbitrary data, timestamped, directly into the context, which is then included as part of the enclosing logging record. The only restriction is that it must be convertible with json.dumps
.
from impulse_core import trace_log as log
@tracer.hook()
def some_function(x: int, y: str = 2) -> str:
log("The ents shall march to")
log({"location": "Isengard"})
return f"{str(x)} - {y}"
These can be accessed in the "trace_log"
field of the record.
{
"function": {
"name" : "some_function",
...
},
...
"trace_log": [
{
"timestamp": "2023-08-20 22:05:55.000511",
"payload": "The ents shall march to"
},
...
]
}
Common use cases include capturing session data when serving web requests and doing more granular logging of function components.
Tutorial
Apologies for the lack of docs for now. Still drafting it. In its place, a quick tutorial can be found at tutorial/tutorial.ipynb
. To get started, use the following to boot up a virtual env with a local mongo-db instance.
make tutorial
After you are done, clean up the tutorial assets with
make shutdown-tutorial
Logging Schema
Detailed overview of the logging schema can be found at impulse_core/schema.py
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for impulse_core-0.1.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d9ca4472f9cbaeca4a3131ac48679e39c920fcc78bb15d626e08986fe5102dc0 |
|
MD5 | 77e735818418bc5ada94d3683ad939f0 |
|
BLAKE2b-256 | aa6835574f88c31a21843456d107e9abdf2ca0b16739b3293ede400178bc9a6d |