Skip to main content

trickle-observe

Runtime type annotations for Python — see tensor shapes, variable types, and crash-time values as you code.

pip install trickle-observe

Quick Start

Scripts

pip install trickle-observe
npm install -g trickle-cli

trickle run python train.py     # run with tracing
trickle hints                   # view source with inline types
trickle hints --errors          # crash-time values + error underline

Jupyter Notebooks

%load_ext trickle               # first cell, then run your code

Types appear inline in VSCode immediately after each cell runs.

What You See

Every variable gets its runtime type visible — in VSCode or in the terminal:

def forward(self, x: Tensor[128, 2] float32):
    x: Tensor[128, 256] float32 = self.relu(self.bn0(self.embed(x)))
    x: Tensor[128, 16, 16] float32 = x.view(x.size(0), 16, 16)
    x: Tensor[128, 32, 16] float32 = self.relu(self.bn1(self.conv1(x)))

When code crashes, see exactly what each variable held:

# train.py — ERROR
# ValueError: could not convert string to float: 'ID' (line 20)
file_path: string = "demographics.txt"
patient_gait_data: string[] = ["ID\tStudy\tGroup\t..."]
    [float(d) for d in time.split('\t')] for time in patient_gait_data
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~  <- ValueError: ...

Usage

pip install trickle-observe
npm install -g trickle-cli

trickle run python your_script.py
trickle hints your_script.py

As a library

import trickle

# Wrap individual functions
@trickle.trickle
def process(data):
    ...

# Instrument a FastAPI/Flask/Django app
trickle.instrument(app)

# Universal observation — wrap all functions on a module
trickle.observe(my_module)

In Jupyter Notebooks

%load_ext trickle

All cells after this are traced. The VSCode extension shows inline type hints.

With pytest

trickle run pytest tests/

What Gets Traced

  • Tensor shapes — PyTorch (shape, dtype, device, memory, gradient norms), MLX (shape, dtype, memory), NumPy, pandas
  • All variable assignments — simple, for-loops, function parameters, tuple unpacking, with-as
  • Imported modules — your local modules are traced too, not just the entry file
  • Error snapshots — all variables at crash time, including list comprehension scopes

Supported Frameworks

  • ML: PyTorch, MLX, NumPy, pandas, scikit-learn, HuggingFace
  • Web: FastAPI, Flask, Django, Litestar
  • LLM: OpenAI, Anthropic, Google Gemini, LangChain, CrewAI

How It Works

Trickle rewrites your Python source via AST transformation before execution. After every variable assignment, it inserts a lightweight call that captures the type and a sample value, then writes to .trickle/variables.jsonl.

Only your code is traced — stdlib, site-packages, torch/numpy internals are skipped. No code changes to your files. No decorators required.

Package Description
trickle-cli CLI for trickle run and trickle hints
trickle-vscode VSCode extension for inline type hints

License

Apache-2.0

Metadata

Release files for trickle-observe 0.2.71

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for trickle-observe 0.2.71
File Size Uploaded Provenance Actions
trickle_observe-0.2.71.tar.gz 156.0 kB Without provenance Details for trickle_observe-0.2.71.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for trickle-observe 0.2.71
File Interpreter ABI Platform Actions
trickle_observe-0.2.71-py3-none-any.whl Python 3 none any Details for trickle_observe-0.2.71-py3-none-any.whl

Total release size: 336.5 kB

Release files / trickle_observe-0.2.71.tar.gz

Download URL trickle_observe-0.2.71.tar.gz
Size 156.0 kB
Tags Source
SHA-256 checksum
How to use checksums
5f910f86d83b08e7d5e3cd477849044ca447221a1b8d530d2ea6eaedb947e700
BLAKE2b-256 checksum
How to use checksums
b9e6ace798cd133936ac8b4b6b7b2ad1b288e42954322deec418075752e6cbb1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.2

Release files / trickle_observe-0.2.71-py3-none-any.whl

Download URL trickle_observe-0.2.71-py3-none-any.whl
Size 180.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d00d11e2992b734601a2bfb0cae5ab9a73098a22088c1167cd2ab7355c6c0a03
BLAKE2b-256 checksum
How to use checksums
3ae1e600c7c12317d0e4a0c1a1e16d6a6fa958756f65f93de02457371f9f434b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.2

Security for trickle-observe 0.2.71

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.

Release history Release notifications | RSS feed

This release

0.2.71 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page