Cannlytics

Simple Cannabis Analytics — The cannlytics Python package provides tools to wrangle, augment, archive, and analyze cannabis data. From COA parsing to lab results analytics to the Metrc API, Cannlytics puts cannabis data in your hands.

Installation

Install the core package from PyPI:

pip install cannlytics

Requires Python 3.11 or later. Install with optional features as needed:

# COA parsing (PDF extraction).
pip install "cannlytics[coa]"

# COA parsing with AI-powered multi-provider support, and embeddings.
pip install "cannlytics[coa,ai]"

# Firebase / Firestore integration.
pip install "cannlytics[firebase]"

# Every runtime extra.
pip install "cannlytics[all]"

Every API key is optional and read from the environment. Copy .env.example to .env to see what each one switches on.

Or clone the repository:

git clone https://github.com/cannlytics/cannlytics.git
cd cannlytics
pip install -e ".[all]"

Quick Start

Parse a COA

Extract lab results from a Certificate of Analysis PDF:

from cannlytics.data.coas import COAdoc

parser = COAdoc()
coa = parser.parse('blue-dream-coa.pdf')

if 'error' in coa:
    print(coa['error'])
else:
    # Sample details.
    metadata = coa['metadata']
    print(metadata['product_name'], metadata['lab'], metadata['total_thc'])

    # Results, grouped by analysis.
    for result in coa['analyses']['cannabinoids']['results']:
        print(result['key'], result['value'], result['units'])

Work with the Published Results

Load the Cannlytics results product (Parquet; pip install cannlytics[datasets]):

from cannlytics.datasets import load_samples, load_results, flatten_results

samples = load_samples('cannabis-results-2026-09-26', states=['ca', 'ky'], years=[2025])
results = load_results('cannabis-results-2026-09-26', states=['ky'], analytes=['Δ9-THC', 'THCA'])
wide = flatten_results(results)   # one row per sample (pdf_hash), one column per analyte

Clean and Standardize

The same rules every Cannlytics dataset uses:

from cannlytics.constants import normalize_analyte_key, state_code
from cannlytics.clean import parse_date, clean_zip_code
from cannlytics.licenses import normalize_license_number, license_key

normalize_analyte_key('Δ9-THC')           # 'delta_9_thc'
state_code('New Jersey')                  # 'NJ'
parse_date('1/5/24')                      # '2024-01-05'
clean_zip_code(2134)                      # '02134'
normalize_license_number(' c10-0000936-lic ')   # 'C10-0000936-LIC' (stored as issued)
license_key('C10-0000936-LIC')            # 'C10-936' (for matching only)

Access Cannabis Data

Query Cannlytics data through the Firebase API:

from cannlytics.firebase import initialize_firebase, get_collection

# Initialize with your credentials.
db = initialize_firebase('.env')

# Query lab results.
results = get_collection(
    'public/data/results',
    filters=[{'key': 'state', 'operation': '==', 'value': 'ca'}],
    order_by='total_thc',
    desc=True,
    limit=100,
)

for r in results:
    print(f"{r['product_name']}: {r['total_thc']}% THC")

Use the Metrc API

Interface with the Metrc seed-to-sale tracking system:

from cannlytics.metrc import Metrc

with Metrc(
    'your-vendor-api-key',
    'your-user-api-key',
    primary_license='123',
    state='ok',
    test=True,
) as track:

    # Get a plant by its ID.
    plant = track.get_plants(uid='123')

    # Harvest the plant.
    plant.harvest(harvest_name='Old-Time Moonshine', weight=420)

Metrc API version. This client speaks version 1 of the Metrc API. Metrc has been retiring v1 state by state since the end of 2024 in favour of Metrc Connect (v2), so check your state before relying on it. Version 2 support is the next milestone for this module.

Verify a file, embed a COA

Every hash in Cannlytics is a whole-input SHA-256 that you can reproduce with sha256sum or Get-FileHash:

from cannlytics.utils import hash_file

pdf_hash = hash_file('blue-dream-coa.pdf')

Embed text, images, and whole PDFs in one vector space, then search, cluster, or look for outliers:

from cannlytics.ai import create_pdf_embedding, find_similar, project_embeddings

coa = create_pdf_embedding('blue-dream-coa.pdf')   # keyed by pdf_hash
matches = find_similar(coa['embedding'], stored_embeddings, k=5)
coordinates, explained = project_embeddings(stored_embeddings, n_components=2)

Package Overview

Firebase Module

The cannlytics.firebase module wraps firebase_admin with an ergonomic path-based API. Organized into focused submodules:

All functions are re-exported for convenience:

from cannlytics.firebase import initialize_firebase, get_document, upload_file

Firestore Enterprise

Supports multi-database configurations via the database_id parameter:

db = initialize_firebase('.env', database_id='cannlytics-enterprise')

Once initialized, all subsequent calls (get_document, get_collection, etc.) automatically target the Enterprise database — no code changes needed in your API endpoints.

Data Operations

from cannlytics.firebase import (
    get_document,
    get_collection,
    update_document,
    update_documents,
)

# Get a single document.
strain = get_document('public/data/strains/blue-dream')

# Query with filters, ordering, and pagination.
results = get_collection(
    'public/data/results',
    filters=[
        {'key': 'state', 'operation': '==', 'value': 'wa'},
        {'key': 'total_thc', 'operation': '>=', 'value': 20.0},
    ],
    order_by='date_tested',
    desc=True,
    limit=50,
)

# Batch update (auto-shards at 420 docs per batch).
refs = [f'public/data/results/{r["id"]}' for r in results]
data = [{'reviewed': True} for _ in results]
update_documents(refs, data)

COA Parsing

The cannlytics.data.coas module provides a hybrid COA parsing engine: lab-specific algorithms first, then AI with a multi-provider fallback chain (Anthropic → OpenAI → Gemini → xAI):

from cannlytics.data.coas import COAdoc

parser = COAdoc()
coa = parser.parse('coa.pdf')          # a path, a URL, or a list of either
metadata, analyses = coa['metadata'], coa['analyses']

Each COA is identified by its pdf_hash, the SHA-256 of the whole file.

See the COA documentation for full details.

Data Assets

Cannlytics maintains comprehensive cannabis datasets:

Testing

Run the test suite:

pip install -e ".[test]"
pytest tests/ --cov=cannlytics --cov-report=term-missing

No credentials or network access are required: every external service is mocked. Tests that need real COA PDFs (marked fixtures) skip when the local-only fixture folders are absent, and live-sandbox tests are marked integration.

Development

git clone https://github.com/cannlytics/cannlytics.git
cd cannlytics
pip install -e ".[dev]"
pytest tests/ -v
ruff check cannlytics/

Contributing

Contributions are welcome. Please ensure:

1. All new functions have at least one test.
2. pytest tests/ passes with no failures.
3. ruff check cannlytics/ passes with no errors.

License

Copyright (c) 2020-2026 Cannlytics

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.