How albert-labs/albert-python works
1. This repository is a Python SDK, not an application server. Its core purpose is to provide a typed, organized client for the Albert Invent platform’s REST-style resources such as projects, inventory, lots, sheets, users, tasks, and many others.
2. The top-level entry point is src/albert/__init__.py and src/albert/client.py. The Albert client is the main façade that application code uses to construct authenticated clients and access resource groups like client.projects, client.inventory, or client.lots.
3. The networking and request lifecycle live under src/albert/core/. This layer contains the synchronous and asynchronous session implementations, pagination helpers, shared base classes, logging, and utility code. It is the transport boundary between SDK consumers and the Albert API.
4. Authentication is a dedicated subsystem in src/albert/core/auth/. It includes client-credential handling, SSO support, token/listener management, and credentials models. This layer feeds the session layer so all downstream resource calls are authenticated consistently.
5. The SDK splits domain access into two parallel abstractions:
- src/albert/resources/ for API-facing resource managers and endpoints
- src/albert/collections/ for collection/data models and higher-level entity representations
In practice, resources orchestrate HTTP operations while collections define the domain objects and request/response shapes.
6. Most business domains are represented as first-class modules, not generic endpoints. Examples include projects, inventory, notebooks, sheets, tasks, storage locations, substances, hazards, data templates, custom fields, teams, roles, reports, and chats. This suggests the diagram should show many peer resource domains hanging off a shared client core.
7. There is a clear shared-model layer in src/albert/core/shared/. It defines common enums, identifiers, base models, patch models, and shared types used across both resource and collection code. This is the main consistency boundary for schema and identifier handling.
8. Utility modules in src/albert/utils/ provide domain-specific helpers for auth, patching, dataframes, custom fields, inventory, property data, tasks, and worksheets. These are convenience layers above the raw resources, likely used to normalize payloads or simplify common workflows.
9. The repository also includes some specialized subresources that imply richer workflows beyond simple CRUD. Notable examples are smart datasets, worker jobs, report templates, chats, and smart projects. These should be treated as separate architectural nodes because they likely coordinate multiple underlying API calls.
10. Tests mirror the architecture closely. tests/collections/, tests/resources/, tests/core/, and tests/utils/ validate each layer independently, while tests/data/ contains fixture artifacts such as a PDF sample. This indicates a layered design with unit tests around each boundary rather than one monolithic integration suite.
11. Documentation is a major part of the repo. The docs/ tree contains concept pages, authentication, configuration, migration, SSO, examples, and extensive resource/collection references. The architecture of the SDK is therefore intended to be discoverable by generated or maintained docs aligned to the code modules.
12. Tooling and release automation are present but not part of runtime behavior: pyproject.toml, mkdocs.yml, pre-commit config, GitHub Actions, CircleCI, and release-please config. These support validation, documentation publishing, and package release, but the runtime architecture remains the client/auth/session/resource stack described above.
13. For an architecture diagram, the central flow is: consumer code -> Albert client -> auth/session core -> resource layer -> API responses -> collection/shared models/utilities. The main boundary is the SDK-to-platform HTTP edge; everything else is internal organization around domain-specific access patterns.
Main entry points: resources Resources · client.py Albert client · session.py Session core · tests Layered tests
Components 19
Source
Runtime SDK code under src/albert
- Albert client · Main SDK entry point for authenticated client construction and resource access
src/albert/client.py - Auth core · Client credentials, SSO, token handling, and auth listener management
src/albert/core/auth - Session core · Synchronous and async request lifecycle and HTTP session boundary
src/albert/core/session.py - Shared models · Common enums, identifiers, base models, patch models, and shared types
src/albert/core/shared - Pagination · Shared pagination behavior for API result traversal
src/albert/core/pagination.py - Resources · Endpoint managers that orchestrate HTTP operations for platform domains
src/albert/resources - Collections · Higher-level collection and entity representations for request and response shapes
src/albert/collections - Utilities · Convenience helpers for auth, patching, dataframes, inventory, tasks, and worksheets
src/albert/utils - Projects · Project access and orchestration
src/albert/resources/projects.py - Inventory · Inventory operations and domain workflows
src/albert/resources/inventory.py - Lots · Lot-centric resource access
src/albert/resources/lots.py - Sheets · Sheet operations and related API flows
src/albert/resources/sheets.py - Users · User and identity access
src/albert/resources/users.py - Tasks · Task workflows and coordination helpers
src/albert/resources/tasks.py - Smart datasets · Dataset-oriented workflow abstraction over multiple API calls
src/albert/resources/smart_datasets.py - Reports · Report and report-template access
src/albert/resources/reports.py - Chats · Chat sessions, folders, flags, and messages access
src/albert/resources/chats.py
Docs
Documentation aligned to SDK modules
- Docs tree · Concepts, authentication, configuration, examples, and resource references
docs
Tests
Layered tests mirroring source architecture
- Layered tests · Tests covering collections, resources, core, and utils boundaries
tests
Connections 27
- Albert client → Auth core: configures · Creates authenticated client sessions
- Albert client → Session core: uses · Routes API calls through the transport layer
- Albert client → Resources: exposes · Publishes domain managers like projects, inventory, and lots
- Albert client → Collections: returns · Hands back typed domain models and collections
- Auth core → Session core: feeds · Supplies credentials and tokens to request sessions
- Session core → Resources: serves · Executes authenticated HTTP operations for resources
- Session core → Pagination: applies · Uses shared pagination while iterating result sets
- Resources → Projects: contains · Project manager endpoint
- Resources → Inventory: contains · Inventory manager endpoint
- Resources → Lots: contains · Lot manager endpoint
- Resources → Sheets: contains · Sheet manager endpoint
- Resources → Users: contains · User manager endpoint
- Resources → Tasks: contains · Task workflows and operations
- Resources → Smart datasets: contains · Specialized smart dataset workflow
- Resources → Reports: contains · Reports and templates
- Resources → Chats: contains · Chat domain operations
- Resources → Collections: maps to · Converts API payloads to collection entities
- Collections → Shared models: depends on · Shares base models, enums, identifiers, and types
- Utilities → Shared models: reuses · Applies shared patching and identifier conventions
- Utilities → Resources: supports · Convenience helpers above raw resource calls
- Docs tree → Albert client: documents · Explains client entry points and usage
- Docs tree → Auth core: documents · Covers authentication and SSO
- Docs tree → Resources: documents · Provides per-resource and per-collection references
- Layered tests → Collections: validates · Collection-level unit tests
- Layered tests → Resources: validates · Resource-level unit tests
- Layered tests → Session core: validates · Core transport and auth tests
- Layered tests → Utilities: validates · Utility helpers and patch behavior