Highlighter SDK
The Highlighter SDK Python library provides convenient access to the Highlighter API from applications written in Python. There is also a CLI to access the Highlighter API in your shell.
The library also provides other features. For example:
- Easy configuration for fast setup and use across multiple Highlighter accounts.
- Functions to help get datasets in and out of Highlighter
- Helpers for pagination.
See the SDK changelog for release notes and migration guidance.
Installation
pip install highlighter-sdk
API Tokens, Environment Variables and Profiles
If you have just a single set of Highlighter credentials you can simply set the appropriate environment variables.
export HL_WEB_GRAPHQL_ENDPOINT="https://<client-account>.highlighter.ai/graphql"
export HL_WEB_GRAPHQL_API_TOKEN="###"
# Only required if you have datasets stored outside Highlighter's managed
# aws s3 storage
export AWS_ACCESS_KEY_ID=###
export AWS_SECRET_ACCESS_KEY=###
export AWS_DEFAULT_REGION=###
If you have several Highlighter credentials we suggest you use the profiles option. Create a secure profile with the CLI:
hl profile create --name my-profile --api-token ### --endpoint-url https://...
Profile command documentation is available in
docs/profile-commands.md. In short:
- Use
hl profile ...to create, list, update, check, activate, delete, and securely migrate credential profiles. - Use
hl profile migrate-metadataandhl profile refreshonly for optional metadata on legacy YAML profile files.
If you're a Maverick Renegade you can manage the ~/.highlighter-profiles.yaml
manually. Below is an example,
# Example ~/.highlighter-profiles.yaml
my_profile:
endpoint_url: https://<client-account>.highlighter.ai/graphql
api_token: ###
# Only required if you have datasets stored outside Highlighter's managed
# aws s3 storage
cloud:
- type: aws-s3
aws_access_key_id: ###
aws_secret_access_key: ###
aws_default_region: ###
To use as a profile in the cli simply use,
hl --profile <profile-name> <command>
In a script you can use,
# in a script
from highlighter.client import HLClient
client = HLClient.from_profile("profile-name")
Additionally HLClient can be initialized using environment variables or
by passing credentials direcly
from highlighter.client import HLClient
client = HLClient.get_client()
# or
api_token = "###"
endpoint_url = "https://...highligher.ai/graphql
client = HLCient.from_credential(api_token, endpoint_url)
Finally, if you are in the position where you want to write a specified profile's
credentials to an evnironment file such as .env or .envrc you can use
the write command. This will create or append to the specified file.
hl --profile my-profile write .envrc
Python API
Once you have a HLClient object you can use it perform queries or mutations. Here is a simple example.
from highlighter.client import HLClient
from pydantic import BaseModel
client = HLClient.get_client()
# You don't always need to define your own BaseModels
# many common BaseModels are defined in highlighter.base_models
# this is simply for completeness
class ObjectClassType(BaseModel):
id: int
name: str
id = 1234 # add an object class id from you account
result = client.ObjectClass(
return_type=ObjectClassType,
id=id,
)
print(result)
Some queries may return arbitrarily many results. These queries are
paginated and are called Connections and the queries are named accordingly.
We have provided a paginate function to help with these Connections
from highlighter.core import paginate
from highlighter.client import HLClient
from pydantic import BaseModel
client = HLClient.get_client()
uuids = [
"abc123-abc123-abc123-abc123",
"xyz456-xyz456-xyz456-xyz456",
]
# The following BaseModels are all defined in
# highlighter.base_models. They are simply here
# for completeness
class PageInfo(BaseModel):
hasNextPage: bool
endCursor: Optional[str]
class ObjectClass(BaseModel):
id: str
uuid: str
name: str
class ObjectClassTypeConnection(BaseModel):
pageInfo: PageInfo
nodes: List[ObjectClass]
generator = paginate(
client.objectClasses,
ObjectClassTypeConnection,
uuid=uuids,
)
for object_class in generator:
print(object_class)
Datasets
Highlighter SDK provides a dataset representation that can populated
from several sources {HighlighterWeb.Assessments | Local files {.hdf, records.json, coco.json} | S3Bucket}.
Once populated the Highlighter.Datasets object contains 2 Pandas.DataFrames
(data_files_df and annotations_df) that you can manipulate as required. When you're
ready you can write to disk or upload to Highligher using one of the Writer classes
to dump your data to disk in a format that can be consumed by your downstream code.
If you need you can also roll-your-own Writer by implementing the highlighter.datasets.interfaces.IWriter interface.
Local SAM3 inference
hl sam3 infer segments local images with a text prompt using a local SAM3
checkpoint. It needs no Highlighter credentials. Install the runtime with
pip install 'highlighter-sdk[sam3]', or use nix-shell -A training or
nix-shell -A product in this repository. No checkpoint is downloaded, and
--device defaults to cuda with no CPU fallback.
hl sam3 infer --input ./images --output ./results --weights /path/to/sam3.pt --prompt cat
--input can be:
- a
.jpg,.jpegor.pngimage; - a directory, whose direct-child images are processed in filename order with frame IDs from 1;
- a workspace containing
evaluation/manifest.json, which takes precedence over loose images, e.g.{"examples": [{"frame_id": 9, "image_path": "evaluation/images/cat.jpg"}]}.
--output must be new or empty. It receives manifest.json (prompt, threshold,
per-image instances with scores and output-relative mask paths, and run
provenance), run_notes.md, and masks/frame_<id>/instance_<n>.png. Progress
goes to stderr (hidden by hl --quiet) and a JSON summary to stdout. A failed
run can leave partial masks; retry into a fresh output directory.
To send many images without reloading the model each time, keep it loaded with
hl sam3 serve and post images to it:
hl sam3 serve --weights /path/to/sam3.pt # prints "Serving SAM3 on http://127.0.0.1:8000"
curl --data-binary @cat.jpg "http://127.0.0.1:8000/infer?prompt=cat"
curl --data-binary @cat.jpg "http://127.0.0.1:8000/infer?prompt=cat&confidence_threshold=0.7"
confidence_threshold is optional and defaults to the server's
--confidence-threshold (0.5).
The response is JSON with prompt, confidence_threshold, image_size
([width, height]) and instances, each with a score and a base64
mask_png in the same format as infer's mask files. GET /health returns
{"status": "ok"} once the model is loaded. Requests are processed one at a
time. Errors are JSON {"error": ...} and the server keeps running.
The server is a local tool with no authentication, built on Python's
http.server, which is not meant for production. It listens on 127.0.0.1 by
default; to use it from another machine, tunnel with
ssh -L 8000:localhost:8000 <host> rather than exposing it with --host.
CLI Tab Completion
| Console | |
|---|---|
| Shell |
Add this to your ~/.bashrc:eval "$(_HL_COMPLETE=bash_source hl)" |
| ZSH |
Add this to your ~/.zshrc:eval "$(_HL_COMPLETE=zsh_source hl)" |
| Fish |
Add this to ~/.config/fish/completions/hl.fish:_HL_COMPLETE=fish_source hl | source
|
For more information, see the Click documentation
Documentation
1 maintainer
Metadata
1 maintainer
Release files for highlighter-sdk 2.6.95
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| highlighter_sdk-2.6.95.tar.gz | 1.9 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| highlighter_sdk-2.6.95-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 4.1 MB
Release files / highlighter_sdk-2.6.95.tar.gz
| Download URL | highlighter_sdk-2.6.95.tar.gz |
|---|---|
| Size | 1.9 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
34bf9a694f8f057ffe723f248f7fb873661d3ef1537763c998877ce2349b4f9d
|
|
BLAKE2b-256 checksum How to use checksums |
6a77a6a7416297548c44d93823c766c3fc5129f8ed329b274fab87d741753e85
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
Hatch/1.16.5 cpython/3.13.15 HTTPX/0.28.1
|
Release files / highlighter_sdk-2.6.95-py3-none-any.whl
| Download URL | highlighter_sdk-2.6.95-py3-none-any.whl |
|---|---|
| Size | 2.2 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1bb2eff1b2e40c27f2fe82b473cc8247dc036f3b9fc60376228f5e091871f54c
|
|
BLAKE2b-256 checksum How to use checksums |
d27c2b028dbb97f79421734cf1c8e1d8e795c23471d1995425dabafb9161330e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
Hatch/1.16.5 cpython/3.13.15 HTTPX/0.28.1
|
