Skip to content

Theseus User Guide

Theseus is a two-layer toolchain for working with OSS package metadata.

Layer 1 normalizes package recipes from Nixpkgs, PyPI, and npm into a shared canonical JSON schema, then ranks and extracts the most important candidates. FreeBSD Ports is also supported as a build recipe source — its 20,000+ port Makefiles complement Nixpkgs.

Layer 2 provides 2,295 machine-readable behavioral specs — one per OSS library — that are verified against the real installed library on macOS and Linux. 1,091 of them target npm packages; the corpus totals 16,683 invariants. ctypes-backed specs include libpcap and pcapng (35 invariants together, all derived from IETF drafts).

Covered library index

The Z-layer covers 2,295 compiled specs (one per source .zsdl file). The full sorted list is below — click to expand.

Show full list of covered libraries (2,295 entries) 
_bisect
_csv
_datetime
_decimal
_hashlib
_heapq
_io
_json
_pickle
_socket
_ssl
_struct
_thread
_weakref
abbrev
abbreviate_number
abc
abc_meta
accepts
accounting
acorn
acorn_walk
aes_js
agent_base
aggregate_error
aifc
aiocache_rust
aiohttp_rust
aiomysql_rust
aiopg_rust
aioredis_rust
aiosignal_rust
ajv
alembic_rust
alphanum_sort
annotated_types_rust
ansi_colors
ansi_regex
ansi_styles
ansible_rust
antigravity
anyio_extra_rust
anyio_rust
anymatch
apscheduler_rust
arch
arg
argparse
argparse_extra_rust
argparse_formatters
ariadne_rust
arithmetic
arr_diff
arr_flatten
arr_union
array
array_chunk
array_chunkify
array_compact
array_contains
array_differ
array_difference
array_extra_rust
array_first
array_flatten
array_flatten2
array_has
array_head
array_includes
array_intersection
array_last
array_move
array_range
array_rust
array_slice
array_sort
array_sum
array_union
array_uniq
array_unique
array_without
array_zip
arrify
arrow_extra_rust
arrow_time_rust
ast
ast_extra_rust
ast_rust
async_mutex
async_retry
async_timeout_rust
asynchat
asyncio
asyncio_events
asyncio_extra_rust
asyncore
asyncpg_rust
atexit
attrs
attrs_rust
audioop
authlib_rust
autopep8_rust
azure_identity_rust
babel_parser
babel_rust
backoff_rust
balanced_match
bandit_rust
base_62
base_64
base_x
base32_decode
base64
base64_js
base64_rust
bcrypt_rust
bcryptjs
bdb
beartype_rust
beautifulsoup4_rust
bezier_easing
bidict_rust
big_js
bignumber_js
binary_to_decimal
binaryextensions
binascii
binascii_rust
bisect
bisect_extra_rust
bisect_rust
bit_twiddle
black_rust
boltons_rust
boto3_rust
bottle_rust
bottleneck
box_rust
boxen
brace_expansion
braces
broadcaster_rust
bson
buffer_from
build_rust
builtins
builtins_rust
bytes
bytes_methods_rust
bz2
bz2_rust
cachelib_rust
cachetools_rust
calendar
calendar_extra_rust
calendar_rust
camel_case
camelcase
camelcase_keys
camelize
capital_case
card_validator
cartesian_product
case
cassandra_driver_rust
castarray
catboost_rust
cattrs_rust
cbor
ccount
celery_rust
cerberus_rust
certifi
certifi_rust
cffi_rust
cgi
cgitb
chalk
change_case
chardet
chardet_rust
charset_normalizer
charset_normalizer_extra_rust
charset_normalizer_rust
check_types
cheerio
cherrypy_rust
chokidar
chroma_js
chrono_node
chunk
chunk_array
cidr_tools
circular_json
clamp
clamp_number
classnames
cli_cursor
cli_progress
cli_spinners
cli_table3
cli_truncate
cli_width
click
click_ansi_rust
click_extra_rust
click_extra2_rust
cliui
clone_deep
clsx
cmath
cmath_rust
cmd
code
codecs
codecs_rust
codeop
collapse_white_space
collections
collections_abc
collections_deque_rust
collections_extra_rust
collections_namedtuple
collections_ordereddict
collections_rust
color
color_convert
color_name
color_parse
color_rgba
color_string
color_support
colorama
colorama_rust
colorette
colornames
colorsys
colorsys_rust
combinations
comma_separated_tokens
command_exists
commander
commitizen_rust
common_prefix
compare_versions
compileall
compute_gcd
compute_lcm
compute_max
compute_mean
compute_min
compute_range
compute_sum
compute_variance
concurrent_extra_rust
concurrent_futures
conda_rust
config_rust
configparser
configparser_rust
consola
constant_case
construct_rust
contains_emoji
content_disposition
content_type
contextlib
contextlib_extra_rust
contextlib_rust
contextlib_suppress
contextvars
convert_units
cookie
cookie_signature
copy
copy_extra_rust
copy_rust
copyreg
counter_extra_rust
countries_and_timezones
country_list
coverage_rust
cProfile
crc
crc_32
crc32
credit_card_type
cron_parser
croniter_rust
cronstrue
cross_spawn
crypt
crypto_js
crypto_random_string
cryptography_extra_rust
cryptography_rust
css_selector_parser
css_tree
css_what
csv
csv_extra_rust
csv_parse
csv_rust
csv_stringify
ctypes
ctypes_extra_rust
ctypes_extra2_rust
ctypes_module
curl
currency_codes
currency_js
currency_symbol_map
curses
curses_ascii
cv2_rust
cx_oracle_rust
cython_extra_rust
d3_array
d3_color
d3_format
d3_geo
d3_interpolate
d3_scale
d3_time_format
dacite_rust
dask_rust
databases_extra_rust
databases_rust
dataclasses
dataclasses_extra_rust
dataclasses_field
dataclasses_json_rust
dataclasses_rust
dataloader
date_fns
datetime
datetime_date_rust
datetime_extra_rust
datetime_rust
datetime_timedelta
datetime_timedelta_rust
dateutil_rust
dayjs
dbm
debug
decamelize
decimal
decimal_js
decimal_rust
decimal_to_binary
decode_named_character_reference
decode_uri_component
decorator
decorator_rust
dedent
deep_diff
deep_equal
deep_extend
deep_get_set
deep_object_assign
deep_object_diff
deepmerge
deepmerge_rust
default_compare
defaults_deep
defu
defusedxml
delaunator
delay
demjson3_rust
depd
dequal
destr
detect_indent
detect_libc
detect_newline
devalue
diacritics
dice_coefficient
diff
diff_match_patch
difflib
difflib_extra_rust
difflib_rust
dill_rust
direction
dirhash_rust
dis
dis_extra_rust
diskcache_rust
distro
django_channels_rust
django_rust
djb2
dlv
dns
dns_packet
dnspython_rust
docker_rust
docopt_rust
doctest
docutils
dom_serializer
domhandler
domutils
dot_case
dot_object
dot_prop
dotenv
dotenv_defaults
dotenv_expand
drf_rust
duckdb_rust
dynaconf_rust
easing_utils
ejs
elasticsearch_rust
elementtree
email_charset
email_encoders
email_errors
email_header
email_message
email_mime
email_policy
email_utils
email_utils_rust
email_validator
email_validator_rust
emittery
emoji_regex
emoji_rust
emoji_strip
encodeurl
end_of_stream
ensure_array
ensurepip
entities
enum
enum_extra_rust
enum_flags
enum_rust
env_paths
environs_rust
errno
errno_extra_rust
errno_rust
es6_error
esbuild
escape_goat
escape_html
escape_string_regexp
espree
estraverse
eta
etag
eventemitter3
exceptiongroup_rust
execa
expand_tilde
expat
exponential_backoff
express
exrex_rust
extract_domain
fabric_rust
factorial
factory_boy_rust
faker_rust
falcon_rust
fast_content_type_parse
fast_deep_equal
fast_diff
fast_equals
fast_fifo
fast_glob
fast_json_parse
fast_json_stable_stringify
fast_jwt
fast_levenshtein
fast_querystring
fast_redact
fast_uri
fast_xml_parser
fastapi_rust
fastest_levenshtein
fastest_validator
fastq
faulthandler
fcntl
fflate
fft_js
figlet
figures
file_type
filecmp
fileinput
filelock
filenamify
filesize
fill_range
filter_obj
find_up
fire_rust
flake8_rust
flask_rust
flat
flatley
flatted
flatten_array
flatten_rust
flit_rust
fnmatch
fnmatch_extra_rust
fnmatch_rust
fnv_plus
fnv1a
fontTools
format_rust
formatter
forwarded
fp_ts_option
fraction_js
fractions
fractions_rust
franc_min
freezegun_rust
fresh
front_matter
frozenlist_rust
fs_extra
fs_jetpack
fsspec
ftplib
functools
functools_extra_rust
functools_lru
functools_rust
furl_rust
future
fuzzy
fuzzysort
gc
gc_extra_rust
genericpath
gensim_rust
geographiclib_geodesic
geolib
get_nested_value
get_stream
get_value
getopt
getpass
gettext
gevent_rust
gino_rust
github_slugger
glob
glob_escape_rust
glob_extra_rust
globby
glom_rust
google_auth_rust
got
graceful_fs
graphene_rust
graphlib
graphql
graphql_tag
gray_matter
grp
grpc_rust
gunicorn_rust
gzip
gzip_rust
h11_rust
handlebars
hapi_hoek
has_own_prop
has_property
has_symbols
has_value
hash_sum
hashlib
hashlib_rust
hashlru
hast_util_to_html
hatch_rust
haversine_distance
he
header_case
heapq
heapq_extra_rust
heapq_rust
hex_rgb
hex_to_rgb
highlight_js
hmac
hmac_rust
hsl_to_hex
html
html_entities
html_entities_rust
html_escape_rust
html_parser
html_rust
html_tags
html_to_text
htmlentities
htmlparser2
htmlspecialchars
http_cache_semantics
http_client
http_cookiejar
http_cookies
http_cookies_rust
http_errors
http_proxy_agent
http_rust
http_server
http_server_handlers
http_status
http_status_codes
httpcore_rust
httpretty_rust
https_proxy_agent
httptools_rust
httpx_extra_rust
httpx_rust
human_id
humanize_duration
humanize_plus
humanize_rust
humanize_string
hyperid
hypothesis_rust
iarna_toml
iban
iconv_lite
idna
idna_extra_rust
idna_rust
ieee754
imaplib
imghdr
immer
immutable
import_fresh
importlib
importlib_abc
importlib_machinery
importlib_metadata
importlib_metadata_rust
importlib_resources
importlib_resources_rust
importlib_util
indent_string
inflect_rust
inflected
inflection
ini
inquirer
inspect
inspect_extra_rust
inspect_signature
invert_color
invert_kv
invoke_rust
io
io_extra_rust
io_extra2_rust
io_rust
io_streams
ip
ip_address
ip_regex
ipaddr_js
ipaddress
ipaddress_rust
is_absolute_url
is_alphabetical
is_alphanumeric
is_alphanumerical
is_anagram
is_array
is_arrayish
is_ascii
is_base64
is_blank
is_boolean
is_boolean_object
is_buffer
is_cidr
is_decimal
is_digit
is_docker
is_domain
is_email
is_empty
is_even
is_extendable
is_extglob
is_falsy
is_finite
is_float
is_fullwidth_code_point
is_glob
is_hexadecimal
is_hexcolor
is_html
is_integer
is_integer_x
is_ip
is_json
is_letter
is_local_path
is_lower_case
is_lowercase
is_mergeable_object
is_natural_number
is_negative
is_nil
is_null
is_number
is_number_like
is_number_object
is_numeric
is_obj
is_object
is_object_like
is_odd
is_palindrome
is_plain_obj
is_plain_object
is_positive
is_power_of_two
is_present
is_prime
is_primitive
is_promise
is_relative
is_relative_url
is_sorted
is_stream
is_string
is_typedarray
is_undefined
is_upper_case
is_uppercase
is_url
is_url_http
is_url_superb
is_uuid
is_whitespace
is_whitespace_character
is_whole_number
is_word_character
is_wsl
is_xml
is_zero
isbn3
isemail
iso_3166_1
iso8601_duration
isobject
isodate
isodate_rust
isort_rust
itertools
itertools_extra_rust
itertools_product
itertools_rust
itsdangerous_rust
jaro_winkler
jiti
jmespath
joblib_rust
joi
jose
jq
jq_rust
js_yaml
jsbi
jschardet
jsesc
json
json_bigint
json_decoder
json_encoder
json_extra_rust
json_extra2_rust
json_logic_js
json_mask
json_merge_patch
json_pointer
json_query
json_rust
json_stable_stringify
json_stringify_safe
json5
jsonata
jsonpath
jsonpath_plus
jsonpickle_rust
jsonpointer
jsonschema
jsonschema_rust
jsonwebtoken
jstat
jszip
just_camel_case
just_clamp
just_clone
just_compact
just_compare
just_diff
just_entries
just_extend
just_flatten
just_flatten_it
just_has
just_intersect
just_is_empty
just_is_prime
just_is_primitive
just_kebab_case
just_mean
just_median
just_mode
just_omit
just_pascal_case
just_pick
just_range
just_safe_get
just_safe_set
just_snake_case
just_sort_by
just_split
just_tail
just_truncate
just_typeof
just_union
just_unique
just_values
just_zip_it
jwcrypto_rust
jwt_rust
kafka_rust
kebab_case
keyword
keyword_rust
kind_of
kleur
klona
kubernetes_rust
lark_rust
last_item
lcm
ldap3_rust
left_pad
lerp
leven
levenshtein_edit_distance
lib2to3
libcrypto
libpcap
libphonenumber_js
libpng
libsodium
libxml2
libyaml
lightgbm_rust
limax
line_column
linecache
linkify_it
liquidjs
locale
locust_rust
lodash
lodash_add
lodash_assign
lodash_assignin
lodash_at
lodash_camelcase
lodash_capitalize
lodash_ceil
lodash_chunk
lodash_clamp
lodash_clone
lodash_clonedeep
lodash_compact
lodash_countby
lodash_deburr
lodash_defaults
lodash_defaultsdeep
lodash_defaultto
lodash_difference
lodash_differenceby
lodash_divide
lodash_drop
lodash_dropright
lodash_endswith
lodash_escape
lodash_every
lodash_fill
lodash_filter
lodash_find
lodash_findindex
lodash_findkey
lodash_findlastindex
lodash_findlastkey
lodash_flatten
lodash_flattendeep
lodash_flattendepth
lodash_floor
lodash_frompairs
lodash_get
lodash_groupby
lodash_gt
lodash_gte
lodash_has
lodash_head
lodash_identity
lodash_includes
lodash_indexof
lodash_initial
lodash_inrange
lodash_intersection
lodash_intersectionby
lodash_invert
lodash_invertby
lodash_invokemap
lodash_isarray
lodash_isarraylike
lodash_isarraylikeobject
lodash_isboolean
lodash_isempty
lodash_isequal
lodash_isfinite
lodash_isinteger
lodash_islength
lodash_ismatch
lodash_isnil
lodash_isnull
lodash_isnumber
lodash_isobject
lodash_isobjectlike
lodash_isplainobject
lodash_issafeinteger
lodash_isstring
lodash_join
lodash_kebabcase
lodash_keyby
lodash_keys
lodash_last
lodash_lastindexof
lodash_lowerfirst
lodash_lt
lodash_lte
lodash_map
lodash_mapvalues
lodash_max
lodash_maxby
lodash_mean
lodash_meanby
lodash_merge
lodash_min
lodash_minby
lodash_multiply
lodash_nth
lodash_omit
lodash_omitby
lodash_orderby
lodash_pad
lodash_padend
lodash_padstart
lodash_partition
lodash_pick
lodash_pickby
lodash_pull
lodash_pullall
lodash_pullat
lodash_range
lodash_rangeright
lodash_reject
lodash_repeat
lodash_result
lodash_reverse
lodash_round
lodash_set
lodash_size
lodash_slice
lodash_snakecase
lodash_some
lodash_sortby
lodash_sortedindex
lodash_sortedindexby
lodash_sortedindexof
lodash_sortedlastindex
lodash_sortedlastindexby
lodash_sortedlastindexof
lodash_sorteduniq
lodash_sorteduniqby
lodash_split
lodash_startcase
lodash_startswith
lodash_subtract
lodash_sum
lodash_sumby
lodash_tail
lodash_take
lodash_takeright
lodash_toarray
lodash_tofinite
lodash_tointeger
lodash_tolower
lodash_tonumber
lodash_topairs
lodash_topath
lodash_tosafeinteger
lodash_tostring
lodash_toupper
lodash_trim
lodash_trimend
lodash_trimstart
lodash_truncate
lodash_unescape
lodash_union
lodash_unionby
lodash_uniq
lodash_uniqby
lodash_unzip
lodash_upperfirst
lodash_values
lodash_without
lodash_words
lodash_xor
lodash_xorby
lodash_zip
lodash_zipobject
lodash_zipobjectdeep
log_symbols
logging
logging_config
logging_handlers
logging_nullhandler
loguru_rust
longest
longest_streak
lower_case
lower_case_first
lowercase_keys
lru_cache
luhn
lunr
luxon
lxml
lxml_etree_extra_rust
lxml_etree_rust
lxml_rust
lz_string
lz4
lzma
lzma_rust
lzutf8
magic_bytes_js
magic_string
mailbox
mailcap
markdown
markdown_it
markdown_it_rust
markdown_table
marked
markupsafe
markupsafe_rust
marshal
marshmallow_rust
masonite_rust
math
math_average
math_extra_rust
math_rust
math_sum
math_trig_rust
mathjs
matplotlib_rust
maturin_rust
md5
mdast_util_to_string
mean
media_typer
median
memfs
meow
merge_anything
merge_deep
merge_options
merge_stream
meriyah
methods
micromark
micromatch
micropython_rust
mime
mime_db
mime_match
mime_types
mimesis_rust
mimetype_extra_rust
mimetypes
mimetypes_rust
minimatch
minimist
mitt
mixin_deep
mkdirp
ml_matrix
mlly
mmap
mmap_extra_rust
mnemonist
modulefinder
moment
moment_timezone
more_itertools
more_itertools_extra_rust
more_itertools_rust
motor_rust
mri
ms
msal_rust
msgpack
msgpack_lite
msgpack_rust
multidict_rust
multimatch
multipledispatch_rust
multiprocessing
multiprocessing_extra_rust
murmurhash
mustache
mypy_rust
nacl_rust
namedtuple_rust
nanoid
nanoid_dictionary
nanostores
nats_rust
natsort_rust
natural_compare
natural_compare_lite
ndjson
negotiator
neo_async
netifaces_rust
netmask
netrc
networkx
networkx_rust
ngeohash
nltk_rust
nntplib
no_case
node_cache
node_cron
node_crypto
node_dir
node_dotenv
node_emoji
node_forge
node_glob
node_html_entities
node_html_parser
node_machine_id
node_os
node_path
node_querystring
node_url
node_util
node_vm
normalize_email
normalize_path
normalize_range
normalize_url
nox_rust
ntpath
nturl2path
num_words
num2fraction
numba_rust
number_abbreviate
number_commas
number_in_range
number_is_integer
number_precision
number_to_words
numbers
numbers_rust
numeral
numpy
numpy_agg_rust
numpy_array_rust
numpy_char_rust
numpy_extra_rust
numpy_eye_rust
numpy_linalg_rust
numpy_ops_rust
numpy_rust
numpy_set_rust
numpy_vstack_rust
numpy_where_rust
nunjucks
oauthlib_rust
obj_flatten
object_assign
object_assign_deep
object_depth
object_from_entries
object_has
object_hash
object_inspect
object_keys
object_merge
object_omit
object_path
object_pick
object_rename_keys
object_sizeof
object_values
objsize_rust
ofetch
on_headers
once
openssl
operator
operator_extra_rust
operator_rust
opossum
optparse
ora
orator_rust
ordinal
ordinalize
orjson_rust
os
os_environ
os_name
os_path
os_path_extra_rust
os_path_rust
os_rust
os_stat
ospath_extra_rust
outcome_rust
p_cancelable
p_debounce
p_defer
p_event
p_limit
p_locate
p_map
p_pipe
p_queue
p_reduce
p_retry
p_throttle
packaging
packaging_extra_rust
packaging_rust
pad_left
pad_right
pad_string
pako
palindrome_check
papaparse
param_case
parameterized_rust
paramiko_rust
parse_color
parse_domain
parse_duration
parse_entities
parse_headers
parse_json
parse_link_header
parse_ms
parse_rust
parse_url
parse5
parseurl
pascal_case
passlib_rust
password_validator
path_browserify
path_case
path_to_regexp
pathe
pathlib
pathlib_extra_rust
pathlib_extra2_rust
pathlib_pure
pathlib_rust
pathspec
pbkdf2
pcapng
pcre2
pdb
pdm_rust
peewee_rust
pendulum_rust
percentile
pexpect_rust
phone
phonenumbers_rust
piccolo_rust
pick_deep
pickle
pickle_rust
pickletools
picocolors
picomatch
pika_rust
PIL_rust
pillow
pino
pint_rust
pip_rust
pip_tools_rust
pipdeptree_rust
pipes
pipx_rust
pkgutil
platform
platform_extra_rust
platformdirs
playwright_rust
plist
plistlib
pluggy
pluggy_rust
plumbum_rust
pluralise
pluralize
poetry_core_rust
polars_rust
polyfactory_rust
pony_rust
poplib
portalocker_rust
portfinder
posix
posixpath
power_set
pprint
pprint_extra_rust
pprint_rust
pre_commit_rust
prepend_http
prettier
pretty_bytes
pretty_error
pretty_format
pretty_ms
pretty_time
prime_number
primes
prismjs
profile
proj4
prom_client
prompt_toolkit_rust
protobuf
protobuf_rust
protobufjs
proxy_addr
proxy_agent
proxy_from_env
psl
pstats
psutil
psutil_extra_rust
psycopg2_rust
pty
pug
punycode
pwd
py_compile
pyarrow_rust
pyclbr
pydantic_extra_rust
pydantic_extra_types_rust
pydantic_rust
pydantic_settings_rust
pydantic_v2_rust
pydoc
pyflakes_rust
pygments
pygments_rust
pyjwt_extra_rust
pylint_rust
pymongo_rust
pymysql_rust
pynput_rust
pyodbc_rust
pyotp_rust
pyparsing
pyparsing_rust
pypy_rust
pyramid_rust
pyright_rust
pytest_asyncio_rust
pytest_cov_rust
pytest_extra_rust
pytest_mock_rust
python_dotenv_rust
pytype_rust
pytz
pytz_extra_rust
pytz_rust
pyyaml
pyyaml_rust
pyzmq_rust
qrcode
qs
query_string
querystringify
questionary_rust
queue
queue_extra_rust
quick_lru
quopri
quopri_rust
ramda
random
random_rust
random_seed
random_seeded_rust
range_exclusive
range_inclusive
range_parser
rapidjson_rust
raw_body
re
re_compile_rust
re_extra_rust
re_findall_rust
re_match_rust
re_patterns
re_rust
reading_time
readline
readline_sync
redis_py_rust
regex_escape
regression
relative_luminance
remove_markdown
repeat_element
repeat_string
reprlib
reprlib_rust
requests
requests_oauthlib_rust
requests_utils_rust
resolve_from
resource
responses_rust
retry
retry_rust
reverse_string
rfdc
rgb_hex
rgb2hex
rich
rich_extra_rust
rich_extra2_rust
rich_rust
rimraf
rlcompleter
roman_numerals
romanize
rotate_array
round_to
ruamel_yaml_rust
runpy
rxjs
sade
safe_buffer
safe_regex
safe_stable_stringify
safety_rust
sanic_rust
sanitize_filename
sanitize_html
sched
schedule_rust
schema_rust
scipy_linalg_rust
scipy_special_rust
scipy_stats_rust
scrapy_rust
secrets
secrets_rust
seedrandom
select
select_extra_rust
selectors
selenium_rust
semver
semver_compare
semver_diff
semver_rust
sendgrid_rust
sentence_case
serialize_javascript
set_cookie_parser
set_value
setuptools
setuptools_scm_rust
sh_rust
sha_js
sha1
shell_quote
shellwords
shelve
shlex
shlex_rust
short_hash
short_uuid
shorten_url
shortid
showdown
shutil
shutil_extra_rust
sift
signal
signal_extra_rust
signal_rust
simple_get
simple_statistics
simplejson_rust
sindresorhus_is
six
six_rust
sklearn_cluster_rust
sklearn_decomp_rust
sklearn_metrics_rust
sklearn_preprocessing_rust
slash
slice_ansi
slug
slugify
sly_rust
smart_buffer
smaz
smol_toml
smtpd
smtplib
snake_case
snakecase_keys
sndhdr
sniffio_rust
socket
socket_rust
socketserver
sockjs_client
socks_proxy_agent
socksio_rust
sort_array
sort_asc
sort_desc
sort_keys
sortedcontainers_rust
space_separated_tokens
spacy_rust
sparkline
speakingurl
split_on_first
split_string
sprintf_js
sqlalchemy_rust
sqlite3
sqlite3_cli
sqlmodel_rust
sse_starlette_rust
ssl
stable
stable_stringify
standard_deviation
starlette_rust
stat
stat_rust
statistics
statistics_extra_rust
statistics_extra2_rust
statistics_rust
statsmodels_rust
statuses
stevedore
stopword
str_repeat
str_reverse
strawberry_rust
stream_buffers
strict_event_emitter
string
string_argv
string_byte_length
string_capitalize
string_extra_rust
string_extra3_rust
string_format
string_format_rust
string_hash
string_length
string_natural_compare
string_rust
string_score
string_similarity
string_stats
string_strip_html
string_template
string_template_rust
string_to_color
string_to_slug
string_truncate
string_width
stringify_entities
stringify_object
stringprep
strip_ansi
strip_bom
strip_color
strip_comments
strip_eof
strip_final_newline
strip_indent
strip_json_comments
stripe_rust
striptags
strman
strnum
struct
struct_rust
structlog_rust
stylis
subprocess
subprocess_extra_rust
subprocess_popen
sunau
svg_tags
svgo
swap_array
swap_case
syllable
sympy_rust
symtable
sys
sys_extra_rust
sys_platform
sys_rust
sysconfig
syslog
tabnanny
tabulate_rust
tarfile
telnetlib
tempfile
tempfile_extra_rust
tempy
tenacity_rust
tensorflow_rust
terminal_link
termios
terser
text_table
textextensions
textual_rust
textwrap
textwrap_dedent_rust
textwrap_extra_rust
textwrap_rust
theseus_abc_cr
theseus_abc_utils
theseus_aifc_cr
theseus_annotationlib_cr
theseus_antigravity_cr
theseus_argparse_cr
theseus_array_cr
theseus_array_cr2
theseus_array_cr3
theseus_ast_cr
theseus_asyncio_cr
theseus_asyncio_cr2
theseus_atexit_cr
theseus_base64
theseus_base64_cr
theseus_base64_cr2
theseus_base64_cr3
theseus_base64_cr4
theseus_bdb_cr
theseus_binascii_cr
theseus_bisect
theseus_bisect_cr
theseus_bisect_cr2
theseus_builtins_cr
theseus_bz2_cr
theseus_calendar
theseus_calendar_cr
theseus_calendar_cr2
theseus_cmath_cr
theseus_cmd_cr
theseus_code_cr
theseus_codecs_cr
theseus_codecs_cr2
theseus_codeop_cr
theseus_collections_abc_cr
theseus_collections_cr
theseus_collections_cr2
theseus_collections_cr3
theseus_collections_cr4
theseus_collections_cr5
theseus_collections_utils
theseus_colorsys_cr
theseus_colorsys_cr2
theseus_compileall_cr
theseus_compression_bz2_cr
theseus_compression_cr
theseus_compression_gzip_cr
theseus_compression_lzma_cr
theseus_compression_zlib_cr
theseus_compression_zstd_cr
theseus_concurrent_cr
theseus_concurrent_futures_cr
theseus_configparser_cr
theseus_configparser_cr2
theseus_contextlib
theseus_contextlib_cr
theseus_contextlib_cr2
theseus_contextlib_cr3
theseus_contextlib_cr4
theseus_contextvars_cr
theseus_copy
theseus_copy_cr
theseus_copyreg_cr
theseus_cprofile_cr
theseus_csv
theseus_csv_cr
theseus_csv_cr2
theseus_csv_cr3
theseus_ctypes_cr
theseus_curses_cr
theseus_dataclasses_cr
theseus_dataclasses_cr2
theseus_dataclasses_cr3
theseus_dataclasses_utils
theseus_datetime_cr
theseus_datetime_cr2
theseus_dbm_cr
theseus_decimal
theseus_decimal_cr
theseus_decimal_cr2
theseus_decimal_cr3
theseus_decimal_cr4
theseus_difflib
theseus_difflib_cr
theseus_difflib_cr2
theseus_dis_cr
theseus_doctest_cr
theseus_email_base64mime_cr
theseus_email_charset_cr
theseus_email_cr
theseus_email_encoders_cr
theseus_email_errors_cr
theseus_email_header_cr
theseus_email_iterators_cr
theseus_email_message_cr
theseus_email_mime_multipart_cr
theseus_email_mime_text_cr
theseus_email_quoprimime_cr
theseus_email_utils_cr
theseus_encodings_cr
theseus_ensurepip_cr
theseus_enum_cr
theseus_enum_cr2
theseus_enum_cr3
theseus_enum_cr4
theseus_enum_utils
theseus_errno_cr
theseus_faulthandler_cr
theseus_fcntl_cr
theseus_filecmp_cr
theseus_fileinput_cr
theseus_fnmatch
theseus_fnmatch_cr
theseus_fnmatch_cr2
theseus_fractions
theseus_fractions_cr
theseus_fractions_cr2
theseus_fractions_cr3
theseus_ftplib_cr
theseus_functools_cr
theseus_functools_cr2
theseus_functools_cr3
theseus_functools_cr4
theseus_functools_cr5
theseus_gc_cr
theseus_genericpath_cr
theseus_getopt_cr
theseus_getpass_cr
theseus_gettext_cr
theseus_gettext_cr2
theseus_glob_cr
theseus_glob_cr2
theseus_graphlib_cr
theseus_grp_cr
theseus_gzip_cr
theseus_hashlib
theseus_hashlib_cr
theseus_heapq
theseus_heapq_cr
theseus_heapq_cr2
theseus_hmac
theseus_hmac_cr
theseus_hmac_cr2
theseus_html_cr
theseus_html_cr2
theseus_html_cr3
theseus_html_escape
theseus_html_parser_cr
theseus_http_client_cr
theseus_http_cookiejar_cr
theseus_http_cookies_cr
theseus_http_cr
theseus_http_server_cr
theseus_idlelib_cr
theseus_imaplib_cr
theseus_importlib_abc_cr
theseus_importlib_cr
theseus_importlib_machinery_cr
theseus_importlib_metadata_cr
theseus_importlib_resources_cr
theseus_importlib_util_cr
theseus_inspect_cr
theseus_inspect_cr2
theseus_io_cr
theseus_io_cr2
theseus_io_cr3
theseus_io_cr4
theseus_io_utils
theseus_ipaddress
theseus_ipaddress_cr
theseus_itertools_cr
theseus_itertools_cr2
theseus_itertools_cr3
theseus_itertools_cr4
theseus_json
theseus_json_cr
theseus_json_cr2
theseus_json_cr3
theseus_json_cr4
theseus_json_cr5
theseus_keyword_cr
theseus_keyword_cr2
theseus_linecache_cr
theseus_locale_cr
theseus_logging_config_cr
theseus_logging_cr
theseus_logging_cr2
theseus_logging_handlers_cr
theseus_lzma_cr
theseus_mailbox_cr
theseus_marshal_cr
theseus_math
theseus_math_cr
theseus_math_cr2
theseus_math_cr3
theseus_math_cr4
theseus_math_cr5
theseus_mimetypes_cr
theseus_mmap_cr
theseus_modulefinder_cr
theseus_msvcrt_cr
theseus_multiprocessing_cr
theseus_multiprocessing_utils
theseus_netaddr_cr
theseus_netrc_cr
theseus_nntplib_cr
theseus_nt_cr
theseus_ntpath_cr
theseus_nturl2path_cr
theseus_numbers_cr
theseus_numbers_cr2
theseus_numbers_cr3
theseus_opcode_cr
theseus_operator
theseus_operator_cr
theseus_operator_cr2
theseus_operator_cr3
theseus_optparse_cr
theseus_os_cr
theseus_path_node
theseus_pathlib
theseus_pathlib_cr
theseus_pathlib_cr2
theseus_pathlib_cr3
theseus_pathlib_cr4
theseus_pathlib_cr5
theseus_pathlib_extra_cr
theseus_pdb_cr
theseus_pickle_cr
theseus_pickletools_cr
theseus_pkgutil_cr
theseus_platform_cr
theseus_platform_cr2
theseus_plistlib_cr
theseus_poplib_cr
theseus_posix_cr
theseus_posixpath_cr
theseus_pprint
theseus_pprint_cr
theseus_profile_cr
theseus_pstats_cr
theseus_pty_cr
theseus_pwd_cr
theseus_py_compile_cr
theseus_pyclbr_cr
theseus_pydoc_cr
theseus_pydoc_data_cr
theseus_pyexpat_cr
theseus_queue_cr
theseus_queue_cr2
theseus_quopri_cr
theseus_random_cr
theseus_random_cr2
theseus_re
theseus_re_cr
theseus_re_cr2
theseus_re_cr3
theseus_re_cr4
theseus_re_cr5
theseus_readline_cr
theseus_reprlib_cr
theseus_resource_cr
theseus_rlcompleter_cr
theseus_runpy_cr
theseus_sched_cr
theseus_secrets_cr
theseus_secrets_cr2
theseus_select_cr
theseus_selectors_cr
theseus_shelve_cr
theseus_shlex
theseus_shlex_cr
theseus_shlex_cr2
theseus_shutil_cr
theseus_signal_cr
theseus_site_cr
theseus_smtplib_cr
theseus_sndhdr_cr
theseus_socket_cr
theseus_socket_cr2
theseus_socket_cr3
theseus_socket_utils
theseus_socketserver_cr
theseus_sqlite3_cr
theseus_sre_compile_cr
theseus_sre_constants_cr
theseus_sre_parse_cr
theseus_ssl_cr
theseus_stat_cr
theseus_statistics
theseus_statistics_cr
theseus_statistics_cr2
theseus_statistics_cr3
theseus_string_cr
theseus_string_cr2
theseus_string_module_cr
theseus_string_utils
theseus_stringprep_cr
theseus_struct
theseus_struct_cr
theseus_struct_cr2
theseus_struct_cr3
theseus_struct_cr4
theseus_struct_extra_cr
theseus_subprocess_cr
theseus_sunau_cr
theseus_symtable_cr
theseus_sys_cr
theseus_sys_utils
theseus_sysconfig_cr
theseus_syslog_cr
theseus_tabnanny_cr
theseus_tarfile_cr
theseus_tempfile_cr
theseus_termios_cr
theseus_textwrap
theseus_textwrap_cr
theseus_textwrap_cr2
theseus_textwrap_cr3
theseus_this_cr
theseus_threading_cr
theseus_threading_cr2
theseus_threading_cr3
theseus_time_cr
theseus_timeit_cr
theseus_tkinter_cr
theseus_token_cr
theseus_tokenize_cr
theseus_tomllib_cr
theseus_trace_cr
theseus_traceback_cr
theseus_traceback_cr2
theseus_tracemalloc_cr
theseus_tty_cr
theseus_turtle_cr
theseus_turtledemo_cr
theseus_types_cr
theseus_types_cr2
theseus_typing_cr
theseus_typing_cr2
theseus_typing_cr3
theseus_typing_utils
theseus_unicodedata_cr
theseus_unicodedata_cr2
theseus_unittest_case_cr
theseus_unittest_cr
theseus_unittest_mock_cr
theseus_unittest_result_cr
theseus_urllib_cr
theseus_urllib_error_cr
theseus_urllib_parse
theseus_urllib_parse_cr
theseus_urllib_parse_cr2
theseus_urllib_parse_cr3
theseus_urllib_parse_cr4
theseus_urllib_request_cr
theseus_urllib_response_cr
theseus_urllib_robotparser_cr
theseus_uu_cr
theseus_uuid
theseus_uuid_cr
theseus_uuid_cr2
theseus_venv_cr
theseus_warnings_cr
theseus_warnings_cr2
theseus_wave_cr
theseus_weakref
theseus_weakref_cr
theseus_weakref_cr2
theseus_weakref_extra_cr
theseus_webbrowser_cr
theseus_winreg_cr
theseus_winsound_cr
theseus_wsgiref_cr
theseus_xml_cr
theseus_xml_cr2
theseus_xml_dom_cr
theseus_xml_et_cr
theseus_xml_etree_cr
theseus_xml_minidom_cr
theseus_xml_sax_cr
theseus_xmlrpc_client_cr
theseus_xmlrpc_cr
theseus_xmlrpc_server_cr
theseus_zipapp_cr
theseus_zipfile_cr
theseus_zipimport_cr
theseus_zlib_cr
theseus_zlib_cr2
theseus_zlib_cr3
theseus_zoneinfo_cr
this
threading
threading_extra_rust
threading_sync
threading_timer
time
time_rust
time_stamp
timeit
tiny_emitter
tiny_queue
tinycolor2
tinyglobby
tinypool
tinyspy
title_case
titlecase
titleize
tkinter
tldts
to_camel_case
to_constant_case
to_dot_case
to_no_case
to_number
to_pascal_case
to_regex_range
to_sentence_case
to_snake_case
to_space_case
to_title_case
to_words
toidentifier
token
token_rust
tokenize
toml_rust
tomli
tomli_rust
tomlkit
tomlkit_rust
toolz_rust
toposort
torch_rust
tornado
tornado_extra_rust
tortoise_orm_rust
tox_rust
tqdm_extra_rust
tqdm_rust
trace
traceback
traceback_extra_rust
tracemalloc
traitlets
transformers_rust
transliterate
traverse
trim_left
trim_right
trio_extra_rust
trio_rust
trough
truncate
tslib
tslog
tty
tunnel_agent
turf_helpers
turndown
turtle
tweetnacl
twilio_rust
twine_rust
twitter_text
type_check
type_detect
type_is
type_name
typebox
typeguard_rust
typer_rust
types
types_rust
typing
typing_extensions
typing_extensions_rust
typing_protocol
tz_lookup
tzdata
ua_parser_js
ucwords
ujson_rust
ulid
underscore
undici
unescape_js
unflatten
unicodedata
unicodedata_rust
unidecode
unidecode_rust
unified
uniq_array
unique_array_by
unique_names_generator
unist_util_stringify_position
unittest
unittest_mock
upper_case
upper_case_first
uppercamelcase
uppercase_keys
uri_templates
url_join
url_parse
url_slug
url_template
urllib_error
urllib_parse
urllib_parse_extra_rust
urllib_parse_rust
urllib_request
urllib_response
urllib_robotparser
urllib3
urllib3_extra_rust
urllib3_rust
utf8
utils_merge
uu
uuid
uuid_by_string
uuid_rust
uuid_validate
uuidv7
uvicorn_rust
valibot
validate_color
validate_npm_package_name
validator
validators_rust
valtio
variance
varint
vary
venv
verror
vfile
virtualenv_extra_rust
voluptuous_rust
warnings
watchdog_rust
wave
wcag_contrast
wcwidth
wcwidth_rust
weakref
weakref_extra_rust
weakref_rust
webbrowser
websockets_extra_rust
whatwg_url
wheel_rust
wide_align
word_count
word_wrap
wordcount
words_count
words_to_numbers
wrap_ansi
wrap_text
wrapt
wrapt_rust
written_number
ws
wsgiref
wsproto_rust
xbytes
xdrlib
xgboost_rust
xml_dom
xml_etree_rust
xml_js
xml_minidom
xml_parse
xml_sax
xml2js
xmldom
xmlrpc_client
xmlrpc_server
xmltodict_rust
xregexp
xss
xss_filters
xtend
xxhashjs
yaml
yaml_extra_rust
yaml_js
yargs
yargs_parser
yarl_rust
yup
z_schema
zero_fill
zipapp
zipfile
zipimport
zlib
zlib_checksum_rust
zlib_rust
zod
zod_validation_error
zoneinfo
zoneinfo_extra_rust
zoneinfo_rust
zope_interface
zstd

Installation

Requirements

Requirement Version Purpose
Python 3.9+ All tools and test suite
Node.js 22+ Node.js-backed Z-specs (ajv, chalk, express, lodash, minimist, prettier, semver, uuid)
npm any Install Node.js test dependencies
pytest any make test
PyYAML any make compile-zsdl / make test (ZSDL compiler)

To run the full behavioral spec suite (make verify-all-specs), the libraries under test must also be installed. The CI workflow installs them automatically. For local use, install the ones you want to verify individually.

Clone and set up

git clone https://github.com/jordanhubbard/Theseus
cd Theseus
pip install pytest pyyaml
npm install
make

make (with no target) checks your Python version and prints usage. If it exits cleanly, you are ready to go.

Verify the installation

make test

All 13,900+ tests should pass (test count grows with the spec corpus; many tests are auto-generated from compiled ZSDL specs). The suite uses no network access and does not require any external tools to be installed beyond Python and Node.js.

Quick Start

Option A: Demo on built-in examples (no snapshot needed)

make start

This runs the overlap report and candidate ranker against the three example records in examples/ (curl, openssl, zlib). Reports land in reports/demo-overlap/ and reports/demo-candidates.json.

Option B: Full pipeline on a real snapshot

If you have Nixpkgs and FreeBSD Ports source trees available:

# 1. Bootstrap canonical records from source trees
python3 tools/bootstrap_canonical_recipes.py \
  --nixpkgs /path/to/nixpkgs \
  --ports   /path/to/freebsd-ports \
  --out     ./snapshots/$(date +%Y-%m-%d)

# 2. Generate overlap report
make report SNAPSHOT=./snapshots/2026-04-06

# 3. Rank candidates
make candidates SNAPSHOT=./snapshots/2026-04-06

# 4. Extract top 50 candidates
make extract SNAPSHOT=./snapshots/2026-04-06

# 5. Check behavioral spec coverage
make spec-coverage EXTRACTION_DIR=reports/extractions/ TOP=50

Option C: Verify behavioral specs

# Compile ZSDL sources to JSON (required before verification)
make compile-zsdl

# Run all compiled specs (2,295 today)
make verify-all-specs

# Run a single spec
make verify-behavior ZSPEC=_build/zspecs/zlib.zspec.json

# Run all specs and write JSON results (for CI dashboards)
make verify-all-specs-json OUT=results.json

Project Layout

theseus/        Python package: importer, drivers, store, agent
tools/          CLI analysis and verification scripts
zspecs/         Z-spec ZSDL sources (*.zspec.zsdl) — committed to git
_build/zspecs/  Compiled JSON specs — build artifact, not committed
schema/         JSON Schema for canonical package records
zspecs/schema/  JSON Schema for Z-spec files
examples/       Sample records: curl, openssl, zlib
specs/          239 committed canonical package records
docs/           Architecture and design documentation
docs/guide/     This user guide (MkDocs source)
tests/          Test suite (13,900+ tests)
scripts/        Release automation

Make Targets Reference

Target Description
make / make all Check Python version, print usage
make start Demo on examples/ or analysis on SNAPSHOT=
make test Validate Z-specs + run pytest suite
make clean Remove _build/, .pytest_cache, *.pyc
make compile-zsdl Compile all ZSDL sources (or one: ZSDL=path)
make verify-all-specs Run all specs; text summary
make verify-all-specs-json Run all specs; write JSON results
make verify-behavior Run one spec (ZSPEC=path, supports FILTER=, VERBOSE=1)
make validate-zspecs Static schema validation of all compiled specs
make spec-coverage Coverage report (EXTRACTION_DIR= required)
make orphan-specs Specs with no matching extraction record
make spec-vector-coverage Per-spec invariant description coverage
make report Overlap report (SNAPSHOT= required)
make candidates Candidate ranking (SNAPSHOT= required)
make extract Phase Z extraction (SNAPSHOT= and CANDIDATES_OUT= required)
make validate Validate records (PATHS=dir, default: examples/)
make diff Diff two snapshots (BEFORE= and AFTER= required)
make release Cut a release (BUMP=major\|minor\|patch, default: patch)
make help Full variable and target reference

Next Steps