albert 1.14.0__tar.gz → 1.16.0__tar.gz

albert-1.16.0/.github/workflows/release-please.yml

@@ -0,0 +1,19 @@
+name: release-please-poc
+
+on:
+  workflow_dispatch: {}
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@v4
+        with:
+          token: ${{ secrets.RELEASE_PLEASE_TOKEN }}
+          release-type: python
+          package-name: albert
+          target-branch: main

albert-1.16.0/.release-please-manifest.json

@@ -0,0 +1 @@
+{ ".": "1.14.1" }

albert-1.16.0/AGENTS.md

@@ -0,0 +1,163 @@
+# AGENTS
+
+This file is the single source of truth for coding-agent guidance in this repo.
+Follow these rules and patterns when making changes.
+
+## Rules
+
+### Changelog
+
+Any change that impacts SDK users must be added to the changelog under the
+appropriate release version, following Keep a Changelog 1.1.0.
+
+This includes breaking and non-breaking changes, such as API or naming changes,
+payload/behavior changes, deprecations, or internal refactors that affect
+user-visible behavior.
+
+When in doubt, add a changelog entry.
+
+### Using Numpy-Style Docstrings
+
+Any new public methods and classes in this repository should follow the
+Numpy-style docstring format. This ensures consistency and compatibility with
+mkdocstrings for automated documentation generation.
+
+Example:
+
+```python
+class Cas:
+    """
+    Represents a CAS entity.
+
+    Attributes
+    ----------
+    number : str
+        The CAS number.
+    name : str, optional
+        The name of the CAS.
+    """
+
+    def from_string(cls, *, number: str) -> "Cas":
+        """
+        Creates a Cas object from a string.
+
+        Parameters
+        ----------
+        number : str
+            The CAS number.
+
+        Returns
+        -------
+        Cas
+            The Cas object created from the string.
+        """
+        return cls(number=number)
+```
+
+When contributing new classes or methods, ensure all public members have
+properly formatted Numpy-style docstrings.
+
+## Design Principles
+
+1. **Keep it simple** - Avoid over-engineering. Make minimal changes. Don't create massive file diffs or edit unnecessary files. Validate at boundaries, trust internal code based on type hints.
+
+2. **Follow existing code patterns** - Check similar code in the codebase before writing new code. Match existing patterns rather than creating new ones.
+
+3. **YAGNI** - Only edit files absolutely necessary for the task. Don't add extra configuration unless explicitly needed. Prefer sensible defaults over configurable complexity.
+
+4. **Verify by running code** - When guessing about how something works, run the code and verify rather than assuming.
+
+5. Verify you haven't over-engineered the solution
+
+## Project Basics
+
+- Python: >=3.10 (type hints use modern syntax like list[str]).
+- Formatting and linting: Ruff (line length 99). CI and pre-commit enforce this.
+- Commit style: Conventional Commits (type(scope): summary), enforced by hooks.
+
+Useful commands:
+
+```bash
+./setup.sh
+uv run ruff format .
+uv run ruff check . --fix
+uv run pytest
+```
+
+## Repo Layout
+
+- src/albert/collections: API-facing collection classes that call endpoints.
+- src/albert/resources: Pydantic models representing API resources.
+- src/albert/core: Session, pagination, shared enums, and base classes.
+- src/albert/utils: Reusable helper utilities used by collections/resources.
+- docs/: mkdocs content (autogenerated from docstrings via mkdocstrings).
+- tests/: pytest suites, fixtures, and seed helpers.
+
+## API and Modeling Conventions
+
+- Collections inherit from BaseCollection and accept an AlbertSession.
+- Public collection methods should use @validate_call for runtime validation.
+- Resources use BaseAlbertModel/BaseResource with Pydantic Fields and aliases.
+- Keep API payloads in the wire format (camelCase) via Field(alias=...) and
+  model_dump(by_alias=True, mode="json", exclude_none=True).
+- Prefer narrow, explicit payload construction instead of dumping entire models.
+
+## Pagination
+
+Many list/search methods use AlbertPaginator (src/albert/core/pagination.py).
+Two modes exist:
+
+- Offset pagination (PaginationMode.OFFSET)
+  - Uses the offset query parameter.
+  - Defaults to limit=1000.
+  - Continues until Items is empty.
+
+- Key pagination (PaginationMode.KEY)
+  - Uses startKey and expects lastKey in the response.
+  - Page size defaults to backend behavior.
+
+Guidelines:
+
+- Expose a max_items parameter on public list/search methods where appropriate.
+  It is used to stop iteration early regardless of mode.
+- If a method returns an iterator, ensure the paginator is used consistently and
+  that the last_key can be inspected for resuming.
+- Use clear docstrings about offset/startKey behavior and max_items semantics.
+
+## Testing
+
+- Tests use pytest (see tests/).
+- Integration-style tests require environment variables:
+  - ALBERT_CLIENT_ID_SDK
+  - ALBERT_CLIENT_SECRET_SDK
+  - ALBERT_BASE_URL
+- The FakeAlbertSession in tests/utils supports unit-style tests without hitting
+  the network. Prefer it for pure behavior/unit tests.
+- Seed helpers live in tests/seeding.py and are reused across fixtures.
+
+## Documentation
+
+- Docs are built with mkdocs + mkdocstrings.
+- When adding a new resource/collection, add a docs page in docs/ and link it in
+  mkdocs.yml (alphabetical in nav).
+- Prefer docstrings for API reference content and keep them Numpy-style.
+
+## Release and Versioning
+
+- Version is defined in src/albert/**init**.py and read dynamically by Hatch.
+- Releases are created by tagging a version and drafting a GitHub release.
+
+## Do/Don’t Summary
+
+Do:
+
+- Add changelog entries for user-visible changes.
+- Keep docstrings Numpy-style for public APIs.
+- Use ruff for formatting/linting and respect line length 99.
+- Follow existing collection/resource patterns and naming.
+
+Don’t:
+
+- Add new public APIs without docstrings and tests.
+- Bypass Conventional Commits in commit messages.
+- Introduce new dependencies without strong justification.

{albert-1.14.0 → albert-1.16.0}/CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.15.0] - 2026-02-04
+
+### Added
+
+- Added `CustomTemplatesCollection.create` to support creating custom templates.
+- Added `CustomTemplatesCollection.update_acl` to support updating custom template ACLs.
+- Added `CustomTemplatesCollection.delete` to support deleting custom templates.
+
+### Changed
+
+- Standardized list-parameter normalization across collection filters so scalars and
+  iterables are handled consistently.
+
+### Fixed
+
+- Resolved custom-template ACL handling and schema parsing issues.
+- Defaulted missing custom-template workflow names to a sensible value.
+- Fixed enum parameter resolution to use session-level enum definitions.
+
 ## [1.14.0] - 2025-01-29
 
 ### Added

{albert-1.14.0 → albert-1.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: albert
-Version: 1.14.0
+Version: 1.16.0
 Summary: The official Python SDK for the Albert Invent platform.
 Project-URL: Homepage, https://www.albertinvent.com/
 Project-URL: Documentation, https://docs.developer.albertinvent.com/albert-python

albert-1.16.0/docs/assets/Albert_Wordmark_Mono_RGB_White.svg

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 450.4 124.83">
+  <defs>
+    <style>
+      .cls-1 {
+        fill: #fff;
+      }
+    </style>
+  </defs>
+  <path class="cls-1" d="M155.73,0v114.36h-18.95V0h18.95Z"/>
+  <path class="cls-1" d="M172.72,114.36V0h18.79v45.75c5.88-8.17,16.01-13.4,27.12-13.4,22.06,0,39.05,18.13,39.05,41.98s-16.99,41.99-39.05,41.99c-11.11,0-21.24-4.74-27.12-12.91v10.95h-18.79ZM214.7,49.5c-13.56,0-24.01,10.95-24.01,24.83s10.45,24.83,24.01,24.83,24.01-10.95,24.01-24.83-10.45-24.83-24.01-24.83Z"/>
+  <path class="cls-1" d="M342.63,95.57c-6.7,12.58-19.28,20.75-36.11,20.75-24.34,0-41.66-17.32-41.66-41.99s17.48-41.98,40.68-41.98,39.86,18.14,39.86,41.98c0,3.11-.17,5.23-.17,5.72h-61.59c.82,11.6,11.11,20.26,23.03,20.26,10.46,0,15.85-5.06,20.42-12.09l15.52,7.35h0ZM326.61,66.33c-1.14-10.62-9.96-18.46-21.4-18.46s-20.26,9.31-21.4,18.46h42.8Z"/>
+  <path class="cls-1" d="M394.25,49.8c-13.88,0-22.38,8.32-22.38,24.82v39.73h-18.79V34.31h18.62v13.72c3.92-9.31,14.12-15.55,28.02-15.55v17.32h-5.47M407.08,6.84h20.33v25.64h22.98v17.33h-22.98v34.14c0,9.55,4.24,13.79,13.43,13.79,3.18,0,6.9-.89,9.55-2.65v18.21c-3.36,1.77-8.49,3.18-15.56,3.18-17.33,0-27.76-10.78-27.76-28.82V6.84h0Z"/>
+  <path class="cls-1" d="M119.79,66.31V0h-17.74L0,114.36h24L102.29,26.62v39.7h-18.67c-8.94,0-16.92,5.34-20.34,13.59-3.42,8.25-1.55,17.68,4.77,24l14.47,14.47c6.32,6.32,15.74,8.19,23.99,4.77,8.26-3.42,13.27-11.41,13.27-20.34v-19.49h9.63v-17h-9.63,0ZM102.29,102.8c0,2.13-1.13,3.82-3.1,4.64-.67.28-1.34.42-2,.42-1.27,0-2.47-.51-3.46-1.5l-14.47-14.47c-1.5-1.5-1.9-3.5-1.09-5.47.81-1.97,2.5-3.1,4.64-3.1h19.49v19.49h0Z"/>
+</svg>

albert-1.16.0/docs/assets/Albert_Wordmark_RGB_Colour.svg

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 450.4 124.83">
+  <defs>
+    <style>
+      .cls-1 {
+        fill: #7d19fe;
+      }
+    </style>
+  </defs>
+  <path class="cls-1" d="M155.73,0v114.36h-18.95V0h18.95Z"/>
+  <path class="cls-1" d="M172.72,114.36V0h18.79v45.75c5.88-8.17,16.01-13.4,27.12-13.4,22.06,0,39.05,18.13,39.05,41.98s-16.99,41.99-39.05,41.99c-11.11,0-21.24-4.74-27.12-12.91v10.95h-18.79ZM214.7,49.5c-13.56,0-24.01,10.95-24.01,24.83s10.45,24.83,24.01,24.83,24.01-10.95,24.01-24.83-10.45-24.83-24.01-24.83Z"/>
+  <path class="cls-1" d="M342.63,95.57c-6.7,12.58-19.28,20.75-36.11,20.75-24.34,0-41.66-17.32-41.66-41.99s17.48-41.98,40.68-41.98,39.86,18.14,39.86,41.98c0,3.11-.17,5.23-.17,5.72h-61.59c.82,11.6,11.11,20.26,23.03,20.26,10.46,0,15.85-5.06,20.42-12.09l15.52,7.35h0ZM326.61,66.33c-1.14-10.62-9.96-18.46-21.4-18.46s-20.26,9.31-21.4,18.46h42.8Z"/>
+  <path class="cls-1" d="M394.25,49.8c-13.88,0-22.38,8.32-22.38,24.82v39.73h-18.79V34.31h18.62v13.72c3.92-9.31,14.12-15.55,28.02-15.55v17.32h-5.47M407.08,6.84h20.33v25.64h22.98v17.33h-22.98v34.14c0,9.55,4.24,13.79,13.43,13.79,3.18,0,6.9-.89,9.55-2.65v18.21c-3.36,1.77-8.49,3.18-15.56,3.18-17.33,0-27.76-10.78-27.76-28.82V6.84h0Z"/>
+  <path class="cls-1" d="M119.79,66.31V0h-17.74L0,114.36h24L102.29,26.62v39.7h-18.67c-8.94,0-16.92,5.34-20.34,13.59-3.42,8.25-1.55,17.68,4.77,24l14.47,14.47c6.32,6.32,15.74,8.19,23.99,4.77,8.26-3.42,13.27-11.41,13.27-20.34v-19.49h9.63v-17h-9.63,0ZM102.29,102.8c0,2.13-1.13,3.82-3.1,4.64-.67.28-1.34.42-2,.42-1.27,0-2.47-.51-3.46-1.5l-14.47-14.47c-1.5-1.5-1.9-3.5-1.09-5.47.81-1.97,2.5-3.1,4.64-3.1h19.49v19.49h0Z"/>
+</svg>

albert-1.16.0/docs/assets/favicon_bw.svg

@@ -0,0 +1,4 @@
+<svg width="32" height="32" viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg">
+<rect x="2" y="2" width="28" height="28" rx="14" fill="black"/>
+<path d="M22.2329 15.4998V7H19.9031L6.5 21.6587H9.65181L19.9358 10.4118V15.4998H17.4838C16.31 15.4998 15.2613 16.1836 14.8125 17.2417C14.3637 18.2997 14.6091 19.5071 15.4395 20.3175L17.3401 22.1722C18.1705 22.9817 19.4077 23.2221 20.4919 22.7841C21.577 22.3452 22.2348 21.3218 22.2348 20.1772V17.6796H23.5V15.5007H22.2348L22.2329 15.4998ZM19.9348 20.1763C19.9348 20.4495 19.7865 20.6662 19.528 20.7709C19.4403 20.8064 19.3517 20.8246 19.2649 20.8246C19.0988 20.8246 18.9402 20.7591 18.8105 20.6316L16.9099 18.7768C16.7121 18.5838 16.6599 18.3289 16.7672 18.0757C16.8745 17.8235 17.0956 17.6787 17.3765 17.6787H19.9358V20.1763H19.9348Z" fill="white"/>
+</svg>

{albert-1.14.0 → albert-1.16.0}/docs/index.md

@@ -1,8 +1,8 @@
 # Albert Python
 
 <div class="logo-wrapper">
-  <img src="assets/Wordmark_White.png" class="logo only-dark" alt="Albert Logo">
-  <img src="assets/Wordmark_Black.png" class="logo only-light" alt="Albert Logo">
+  <img src="assets/Albert_Wordmark_Mono_RGB_White.svg" class="logo only-dark" alt="Albert Logo">
+  <img src="assets/Albert_Wordmark_RGB_Colour.svg" class="logo only-light" alt="Albert Logo">
 </div>
 
 [![CI](https://img.shields.io/circleci/build/github/albert-labs/albert-python/main?label=CI)](https://app.circleci.com/pipelines/github/albert-labs/albert-python?branch=main)

{albert-1.14.0 → albert-1.16.0}/docs/styles/extra.css

@@ -1,6 +1,13 @@
 :root {
-  --md-primary-fg-color: #0149ff;
-  --md-accent-fg-color: #0149ff;
+  --md-primary-fg-color: #7D19FE;
+  --md-accent-fg-color: #7D19FE;
+}
+
+.md-typeset a:hover,
+.md-nav__link:hover,
+.md-nav--primary .md-nav__link:hover,
+.md-nav--secondary .md-nav__link:hover {
+  color: #0b62fe;
 }
 
 .logo-wrapper {

{albert-1.14.0 → albert-1.16.0}/mkdocs.yml

@@ -24,8 +24,8 @@ theme:
   name: "material"
   font:
     text: Aeonik Regular
-  logo: assets/Wordmark_White.png
-  favicon: assets/Vector_Favicon_Blue.svg
+  logo: assets/Albert_Wordmark_Mono_RGB_White.svg
+  favicon: assets/favicon_bw.svg
   features:
     - content.tabs.link # Tabs can contain links
     - content.code.annotate # Annotated code blocks (tooltips)

albert-1.16.0/release-please-config.json

@@ -0,0 +1,10 @@
+{
+  "release-type": "python",
+  "packages": {
+    ".": {
+      "package-name": "albert",
+      "version-file": "src/albert/__init__.py",
+      "include-v-in-tag": true
+    }
+  }
+}

{albert-1.14.0 → albert-1.16.0}/src/albert/__init__.py

@@ -4,4 +4,4 @@ from albert.core.auth.sso import AlbertSSOClient
 
 __all__ = ["Albert", "AlbertClientCredentials", "AlbertSSOClient"]
 
-__version__ = "1.14.0"
+__version__ = "1.16.0"

{albert-1.14.0 → albert-1.16.0}/src/albert/collections/attachments.py

@@ -9,7 +9,7 @@ from pydantic import validate_call
 from albert.collections.base import BaseCollection
 from albert.collections.files import FileCollection
 from albert.collections.notes import NotesCollection
-from albert.core.shared.identifiers import AttachmentId, DataColumnId, InventoryId
+from albert.core.shared.identifiers import AttachmentId, DataColumnId, InventoryId, ProjectId
 from albert.core.shared.types import MetadataItem
 from albert.resources.attachments import Attachment, AttachmentCategory
 from albert.resources.files import FileCategory, FileNamespace
@@ -288,3 +288,47 @@ class AttachmentCollection(BaseCollection):
 
         response = self.session.post(self.base_path, json=payload)
         return Attachment(**response.json())
+
+    @validate_call
+    def upload_and_attach_document_to_project(
+        self,
+        *,
+        project_id: ProjectId,
+        file_path: Path,
+    ) -> Attachment:
+        """Upload a file and attach it as a document to a project.
+
+        Args:
+            project_id: The Albert ID of the project (e.g. "PRO770").
+            file_path: Local path to the file to upload.
+
+        Returns:
+            The created Attachment record.
+        """
+        resolved_path = file_path.expanduser()
+        if not resolved_path.is_file():
+            raise FileNotFoundError(f"File not found at '{resolved_path}'")
+
+        content_type = mimetypes.guess_type(resolved_path.name)[0] or "application/octet-stream"
+        encoded_file_name = quote(resolved_path.name)
+        file_key = f"{project_id}/documents/original/{encoded_file_name}"
+
+        file_collection = self._get_file_collection()
+        with resolved_path.open("rb") as file_handle:
+            file_collection.sign_and_upload_file(
+                data=file_handle,
+                name=file_key,
+                namespace=FileNamespace.RESULT,
+                content_type=content_type,
+            )
+
+        payload = {
+            "parentId": project_id,
+            "category": AttachmentCategory.OTHER.value,
+            "name": encoded_file_name,
+            "key": file_key,
+            "nameSpace": FileNamespace.RESULT.value,
+        }
+
+        response = self.session.post(self.base_path, json=payload)
+        return Attachment(**response.json())

{albert-1.14.0 → albert-1.16.0}/src/albert/collections/btinsight.py

@@ -7,6 +7,7 @@ from albert.core.pagination import AlbertPaginator
 from albert.core.session import AlbertSession
 from albert.core.shared.enums import OrderBy, PaginationMode
 from albert.core.shared.identifiers import BTInsightId
+from albert.core.utils import ensure_list
 from albert.resources.btinsight import BTInsight, BTInsightCategory, BTInsightState
 
 
@@ -132,17 +133,17 @@ class BTInsightCollection(BaseCollection):
         """
         params = {
             "offset": offset,
-            "order": OrderBy(order_by).value if order_by else None,
+            "order": order_by,
             "sortBy": sort_by,
             "text": text,
-            "name": name,
+            "name": ensure_list(name),
         }
-        if state:
-            state = state if isinstance(state, list) else [state]
-            params["state"] = [BTInsightState(x).value for x in state]
-        if category:
-            category = category if isinstance(category, list) else [category]
-            params["category"] = [BTInsightCategory(x).value for x in category]
+
+        state_values = ensure_list(state)
+        params["state"] = state_values if state_values else None
+
+        category_values = ensure_list(category)
+        params["category"] = category_values if category_values else None
 
         return AlbertPaginator(
             mode=PaginationMode.OFFSET,

{albert-1.14.0 → albert-1.16.0}/src/albert/collections/cas.py

@@ -106,7 +106,7 @@ class CasCollection(BaseCollection):
             An iterator over Cas entities.
         """
 
-        params: dict[str, Any] = {"orderBy": order_by.value}
+        params: dict[str, Any] = {"orderBy": order_by}
         if id is not None:
             yield self.get_by_id(id=id)
             return

{albert-1.14.0 → albert-1.16.0}/src/albert/collections/companies.py

@@ -7,6 +7,7 @@ from albert.core.logging import logger
 from albert.core.pagination import AlbertPaginator, PaginationMode
 from albert.core.session import AlbertSession
 from albert.core.shared.identifiers import CompanyId
+from albert.core.utils import ensure_list
 from albert.exceptions import AlbertException
 from albert.resources.companies import Company
 
@@ -62,9 +63,8 @@ class CompanyCollection(BaseCollection):
             "dupDetection": "false",
             "startKey": start_key,
         }
-        if name:
-            params["name"] = name if isinstance(name, list) else [name]
-            params["exactMatch"] = str(exact_match).lower()
+        params["name"] = ensure_list(name)
+        params["exactMatch"] = str(exact_match).lower()
 
         return AlbertPaginator(
             mode=PaginationMode.KEY,