Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 37 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -22,3 +22,40 @@ jobs:
- name: WebAssembly build
working-directory: app
run: cargo build --release -p titler-wasm --target wasm32-unknown-unknown

bindings:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: dtolnay/rust-toolchain@stable
with:
targets: wasm32-unknown-unknown
- uses: Swatinem/rust-cache@v2
with:
workspaces: app
- uses: taiki-e/install-action@v2
with:
tool: wasm-pack
- uses: actions/setup-node@v4
with:
node-version: 22
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- name: Rust API tests
working-directory: app
run: cargo test --release -p titler
- name: C API smoke test
working-directory: app
run: ./capi/tests/run-smoke.sh
- name: Python package tests
working-directory: app/python
run: |
pip install pytest
TITLER_LIB="$GITHUB_WORKSPACE/app/target/release/libtitler_c.so" python -m pytest tests -q
- name: npm package tests
working-directory: app
run: |
wasm-pack build wasm --target web --release --out-dir ../npm/pkg --out-name titler_wasm
cp model/titler-v3-q4_k_m.gguf npm/titler.gguf
cd npm && npm test
70 changes: 70 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -32,3 +32,73 @@ jobs:
- uses: softprops/action-gh-release@v2
with:
files: titler-${{ matrix.name }}*

libraries:
strategy:
fail-fast: false
matrix:
include:
- { os: ubuntu-latest, name: linux-x86_64 }
- { os: windows-latest, name: windows-x86_64 }
- { os: macos-latest, name: macos-arm64 }
runs-on: ${{ matrix.os }}
steps:
- uses: actions/checkout@v4
- uses: dtolnay/rust-toolchain@stable
- uses: Swatinem/rust-cache@v2
with:
workspaces: app
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- name: Build the C library
working-directory: app
run: cargo build --release -p titler-capi
- name: Zip the C library with its header
shell: bash
working-directory: app
run: |
files="capi/include/titler.h"
for f in target/release/titler_c.dll target/release/titler_c.dll.lib target/release/titler_c.lib target/release/libtitler_c.so target/release/libtitler_c.dylib target/release/libtitler_c.a; do
[ -f "$f" ] && files="$files $f"
done
python -m zipfile -c "../titler-capi-${{ matrix.name }}.zip" $files
- name: Build the Python wheel
shell: bash
working-directory: app/python
run: |
pip install build wheel setuptools
python build_wheel.py
cp dist/*.whl ../..
- uses: softprops/action-gh-release@v2
with:
files: |
titler-capi-${{ matrix.name }}.zip
titler-*.whl

npm-and-model:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: dtolnay/rust-toolchain@stable
with:
targets: wasm32-unknown-unknown
- uses: Swatinem/rust-cache@v2
with:
workspaces: app
- uses: taiki-e/install-action@v2
with:
tool: wasm-pack
- name: Build the npm package
working-directory: app
run: |
wasm-pack build wasm --target web --release --out-dir ../npm/pkg --out-name titler_wasm
cp model/titler-v3-q4_k_m.gguf npm/titler.gguf
cd npm && npm pack
cp titler-wasm-*.tgz ../..
cp ../model/titler-v3-q4_k_m.gguf ../../titler-v3-q4_k_m.gguf
- uses: softprops/action-gh-release@v2
with:
files: |
titler-wasm-*.tgz
titler-v3-q4_k_m.gguf
9 changes: 9 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -32,3 +32,12 @@ node_modules/
# Rust build output
app/target/
app/website/dist/
app/npm/pkg/
app/npm/titler.gguf
app/python/dist/
app/python/build/
app/python/*.egg-info/
app/python/titler/*.dll
app/python/titler/*.so
app/python/titler/*.dylib
app/python/titler/*.gguf
21 changes: 21 additions & 0 deletions LICENSE
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
MIT License

Copyright (c) 2026 Cyrus Attoun

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
9 changes: 8 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,13 @@
# titler

A tiny T5 model that turns a prompt into a short title.
A tiny model that turns a prompt into a short title.

> **New: titler v2** is a standard Llama-architecture GGUF (5.8M parameters, **4 MB**) that runs on the CPU in 15-100 ms. It wins about
> 65% of the head-to-head pairs against the v1.5 model described below.
> Try it in your browser: **https://cyronius.github.io/titler/** (runs locally with WebAssembly, nothing is sent anywhere).
> Use it in your own app (Rust, C, Python, JavaScript, command line): [app/EMBEDDING.md](app/EMBEDDING.md).
> Code and model: [app/](app/). Training and evaluation scripts are in [scripts/](scripts/). The sections below describe v1.5.


**7.6M parameters · 10.3 MB int8 ONNX · CPU-only · browser / Node / Python**

Expand Down
15 changes: 15 additions & 0 deletions app/Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion app/Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[workspace]
resolver = "2"
members = ["core", "cpu", "llama", "cli", "wasm"]
members = ["core", "cpu", "titler", "llama", "cli", "wasm", "capi"]

[workspace.package]
version = "0.1.0"
Expand Down
91 changes: 91 additions & 0 deletions app/EMBEDDING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
# Use titler in your app

titler turns a prompt into a short title (8 words at most). The model is one 4 MB file. It runs on the CPU, offline,
with no telemetry. Pick the way that fits your app:

| Your app is | Use | Install |
|---|---|---|
| Rust | the `titler` crate | `titler = { git = "https://github.com/Cyronius/titler" }` |
| C, C++, C#, Go, Swift, Java (anything that loads a DLL) | the C library | `titler-capi-<platform>.zip` from the [releases](https://github.com/Cyronius/titler/releases) |
| Python | the `titler` wheel | `pip install titler-0.1.0-py3-none-<platform>.whl` from the releases |
| A web page or Node | `titler-wasm` | `npm install titler-wasm-0.1.0.tgz` from the releases |
| A script or shell | the `titler` command | `titler-<platform>` from the releases |

The model file is `titler-v3-q4_k_m.gguf` in each release and in `app/model/`. The wheel, the npm package and the
command-line tool already contain it.

## Rust

```rust
let titler = titler::Titler::from_path("titler-v3-q4_k_m.gguf")?; // load once
let title = titler.title("how do I sort a list of dicts by a key in python")?;
```

`Titler` is `Send + Sync`. Share one between threads (in an `Arc`); `title` takes `&self`. `title_with_beams(prompt, 1)` is
the fast setting. For a faster native build, use `titler-llama` (llama.cpp, needs a C++ compiler) in place of `titler`.

## C and everything that can call C

Header: `capi/include/titler.h`. Library: `titler_c.dll`, `libtitler_c.so` or `libtitler_c.dylib` (and a static library).

```c
titler_t *t = titler_new_from_file("titler-v3-q4_k_m.gguf");
char out[256];
int64_t n = titler_title(t, "how do I sort a list of dicts by a key in python", 0 /* default beams */, out, sizeof out);
if (n < 0) fprintf(stderr, "%s\n", titler_last_error());
titler_free(t);
```

- Strings are UTF-8. A 256-byte buffer holds any title. The return value is the full length; if it is `cap` or more, the title was cut.
- `titler_title` can be called from many threads at once on one handle. Free the handle only when no call is running.
- Errors return NULL or -1. The message is in `titler_last_error()` for the calling thread.
- C#: `[DllImport("titler_c")]` with the same signatures. Go: cgo or `purego`. Both call plain C functions.

## Python

```python
from titler import Titler
t = Titler() # the model inside the wheel; or Titler("path.gguf")
print(t.title("how do I sort a list of dicts by a key in python"))
```

A `Titler` can be shared between threads. The wheel is built per platform (the C library is inside it).

## Web and Node

```js
import { createTitler } from "titler-wasm";
const titler = await createTitler(); // loads the 4 MB model
titler.title("how do I sort a list of dicts by a key in python");
```

In a browser, run it in a Web Worker so the page does not freeze; `website/worker.js` is a complete example.
Host `pkg/titler_wasm_bg.wasm` and `titler.gguf` as static files next to your script.

## What you get

| | |
|---|---|
| Output | 3 to 8 words in Title Case, for example `Sorting Dicts By Key in Python`. Same input, same output. |
| Input | Any text. Only the first 256 tokens (about 1,000 characters of English) are read. English only: other languages are not supported. |
| Speed, 4 beams | Native Rust (one thread): median 40-70 ms, slowest 5% 200-275 ms (long prompts). llama.cpp: 18 ms / 48 ms. Browser: 50-175 ms. |
| Speed, 1 beam | About half of that, with slightly worse titles. |
| Memory | About 25 MB after loading (weights are held as 32-bit numbers). Load time about 30 ms. |
| Quality | Judged against the previous titler (v1.5): the new titles win about 65% of the pairs that have a winner. |
| Beams | 4 is the default the model was judged with. The maximum is 8. |

## Limits

- It titles; it does not summarize, translate or answer.
- It sometimes drops an apostrophe (`Nick Wildes Judy Hopp Dialog Line`). Weak inputs are vague one-liners and pasted logs.
- The training data and its licenses are listed in `model/NOTICE.md`.

## Build from source

```
cd app
cargo build --release -p titler-capi # C library -> target/release/
cargo build --release -p titler-cli # command-line tool
python python/build_wheel.py # Python wheel (from app/python)
npm/build.sh # npm package (needs wasm-bindgen-cli, see README.md)
```
6 changes: 6 additions & 0 deletions app/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,19 @@ A 4 MB model that turns a prompt into a short title. It runs on the CPU in about
| Folder | Content |
|---|---|
| `core/` | Tokenizer, beam search, title cleanup. No I/O. The model side is a `Backend` trait. |
| `titler/` | The `titler` crate: load a model, call `title`. Shares one model between threads. |
| `capi/` | C library and `include/titler.h`. |
| `python/` | Python package (ctypes over the C library) and wheel builder. |
| `npm/` | The `titler-wasm` npm package. |
| `cpu/` | `Backend` in plain Rust (no C++, no dependencies). It runs in the browser. |
| `llama/` | `Backend` for llama.cpp (through `llama-cpp-2`). Faster on a desktop. |
| `cli/` | The `titler` command. The model is built into the binary. |
| `wasm/` | WebAssembly wrapper around `core` and `cpu`. |
| `website/` | The demo page. `build-site.sh` builds it into `website/dist/`. |
| `model/` | The shipped GGUF (Q4_K_M, 5.84M parameters) and `NOTICE.md` (data licenses). |

To use titler in your own app (Rust, C, Python, JavaScript), see [EMBEDDING.md](EMBEDDING.md).

## Use

```
Expand Down
Empty file modified app/build-site.sh
100644 → 100755
Empty file.
13 changes: 13 additions & 0 deletions app/capi/Cargo.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
[package]
name = "titler-capi"
description = "C interface to titler (include/titler.h)"
version.workspace = true
edition.workspace = true
license.workspace = true

[lib]
name = "titler_c"
crate-type = ["cdylib", "staticlib", "rlib"]

[dependencies]
titler = { path = "../titler" }
53 changes: 53 additions & 0 deletions app/capi/include/titler.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
/* titler: short titles for prompts, from a 4 MB model that runs on the CPU.
*
* Load the model once with titler_new_*, then call titler_title from any number of threads at the same time.
* Strings are UTF-8. Functions that can fail return NULL or -1 and set a message for titler_last_error().
*/
#ifndef TITLER_H
#define TITLER_H

#include <stddef.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

#if defined(_WIN32) && defined(TITLER_DLL_IMPORT)
#define TITLER_API __declspec(dllimport)
#else
#define TITLER_API
#endif

typedef struct TitlerHandle titler_t;

/* Load the model from a GGUF file. Returns NULL on error. */
TITLER_API titler_t *titler_new_from_file(const char *path);

/* Load the model from GGUF bytes already in memory. The bytes are copied; free them afterwards if you like. */
TITLER_API titler_t *titler_new_from_memory(const uint8_t *data, size_t len);

/* Free a handle. NULL is fine. Do not use the handle afterwards, and do not free it while another thread uses it. */
TITLER_API void titler_free(titler_t *t);

/* Write the title for a NUL-terminated prompt into out (at most cap bytes, including the NUL).
* beams: 4 is the default (use 0 or less for it); 1 is fastest; the maximum is 8.
* Returns the full length of the title in bytes, not counting the NUL, or -1 on error.
* If the return value is cap or more, the title was cut short at a character boundary. A buffer of 256 bytes is enough
* for any title (8 words). Invalid UTF-8 in the prompt is replaced, not rejected. */
TITLER_API int64_t titler_title(const titler_t *t, const char *prompt, int beams, char *out, size_t cap);

/* Same, for a prompt that is not NUL-terminated or contains NUL bytes. */
TITLER_API int64_t titler_title_n(const titler_t *t, const uint8_t *prompt, size_t len, int beams, char *out, size_t cap);

/* The message for the last failure on the calling thread. Valid until the next titler call on this thread. */
TITLER_API const char *titler_last_error(void);

/* Library version, for example "0.1.0". */
TITLER_API const char *titler_version(void);

#ifdef __cplusplus
}
#endif

#endif
Loading
Loading