Skip to main content

Annapurna Suite Python SDK

Automate your Annapurna workspace from Python: projects, points, block models, drillholes, surfaces, meshes, modeling instances, sharing and Compute jobs.

pip install annapurna

Authenticate

Create a key in Account Settings → API Key, then keep it out of your code:

export ANNAPURNA_API_KEY="aps_live_..."          # Windows: setx ANNAPURNA_API_KEY "aps_live_..."
export ANNAPURNA_ENV="prod"      # optional: "prod" (default, api.annapurnasuite.com) or "dev" (dev-api.annapurnasuite.com)
import annapurna as ap

client = ap.Client()          # or ap.Client(api_key=..., environment="dev")
print(client.whoami())

Work with a project

proj = client.project("Fireweed")          # client.project() = active project
proj.objects()                             # everything, grouped by kind

# Block models / points ------------------------------------------------------
bm = proj.block_models.read("BM_123", columns=["Easting", "Northing", "Elevation", "Au"])
proj.block_models["BM_123"].clone("BM_123_backup")
proj.block_models.rename("BM_123_backup", "BM_123_v1")
proj.block_models.reblock("BM_123", "BM_123_25m", size=(25, 25, 10), weight_column="Density")
proj.points.upload("Comps_2026", comps_df)                  # refuses to overwrite unless overwrite=True
proj.points.rename_columns("Comps_2026", {"AU": "Au_gpt"})
proj.points.delete("Old_Comps")

# Drillholes ------------------------------------------------------------------
proj.drillholes.list()                       # drillhole projects
proj.drillholes.tables("Fireweed_DH")        # their tables
assays = proj.drillholes.read("Fireweed_DH", "Assays")

# Surfaces & meshes (OBJ) -------------------------------------------------------
proj.meshes.upload("Ore_Shell", "shell.obj")
proj.surfaces.download("Topo_2025", "topo.obj")

Modeling instances

inst = proj.instances
inst.upload("Au_OK", method="kriging", csv="params.csv")    # path, CSV text or DataFrame
result = inst.run("Au_OK", wait=True)                       # blocks until Completed/Failed/Killed
print(result.status, result.run_time)

# Edit the parameter table (index = parameter, columns = runs, values as text)
df = inst.load("SGS_Iter_0")
df.loc["num_reas"] = "50"
inst.save("SGS_Iter_1", df)        # new instance (method from the 'method' row), or
inst.save("SGS_Iter_0", df)        # replace the parameters of an existing one

Compute: evaluate geometries

from annapurna import GeometryMapping as G

proj.evaluate(
    "block_models", "BM_123", attribute="Domain", default_label="WASTE",
    mappings=[G("Ore_Shell", "ORE"), G("Topo_2025", "AIR", geometry_type="surface", side="above")],
)

Share datasets

code = proj.share("block_models", "BM_123")      # give code.access_code and code.password (separately)
client.sharing.preview(access_code, password)
client.project("Target").import_shared(access_code, password)

Inside Annapurna (Project Scripting page)

ap is already loaded and works without a key:

ap.list_datasets("block_models")
bm = ap.load("block_models", "BM_123")
ap.save(bm.describe(), "reports/summary.csv")

print(ap.list_instances())
params = ap.load_instance("SGS_Iter_0")
params.loc["num_reas"] = "50"
ap.save_instance(params, "SGS_Iter_1")

ap.file_to_bm("Lb1_geo.csv", "LB1_geo", data_row=5, easting="centroid_x", northing="centroid_y",
              elevation="centroid_z", xsize="dim_x", ysize="dim_y", zsize="dim_z", categorical=["lito"])
ap.file_to_points("raw/comps.csv", "Comps_2026", easting="X", northing="Y", elevation="Z", dhid="HOLEID")
ap.file_to_bm("Pit_BM.csv", "Pit_BM", origin=(46117.5, 7002.5, 867.5), count=(200, 150, 60),
              block_size=(15, 15, 15), rotation=32.5, rotation_point=(46110.0, 6995.0))

kriging = ap.read_instance("the_kriging.csv")
ap.save_instance(kriging, "Kriging_From_Disk", method="kriging")

Platform modules

The modules of the platform pages are functions of ap inside Annapurna. Each one runs for the open project and waits for the result; chart modules save their PNG figures to Disk:

ap.histogram("points", "Comps_2026", ["Au", "Cu"], bins=40)
stats = ap.statistics("block_models", "BM_2026", ["Au"], break_by="Zone")
ap.compositing("DH_2026", "Assays", "Assays_Comp5", length=5)
ap.cumulative("points", "Comps_2026", ["Au"], break_by="Domain", save_to="report/cdf")
print(ap.MODULES)

Disk files and PDF reports

print(ap.disk_list("figures/contact_analysis", pattern="*.png"))
ap.figures_to_pdf("figures/contact_analysis", "reports/contacts.pdf")
ap.disk_delete("tmp/old_export.parquet")
ap.disk_delete(ap.disk_list("tmp", pattern="*.csv"), missing_ok=True)

figs = ap.contact_analysis("Comps_2026", "cut", contact="ue_cut")
figs.to_pdf("reports/contacts.pdf")

Rotation angles between software

ap.angles_conversion converts anisotropy angles (variograms, search ellipsoids, local anisotropy) between Annapurna, which uses the GSLIB ang1, ang2, ang3, Leapfrog, Vulcan and Datamine. It works inside the platform and on your own computer:

ap.angles_conversion((120, -35, 10), "annapurna", "leapfrog")
# {'dip': 36.22, 'dip_azimuth': 137.09, 'pitch': 76.07}

ap.angles_conversion({"bearing": 120, "plunge": -35, "dip": -10}, "vulcan", "annapurna")
# {'ang1': 120.0, 'ang2': -35.0, 'ang3': 10.0}

ap.angles_conversion((90, 60, 30), "datamine", "annapurna")          # SANGLE1-3 about axes 3-1-3
ap.angles_conversion((120, -35, 10), "annapurna", "directions")      # azimuth / plunge of each axis

bm[["ang1", "ang2", "ang3"]] = ap.angles_conversion(bm[["dip", "dip_azimuth", "pitch"]], "leapfrog", "annapurna")

Errors

Every error derives from ap.AnnapurnaError: AuthenticationError, PermissionDeniedError, NotFoundError, ConflictError, ValidationError, RateLimitError, ServerError, APIConnectionError, TaskFailedError, TaskTimeoutError.

Security

  • The key is read from the environment, sent only to base_url over HTTPS, and never printed.
  • Redirects are not followed with the key; file transfers use short-lived signed URLs without the key.
  • Names are validated and URL-encoded, so they cannot alter request paths.
  • TLS verification cannot be disabled (use verify="/path/ca.pem" for corporate proxies).
  • Revoke a leaked key immediately in Account Settings.

Upgrading from 0.0.x

Old flat methods (client.read_parquet, client.upload_points, client.run_instance, …) still work and print a DeprecationWarning that names the new call. whoami() now returns an Identity object (dict-style access me["username"] still works).

Metadata

Release files for annapurna 0.2.7

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

Source distribution (sdist)

Source distribution for annapurna 0.2.7
File Size Uploaded Provenance Actions
annapurna-0.2.7.tar.gz 87.8 kB Without provenance Details for annapurna-0.2.7.tar.gz

Built distribution (wheel)

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

Total release size: 178.5 kB

Release files / annapurna-0.2.7.tar.gz

Download URL annapurna-0.2.7.tar.gz
Size 87.8 kB
Tags Source
SHA-256 checksum
How to use checksums
fad723c68340988a5e512e9423db0902d98a857fe15e779a8252c2fa71b17f2a
BLAKE2b-256 checksum
How to use checksums
4830aa37a02a54b24ea47c4786dbf6e8006c06f77c15bfe7bf34b0c08aa4c58b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.13

Release files / annapurna-0.2.7-py3-none-any.whl

Download URL annapurna-0.2.7-py3-none-any.whl
Size 90.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2e5bd840c417033473d26fd50e4685ef8c085ef0187cdfa26382c2146308b0e7
BLAKE2b-256 checksum
How to use checksums
378b2baa5858d2f709a3187ad1b9e5e332bf1be628cfcbf065fde88a354861b7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.13

Security for annapurna 0.2.7

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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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

0.2.7 This release

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