Skip to main content

bocconcini

tests

Use it for: documents and prompts on local LLMs with a genuinely small context - Android/Termux, Raspberry Pi, old laptops, air-gapped machines.

Zero runtime dependencies. A Python client for local LLMs whose usable window is smaller than the advertised one. Born on a Samsung S20 Ultra in Termux, built to never lie about what it did.

The problem

A local model advertises 8k context but stops understanding around 2k. Long documents get silently truncated, compressed into summaries that delete the answer, or split in the middle of a string. You ask for a code buried in a log and the model invents one - because the pipeline removed it before the model ever saw it.

bocconcini fixes the pipeline, not the model:

  • Measures the real usable window instead of trusting the advertised one.
  • Refuses instead of silently degrading - no quiet loss of the middle.
  • Scans long documents deterministically, then sends the model only the sentences that matter.

Why "bocconcini"? A child, a huge cake, a small mouth: STORIA.md. Italian edition: README.it.md.

Verification status

  • Verified live: KoboldCpp, Samsung S20 Ultra, smol-tools-4b.
  • Implemented but NOT verified live: llama.cpp native, Ollama, cloud.
  • 43 checks: python test_bocconcini.py and python test_regressioni.py.

What it does

  • Chunks text / Python / JSON, never inside a string or an escape sequence.
  • Output budget from the context window, not from generation speed.
  • Cognitive window: client.calibra() measures how much the model actually understands, not how much the server can hold. Only a passed probe is stored.
  • Detects silent prompt truncation, and only near the window: far from it a shortfall is our own estimate, not a cut.
  • Continues answers cut by the token limit, stitching without duplicates.
  • Disk-backed tree: DocTree, naviga, albero_codice (lossless AST partition).
  • trova_fatti: deterministic scan for codes / IDs / measurements / keys, each with its surrounding sentence.

Some public names are Italian (trova_fatti, contesto, invia_adattivo). They are kept as-is for compatibility.

Install

Python 3.7+. No runtime dependencies. On PyPI.

pip install bocconcini

Offline / Termux — no pip, no build, two files:

curl -O https://raw.githubusercontent.com/MalgTruevero/bocconcini_crunch/main/bocconcini.py
curl -O https://raw.githubusercontent.com/MalgTruevero/bocconcini_crunch/main/bocconcini_tree.py

First result — no model, no server

from bocconcini_tree import trova_fatti
doc = "filler " * 4000 + "The unlock code is ALFA-1." + "filler " * 4000
print(trova_fatti(doc))

Python reads every character and returns the code with its sentence. This is the mechanism that found 4/4 hidden codes in 52 s where blind compression found 0/4 in 42 min, on a Samsung S20 Ultra with a 4B model.

Reproduce it:

python benchmark_tank.py --no-model   # scan only, no server, milliseconds
python benchmark_tank.py              # scan + one model call

Exits 1 if a needle is missed.

Reproduce it:

python benchmark_tank.py --no-model   # scan only, no server, milliseconds
python benchmark_tank.py              # scan + one model call

Exits 1 if a needle is missed.

With a local server

Needs a running llama.cpp / KoboldCpp server. Verified live: KoboldCpp only.

from bocconcini import LlamaCppClient
cl = LlamaCppClient("http://127.0.0.1:5001")
print(cl.chat("Answer with one word: ok"))

Ollama and OpenAI-compatible cloud paths are implemented but not verified live.

Finding facts without blind compression

from bocconcini_tree import trova_fatti
facts = trova_fatti(document)      # reads every character, no model call
context = "\n".join(f["contesto"] for f in facts)

Measured on the reference phone, 4 codes hidden in 32,000 characters: blind compression 0/4 in 2562 s; trova_fatti 4/4 in 52 s, ~265 prompt tokens instead of ~10923.

auto_reduce=True is lossy: it can discard the middle of a document. To find facts, use trova_fatti or explicit chunking.

License

MIT. Keeping the name and the story is a courtesy, not a requirement.

The name

"BOCCONCINI" reads like mozzarella to an English speaker. It is not: it means small bites. If you fork and republish, please carry STORIA.md along — a courtesy, not a licence requirement.

Metadata

Release files for bocconcini 4.3.1

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

Source distribution (sdist)

Source distribution for bocconcini 4.3.1
File Size Uploaded Provenance Actions
bocconcini-4.3.1.tar.gz 52.6 kB With provenance Details for bocconcini-4.3.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for bocconcini 4.3.1
File Interpreter ABI Platform Actions
bocconcini-4.3.1-py3-none-any.whl Python 3 none any Details for bocconcini-4.3.1-py3-none-any.whl

Total release size: 106.2 kB

Release files / bocconcini-4.3.1.tar.gz

Download URL bocconcini-4.3.1.tar.gz
Size 52.6 kB
Tags Source
SHA-256 checksum
How to use checksums
4251ee407a760f4c6737b9cd288632b2073d3b045483b2c10a75b1948d439633
BLAKE2b-256 checksum
How to use checksums
22a3f3eb3d51d4a4a0a913c3f879815c772ea5a149196311a5e35e5df17f4c0e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / bocconcini-4.3.1-py3-none-any.whl

Download URL bocconcini-4.3.1-py3-none-any.whl
Size 53.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7e90295620f89cc06bf36c454733f4b1416886788861c0a90c1baacfe47a3dcf
BLAKE2b-256 checksum
How to use checksums
4da366bc3a28e6441c3ccdd909d14bde1f16e62ee4b9606c6bdfb2a5040aed90
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Security for bocconcini 4.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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for bocconcini-4.3.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

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

4.3.1 This release

2 release files Full 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