Cogniac Python SDK
Python SDK for the Cogniac public API. Provides both synchronous and asynchronous (async/await) interfaces.
Requires Python 3.11+
Installation
pip install cogniac
Configuration
Authentication is configured via environment variables or constructor arguments:
| Variable | Description |
|---|---|
COG_USER |
Cogniac username (usually an email address) |
COG_PASS |
Cogniac password |
COG_API_KEY |
API key (alternative to username/password) |
COG_TENANT |
Tenant ID (required if user belongs to multiple tenants) |
COG_URL_PREFIX |
API endpoint (default: https://api.cogniac.io/) |
Synchronous API
import cogniac
cc = cogniac.CogniacConnection()
# Tenants and users
tenant = cc.get_tenant()
print(tenant.name)
# Applications
apps = cc.get_all_applications()
app = cc.get_application(application_id)
# Subjects
subjects = cc.get_all_subjects()
subject = cc.create_subject(name="my-subject", description="example")
subject.description = "updated" # auto-syncs to API
subject.delete()
# Media
media = cc.create_media("image.jpg", meta_tags=["test"])
fetched = cc.get_media(media.media_id)
image_bytes = fetched.download() # returns bytes
with open("out.jpg", "wb") as f: # or write to file
fetched.download(f) # takes open file object, NOT a path string
# Paginated results via generators
for detection in app.detections(limit=100):
print(detection)
# Score your own predictions (e.g. from a VLM or another model) the way CloudCore
# scores the app's models: against a consensus release, with an evaluation metric
result = app.evaluate([{"media_id": media_id, "subject_uid": subject_uid, "probability": 0.9}],
consensus_release_id=None, # default: the app's latest release
evaluation_metric_hash=None, # default: the app's primary metric
allow_unscorable=False, # True: score what can be scored instead of a 400
timeout=None) # default 3600 s: scoring time grows with the release
print(result["coverage"], result["summary"])
Each prediction is one (media, focus, subject):
media_id,subject_uid, andfocusfor apps that label a focus box (copy it from the release label; omit it for whole-image labels);- plus, by app type:
probability(detection, classification),boxes([{x0, y0, x1, y1, probability?}], image pixels),points([{x, y, probability?}], image pixels) ortext(OCR; the app must have exactly one output subject).
For classification, send one prediction per unit, naming the chosen subject; for the other types, a subject with no prediction counts as a negative. The CLI's --predictions FILE takes a JSON array or JSON Lines of these.
Entity Classes
| Class | Description |
|---|---|
CogniacConnection |
Authentication and HTTP session management |
CogniacApplication |
Vision applications (detection, classification, etc.) |
CogniacSubject |
Organizational groupings of media |
CogniacMedia |
Image and video files |
CogniacTenant |
Tenant (organization) management |
CogniacUser |
User accounts and API keys |
CogniacEdgeFlow |
Edge computing devices (alias: CogniacGateway) |
CogniacNetworkCamera |
Network camera configuration |
CogniacExternalResult |
External inspection results |
CogniacOpsReview |
Operations review queue |
CogniacDeployment |
Deployment groups (EdgeFlow/CloudFlow rollouts) |
CogniacDeploymentCapacityClass |
Deployment capacity classes |
CogniacWorkflow |
Deployment workflows and versions |
CogniacBuild |
EdgeFlow/CloudFlow build definitions |
Async API
The async interface mirrors the sync API. Use AsyncCogniacConnection.create() as an async factory:
import asyncio
import cogniac
async def main():
async with await cogniac.AsyncCogniacConnection.create() as cc:
# List subjects
subjects = await cogniac.AsyncCogniacSubject.get_all(cc)
for s in subjects:
print(s.name, s.subject_uid)
# Create and update
s = await cogniac.AsyncCogniacSubject.create(cc, name="my-subject")
await s.set(description="updated") # explicit async setter
await s.delete()
# Download media
media = await cogniac.AsyncCogniacMedia.get(cc, media_id)
image_bytes = await media.download() # returns bytes
with open("out.jpg", "wb") as f: # or write to file
await media.download(f) # takes open file object, NOT a path string
# Async generators for paginated endpoints
apps = await cogniac.AsyncCogniacApplication.get_all(cc)
async for detection in apps[0].detections(limit=10):
print(detection)
asyncio.run(main())
Every sync entity class has an async counterpart prefixed with Async (e.g., AsyncCogniacSubject, AsyncCogniacMedia).
Key Differences from Sync API
- Connection:
await AsyncCogniacConnection.create(...)instead ofCogniacConnection(...) - Attribute updates:
await subject.set(name="new")instead ofsubject.name = "new"(batches multiple fields in one API call) - Pagination:
async forwith generators (detections,media_associations,usage, etc.) - Cleanup: supports
async withcontext manager for automatic session cleanup
CLI Tools
cogniac
Agent-friendly CLI. JSON output by default; --format table for humans or --format jsonl for one JSON object per line. The command tree is nested, noun-first / verb-last; resource ids are --<resource>-id flags (the older positional form, e.g. application get <id>, still works). --format and --tenant may be given before or after the command.
cogniac auth # check credentials (add --tenant <id> to verify a session)
cogniac auth login # browser login; store a per-user API key
cogniac commands # print the whole command tree as JSON (noun -> verbs -> args)
cogniac tenant get # current tenant info
cogniac application list # list applications
cogniac application get --application-id <id> # one application
cogniac subject list
cogniac subject search --prefix test # search subjects
cogniac subject media --subject-uid <uid> --full-media # full media records, not just media_id
cogniac media get --media-id <id> # media metadata
cogniac media download --media-id <id> -o out.jpg # download media to file
cogniac edgeflow list # list edge devices
cogniac edgeflow status --edgeflow-id <id> --list-subsystems # discover which subsystems a device reports
cogniac edgeflow health # fleet health derived from each device's latest status record
cogniac application create --body @app.json # --body takes inline JSON, @FILE, or - (stdin)
cogniac application evaluate --application-id <id> --predictions preds.jsonl # score predictions
# (JSON array or JSON Lines) against the latest consensus
# release with the primary metric; --consensus-release-id,
# --evaluation-metric-hash, --allow-unscorable, --label
cogniac deployment deploy --deployment-group-id <id> --workflow-id <wf> # DISPATCH a workflow rollout
# (--now bypasses the group schedule; --timeout raises the
# client read timeout — the server blocks until every
# EdgeFlow accepts, default 300s)
cogniac deployment deploy-status --deployment-group-id <id> # rollout convergence status
cogniac deployment target workflow set ... # records target_workflow_id only — does NOT deploy
Descriptions under version control
cogniac descriptions keeps a tenant's tenant, application and subject descriptions in a descriptions-<tenant_id>.yaml file, so description changes can be reviewed and versioned like code:
cogniac --tenant <tenant_id> descriptions export [--application-id <id> ...] # write descriptions-<tenant_id>.yaml
cogniac descriptions plan descriptions-<tenant_id>.yaml # what differs from the live tenant; exit 2 if anything does
cogniac descriptions apply descriptions-<tenant_id>.yaml # write the descriptions that differ (asks first; --yes to skip)
tenant:
tenant_id: <tenant_id>
name: <tenant name> # names are for readability only; never applied
description: <text>
applications:
<application_id>:
name: <application name>
description: |
<text, may span lines>
subjects:
<subject_uid>:
name: <subject name>
description: <text>
- The file names the tenant;
planandapplyrefuse a--tenantthat differs. - Only descriptions are managed. Anything the file doesn't list is left alone, and a listed tenant only has its description managed if the file gives one.
- A listed application or subject must have a
descriptionkey, anddescription: ""clears that description. Descriptions are limited to 8,000 characters. exportwrites the tenant and every application and subject by default. With--application-id, it writes only those applications and their input and output subjects.--refresh --file FILEupdates the entries an existing file lists.applyworks from the file and the live values alone, so running it again is a no-op. Writing the tenant description needs the tenant admin role.
Evaluation metrics
Each application scores its models with up to five active evaluation metrics. One is primary: models are ranked and released by it, and evaluate() uses it unless given another evaluation_metric_hash.
cogniac application evaluation metrics schema [--name box_F1] # what each metric scores; its parameters, defaults and ranges
cogniac application evaluation metrics get --application-id <id> # the app's active metrics, primary first, with hashes
cogniac application evaluation metrics create --application-id <id> --body '{"name": "box_F1", "iou_threshold": 0.5, "active": 1}'
cogniac application evaluation metrics set-primary --application-id <id> --evaluation-metric-hash <hash>
cogniac application evaluation metrics delete --application-id <id> --evaluation-metric-hash <hash> # not the primary
In the SDK: CogniacApplication.evaluation_metric_schemas(cc, name=None), and on an application evaluation_metrics(), create_evaluation_metric(body), set_primary_evaluation_metric(hash) and delete_evaluation_metric(hash). A metric is identified by its configuration, so the same configuration always has the same hash. create adds a non-primary metric; add "primary": 1 to make it primary in the same call.
Run cogniac <noun> --help to explore the tree interactively, or cogniac commands for the full machine-readable catalog. An unknown command suggests the closest match.
icogniac
Interactive IPython shell with pre-loaded Cogniac connection:
icogniac [optional tenant name or ID]
cogupload
Parallel media upload (24 threads) to a subject:
cogupload <subject_uid> <directory>
cogstats
EdgeFlow statistics aggregation:
cogstats -t TENANT_ID [-g GATEWAY_ID] [-s START] [-e END]
Support
Please email support@cogniac.co with feedback.
Metadata
Release files for cogniac 3.6.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| cogniac-3.6.1.tar.gz | 181.4 kB | Without provenance | Details for cogniac-3.6.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| cogniac-3.6.1-py3-none-any.whl | Python 3 | none | any | Details for cogniac-3.6.1-py3-none-any.whl |
Total release size: 337.7 kB
Release files / cogniac-3.6.1.tar.gz
| Download URL | cogniac-3.6.1.tar.gz |
|---|---|
| Size | 181.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
400056e62133f8dc21797ae54e00b075fb3c017ee7a1af69724bce0f31dd2271
|
|
BLAKE2b-256 checksum How to use checksums |
724e8eb979ce0be5ee122e5beea540874afcc7d5a8d6717c132183d0f6c381f4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.6 {"installer":{"name":"uv","version":"0.11.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / cogniac-3.6.1-py3-none-any.whl
| Download URL | cogniac-3.6.1-py3-none-any.whl |
|---|---|
| Size | 156.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bb6d7d452158372a302f63da1a3cb0d3cf06e160c8ceeebd57671c55408c1e2a
|
|
BLAKE2b-256 checksum How to use checksums |
40c8f32b0306bcb5069c2ca2ac7cfc7274ff707ace74ee8177d00cf6e4763fdc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.6 {"installer":{"name":"uv","version":"0.11.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for cogniac 3.6.1
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.