# PipeBio Python SDK

> A Python SDK for the PipeBio platform - an integrated bioinformatics platform
> for large molecule and peptide discovery. This file is auto-generated from the
> SDK source by scripts/generate_llms_txt.py; do not edit by hand.

## Getting started

- Install: `pip install pipebio` (or `uv pip install pipebio`).
- Authenticate: set the `PIPE_API_KEY` environment variable (get a key from the
  `me` page of your PipeBio instance), or place it in a local `.env` file.
- Create a client and call resource services:

    from pipebio.pipebio_client import PipebioClient
    client = PipebioClient(url="https://app.pipebio.com")
    client.entities.get(entity_id)

- Escape hatch: for endpoints not yet wrapped by the SDK, use the authenticated
  `client.session` directly, e.g. `client.session.get("me")`.

## API reference

### pipebio.pipebio_client

- class `PipebioClient`: Authenticated client for the PipeBio API.
  - `PipebioClient.export(self, entity_id: str, format: pipebio.models.export_format.ExportFormat, destination_folder: Optional[str] = None, destination_filename: Optional[str] = None, params: Optional[dict] = None) -> List[str]`: Export an entity to a file and download the result.
  - `PipebioClient.get_user(self) -> Dict[str, Any]`: Fetch the authenticated user from the ``me`` endpoint.
  - property `PipebioClient.is_aws -> bool`: Whether the connected PipeBio instance runs on AWS.
  - `PipebioClient.sanitize_baseurl(url: str) -> str`: Validate and normalise a PipeBio base URL.
  - `PipebioClient.set_correlation_id(self, correlation_id: str) -> None`: Set a correlation ID sent as an X-Correlation-Id header on every subsequent API request.
  - `PipebioClient.upload_file(self, file_name: str, absolute_file_location: str, parent_id: str, project_id: str, organization_id: Optional[str] = None, details: Optional[List[pipebio.models.upload_detail.UploadDetail]] = None, file_name_id: Optional[str] = None, poll_job: bool = False, on_progress: Optional[Callable[[int, int], NoneType]] = None) -> Dict[str, Any]`: Upload a single local file as a new document.
  - `PipebioClient.upload_files(self, absolute_folder_path: str, parent_id: str, project_id: str, organization_id: Optional[str] = None, filename_pattern: Optional[str] = None, poll_jobs: bool = False) -> List[Dict[str, Any]]`: Upload multiple files from a folder, one document per file.
  - `PipebioClient.upload_files_as_zip(self, absolute_folder_path: str, parent_id: str, project_id: str, organization_id: Optional[str] = None, filename_pattern: Optional[str] = None, poll_jobs: bool = False) -> Dict[str, Any]`: Zip the matching files in a folder and upload them as one document.


### pipebio.entities

- class `Entities`: Wraps the ``entities`` API endpoints.
  - `Entities.convert_pandas_type(pandas_type: str) -> pipebio.models.table_column_type.TableColumnType`: (no description)
  - `Entities.create_file(self, project_id: str, name: str, parent_id: str = None, entity_type: pipebio.models.entity_types.EntityTypes = <EntityTypes.SEQUENCE_DOCUMENT: 'SEQUENCE_DOCUMENT'>, visible: bool = False) -> dict`: Create a new entity (document or folder).
  - `Entities.create_folder(self, project_id: str, name: str, parent_id: str = None, visible: bool = False) -> dict`: Create a new folder entity.
  - `Entities.delete(self, entity_ids: list) -> None`: Delete one or more entities.
  - `Entities.download_original_file(self, entity_id: str, destination_filename: str) -> str`: Download the original uploaded file for a document.
  - `Entities.get(self, entity_id: str) -> dict`: Fetch a single entity by id.
  - `Entities.get_all(self, entity_ids: List[str]) -> List[dict]`: Fetch multiple entities in parallel.
  - `Entities.get_fields(self, entity_id: str, ignore_id: bool = False) -> List[pipebio.column.Column]`: Return the column fields (schema) for a document.
  - `Entities.get_fields_for_all_entities(self, entity_ids: List[str]) -> List[pipebio.column.Column]`: (no description)
  - `Entities.get_file_handle(self, absolute_file_path: str) -> pandas.core.frame.DataFrame`: Read a tabular file into a pandas DataFrame.
  - `Entities.mark_file_visible(self, entity_summary: pipebio.models.upload_summary.UploadSummary) -> dict`: Make a previously hidden entity visible in the UI.
  - `Entities.merge(self, entity_id: str, assay_absolute_file_path: str, assay_column: str, entity_column: str, append_unmatched_rows: bool = False, timeout_seconds: int = 3600) -> Dict[str, Any]`: Merge tabular assay data into a sequence document.
  - `Entities.merge_fields(schema_a: List[pipebio.column.Column], schema_b: List[pipebio.column.Column]) -> List[pipebio.column.Column]`: (no description)


### pipebio.jobs

- class `Jobs`: Wraps the ``jobs`` API endpoints.
  - `Jobs.bulk_update(self, updates: List[dict]) -> None`: Update multiple jobs in a single request.
  - `Jobs.cancel(self, job_id: str = None) -> None`: Cancel a running or queued job.
  - `Jobs.create(self, shareable_id: str, job_type: pipebio.models.job_type.JobType, name: str, input_entity_ids: List[str], owner_id: str = None, params=None, poll_jobs: bool = False, client_side: bool = False, messages: Optional[List[str]] = None, status: Optional[pipebio.models.job_status.JobStatus] = None, allow_deleted_entities: bool = False) -> str`: Create a new job.
  - `Jobs.create_signed_upload(self, file_name: str, parent_id: str, project_id: str, details: List[pipebio.models.upload_detail.UploadDetail], file_name_id: str, organization_id: str = None) -> dict`: Create a signed upload slot for a new sequence document.
  - `Jobs.get(self, job_id: str = None) -> Dict[str, Any]`: Fetch a single job by id.
  - `Jobs.list(self, organization_id: str = None, page_offset: Optional[int] = None, page_limit: Optional[int] = None, sort: Optional[str] = None, include_cols: Optional[List[str]] = None, include_total_count: Optional[bool] = None, filters: Optional[List[pipebio.models.job_filter.JobFilter]] = None) -> Dict[str, Any]`: List jobs with optional pagination, sorting and filtering.
  - `Jobs.poll_job(self, job_id: str = None, timeout_seconds: Optional[int] = None) -> Dict[str, Any]`: Poll a job until it completes or fails.
  - `Jobs.poll_jobs(self, job_ids: List[str], timeout_seconds: Optional[int] = None) -> List[Dict[str, Any]]`: Poll multiple jobs in parallel until they complete or fail.
  - `Jobs.reschedule(self, job_id: str = None, automated: Optional[bool] = None) -> Dict[str, Any]`: Re-run a failed job.
  - `Jobs.set_complete(self, messages: List[str] = None, output_entity_ids: List[str] = None, output_links: List[pipebio.models.output_link.OutputLink] = None) -> requests.models.Response`: Mark the current job complete (status COMPLETE, progress 100).
  - `Jobs.start_import_job(self, file_size: Optional[int] = None) -> requests.models.Response`: Trigger an import job run via the job-processing engine.
  - `Jobs.update(self, status: pipebio.models.job_status.JobStatus, progress=None, messages: List[str] = None, output_entity_ids: List[str] = None, output_links: List[pipebio.models.output_link.OutputLink] = None, allow_deleted_entities: bool = False) -> requests.models.Response`: Update the current job's status.
  - `Jobs.upload_data_to_signed_url(self, absolute_file_location: str, signed_url: str, signed_headers: Any) -> None`: Upload a file to a signed URL (small-file path).


### pipebio.sequences

- class `ImportError`: Raised when a sequence import fails irrecoverably.

- class `Sequences`: Wraps the sequence extract/import API endpoints.
  - `Sequences.convert_parquet_to_tsv(path_to_parquet_data: str, path_to_tsv_file: str, skip_header: bool = False, chunk_size: int = 10000) -> None`: Convert a Parquet shard to TSV, appending to the output file.
  - `Sequences.create_signed_upload(self, entity_id: str, retries: int = 5) -> dict`: Create a signed upload slot for sequence data.
  - `Sequences.download(self, entity_id: str, destination: str = None, sort: List[pipebio.models.sort.Sort] = None, query: str = None, include_cols: Optional[List[str]] = None, exclude_cols: Optional[List[str]] = None, limit: int = None, allow_deleted: bool = True) -> str`: Download the sequences of a single document to a local file.
  - `Sequences.download_to_memory(self, entity_ids: List[str]) -> Dict[str, Any]`: Download several documents and return their sequences in memory.
  - `Sequences.get_joined_cols(cols, parameter)`: (no description)
  - `Sequences.import_signed_upload(self, import_details: Dict, allow_deleted_entity: bool = True, remaining_retries: int = 10) -> bool`: Trigger import of a previously uploaded file, polling to completion.
  - `Sequences.maybe_compress_file(file_path) -> str`: (no description)
  - `Sequences.upload(self, url: str, file_path: str, headers: dict = None, retries: int = 5) -> None`: Upload a local file to a signed URL, retrying on connection errors.


### pipebio.workflows

- class `Workflows`: Wraps workflow execution on top of the ``jobs`` API.
  - `Workflows.run_workflow(self, project_id: str, workflow_id: str, name: str, input_entity_ids: List[str], organization_id: Optional[str] = None, target_folder_id: Optional[str] = None, params: Optional[Dict[str, Any]] = None, poll_job: bool = False) -> Dict[str, Any]`: Resolve and run a saved workflow.


### pipebio.shareables

- class `Shareables`: Wraps the ``shareables`` API endpoints.
  - `Shareables.create_project(self, name: str, owner_id: str) -> dict`: Create a new project shareable.
  - `Shareables.get_project(self, project_name: str) -> dict`: Find a project by its exact name.
  - `Shareables.list(self) -> List[dict]`: List the shareables (projects) the user can access.
  - `Shareables.list_entities(self, shareable_id: str) -> List[dict]`: List the entities contained in a shareable.


### pipebio.organization_lists

- class `OrganizationLists`: Wraps the ``organizations/{id}/lists`` API endpoints.
  - `OrganizationLists.get_germlines(self, organization_id: str = None) -> List[Dict[str, Any]]`: List the germline lists for an organization.
  - `OrganizationLists.get_scaffolds(self, organization_id: str = None) -> Any`: List the scaffold lists for an organization.
  - `OrganizationLists.get_workflow(self, workflow_id: str, organization_id: str = None) -> Any`: Fetch a single workflow list by id.


### pipebio.uploader

- class `Uploader`: Buffered uploader that writes schema-applied rows to a PipeBio document.
  - `Uploader.add_natural_sort_columns(self, schema: List[pipebio.column.Column]) -> List[pipebio.column.Column]`: Inserts columns for natural sort.
  - `Uploader.build_no_sort_cols()`: (no description)
  - `Uploader.build_unique_schema(self) -> List[Dict[str, Any]]`: Return the schema as de-duplicated name/type/description dicts.
  - `Uploader.cols_to_header_line(self) -> str`: Return the tab-separated header line for the current schema.
  - `Uploader.escape_tsv_within_tsv(tsv_line)`: We encode annotations as a tsv within the larger tsv document, therefore we need to escape tsv chartacters.
  - `Uploader.fill_string_sort_cell(value: str, kind: <RendererCodes.medianv1: 'medianv1'> = None)`: (no description)
  - `Uploader.get_sort_kind(description: Optional[str]) -> pipebio.models.render_codes.RendererCodes`: (no description)
  - `Uploader.get_type(self) -> pipebio.models.entity_types.EntityTypes`: Return the inferred document type (alignment vs the configured type).
  - `Uploader.make_line(self, row_data: dict) -> str`: Applies the columns to the row data.
  - `Uploader.needs_natural_sort(self, column: pipebio.column.Column) -> bool`: Some columns are blacklisted as not needing sort. Other more uncommon columns can mark they do not need sort
  - `Uploader.upload(self, allow_empty: bool = False) -> bool`: Flush all buffered rows and wait for the uploads to finish.
  - `Uploader.upload_if_ready(self, force: bool = False) -> None`: Upload the current chunk if it is full (or ``force`` is set).
  - `Uploader.write_data(self, data: dict) -> None`: Write a single row, applying the schema and buffering for upload.


### pipebio.multipart_upload

- `upload_multipart_aws(session: requests_toolbelt.sessions.BaseUrlSession, absolute_file_location: str, file_name: str, parent_id: str, project_id: str, organization_id: str, details: Optional[List[pipebio.models.upload_detail.UploadDetail]] = None, file_name_id: Optional[str] = None, on_progress: Optional[Callable[[int, int], NoneType]] = None) -> dict`: Upload a large file to an AWS instance using S3 multipart upload.

### pipebio.column

- class `BooleanColumn`: (no description)
  - `BooleanColumn.parse(self, value)`: (no description)
  - `BooleanColumn.to_json(self) -> dict`: (no description)

- class `Column`: (no description)
  - `Column.parse(self, value)`: (no description)
  - `Column.to_json(self) -> dict`: (no description)

- class `ConstantColumn`: (no description)
  - `ConstantColumn.parse(self, value)`: (no description)
  - `ConstantColumn.to_json(self) -> dict`: (no description)

- class `IntegerColumn`: (no description)
  - `IntegerColumn.parse(self, value)`: (no description)
  - `IntegerColumn.to_json(self) -> dict`: (no description)

- class `NumberColumn`: (no description)
  - `NumberColumn.parse(self, value)`: (no description)
  - `NumberColumn.to_json(self) -> dict`: (no description)
  - `NumberColumn.write_for_db(value: Union[float, str]) -> str`: Writes in a value so it can be parsed.

- class `StringColumn`: (no description)
  - `StringColumn.parse(self, value)`: (no description)
  - `StringColumn.to_json(self) -> dict`: (no description)

- `strtobool(val: str) -> bool`: Convert a string representation of truth to True or False.
- `take_uniques(maybe_with_dupes: List[<built-in function any>]) -> List[<built-in function any>]`: Like doing set(columns) but has the benefit of preserving order.

### pipebio.models.job_type

- enum `JobType`: The type of job to run.
  - values: AmpliconOverlapAssemblyJob, ImportJob, FlashJob, AnnotateJob, AnnotateForBenchlingJob, CompareJob, ClusterJob, DetectMixedWellsJob, ChartJob, AlignJob, AlignNumberedJob, AlignAnchoredJob, SubtractionJob, AddToSequenceStoreJob, QuerySequenceStoreJob, RemoveSequencesFromStoreJob, ExtractJob, ExtractAndStitchJob, ConcatenateJob, RestrictionClone, CodonOptimiseJob, ExportJob, AddColumnsJob, RemoveColumnsJob, SangerAssemblyJob, SangerAlignmentJob, SangerSecondaryPeaksJob, WorkflowJob, ExtractMostAbundantJob, QcFor10xJob, TrimJob, CollapseUmiJob, PairJob, SummaryJob, NumberSequencesJob, ReconstructSequenceJob, MoveEntitiesJob, BackTranslateJob, SequencingQcJob, SynthesisCheckJob, DegenerateNucleotideSequencesJob, DifferentialEnrichmentJob, ReverseComplementJob, HumanizeJob, ExtractDifferentiallyEnrichedJob, DiversityAnalysisJob, AlignmentBasedDiversitySelectionJob, LiabilityBasedSelectionJob, AggregationJob, ProteinPropertiesJob, ClusterAssemblyJob, DemuxJob, BulkRemoveAnnotationsJob, OverlapAssemblyJob, AddToBenchlingJobV2, RuleBasedSelectionJob, ChartSummaryJob, FindRareAaJob, EnaImportJob, MlPredictAntibodyStructureJob, AddToLabkeyJob, TrimUmiJob, CollapsePcrDuplicatesJob, ExtractConsensusJob, HumannessJob, InsertMakerJob, PseudogeneFinderJob, DevelopabilityJob, HitpickJob, HumanizationJob, AwsImportJob, Merge10xSequencesAndAssayDataJob, SplitDocumentJob, CorrectLiabilitiesJob, FindAndReplaceJob, BindingPredictionJob, VariantGenerationJob, ProteinMpnnJob, EpianalyzerJob, ExtractUmiByAnchorJob, ClusterSequencesJob, DeduplicateUmiJob, DiamondAlignJob, LibraryDiversityJob, FastQcJob, FastpMergeJob, MergeAssayDataJob, CopyJob, QueryStoreJob, AddToBenchlingJob, MlHitpickingJob, StoreV3AddFromDocumentJob, StoreV3QueryJob, PluginJob


### pipebio.models.job_status

- enum `JobStatus`: The status of a job in its lifecycle.
  - values: QUEUED, RUNNING, FAILED, COMPLETE, CANCELLED


### pipebio.models.job_filter

- class `JobFilter`: Represents a single filter condition for querying jobs.
  - `JobFilter.to_json(self) -> dict`: Serialize to API request format.


### pipebio.models.entity_types

- enum `EntityTypes`: The type of an entity in the PipeBio document tree.
  - values: FOLDER, REPORT, CLUSTER, CLUSTER_V3, COMPARISON, SEQUENCE_DOCUMENT, ALIGNMENT, PDF, IMAGE, UNKNOWN


### pipebio.models.export_format

- enum `ExportFormat`: A file format an entity can be exported to.
  - values: FASTA, FASTQ, GENBANK, TSV, CSV, EXCEL, PARQUET, DUCKDB


### pipebio.models.table_column_type

- enum `TableColumnType`: The data type of a document column.
  - values: INTEGER, STRING, BYTES, BOOLEAN, NUMERIC, BIGNUMERIC, FLOAT, FLOAT64, ARRAY, STRUCT, TIMESTAMP


### pipebio.models.render_codes

- enum `RendererCodes`: Hints that control column rendering and sort behaviour in the UI.
  - values: idcol, hidden, medianv1, natural


### pipebio.models.sort

- class `Sort`: (no description)
  - `Sort.from_json(json: dict)`: (no description)
  - `Sort.to_json(self)`: (no description)
