Find Similar Files

The find_similar resource submits and manages find-similar jobs. It is available via client.find_similar.

Find-similar jobs take source identifiers, such as DOIs, internal IDs, or open access IDs, and search for the corresponding file in two places:

Locally, among indexed files already available in Elise.
Remotely, through bibliographic sources such as Arxiv and PubMed.

When a remote source is found but the full file is not available as open access, the job returns a metadataOnly match instead of a local file match.

import asyncio
from biolevate import BiolevateClient, SourceIdentifiers

async def main():
    async with BiolevateClient(
        base_url="https://<api-domain>",
        token="<your-pat>",
    ) as client:
        job = await client.find_similar.create_job(
            source_identifiers=[
                SourceIdentifiers(doi="10.1000/example"),
            ]
        )
        print(f"Job created: {job.job_id} (status: {job.status})")

asyncio.run(main())

Methods

`create_job()`

Submit a new find-similar job.

from biolevate import SearchSources, SourceIdentifiers

# Convenience form
job = await client.find_similar.create_job(
    source_identifiers=[
        SourceIdentifiers(doi="10.1000/example"),
        SourceIdentifiers(open_access_id="PMC1234567"),
    ]
)

# Or pass a pre-built request
job = await client.find_similar.create_job(
    search_sources=SearchSources(
        source_identifiers=[SourceIdentifiers(id="internal-source-id")]
    )
)

Parameter	Type	Default	Description
`source_identifiers`	`list[SourceIdentifiers] \| None`	`None`	Sources to match by DOI, ID, or open access ID
`search_sources`	`SearchSources \| None`	`None`	Pre-built request object

Returns FindSimilarJob

Raises AuthenticationError, APIError

`get_job()`

Get a find-similar job by ID. Completed jobs include result and statistics, with local file matches in files and remote metadata-only matches in metadataOnly.

job = await client.find_similar.get_job(job_id)
print(job.status)

if job.statistics:
    print(job.statistics.total_file_matches)

Parameter	Type	Description
`job_id`	`str`	UUID of the find-similar job

Returns FindSimilarJob

Raises NotFoundError, AuthenticationError, APIError

`list_jobs()`

List all find-similar jobs for the current user.

page = await client.find_similar.list_jobs(page=0, page_size=20)
for job in page.data:
    print(f"{job.job_id}: {job.status}")

Parameter	Type	Default	Description
`page`	`int`	`0`	Page number (0-based)
`page_size`	`int`	`20`	Number of jobs per page
`sort_by`	`str \| None`	`None`	Field to sort by
`sort_order`	`str`	`"asc"`	Sort direction

Returns FindSimilarJobPage

Raises AuthenticationError, APIError

Reading Results

Each source can produce local files, remote metadataOnly matches, or both. A metadataOnly entry means the bibliographic record was found remotely, but no open access file was available to attach as a file match.

job = await client.find_similar.get_job(job_id)

for source_match in job.result or []:
    source = source_match.source
    print(f"Source DOI: {source.doi if source else 'unknown'}")

    for file_match in source_match.files or []:
        print(f"Local file: {file_match.name} ({file_match.file_id})")

    for metadata_match in source_match.metadata_only or []:
        print(f"Remote metadata-only result: {metadata_match.search_result_id}")

Full Example — Create, Poll, and Read Matches

import asyncio
from biolevate import BiolevateClient, SourceIdentifiers

TERMINAL_STATUSES = {"COMPLETED", "FAILED"}

async def main():
    async with BiolevateClient(
        base_url="https://<api-domain>",
        token="<your-pat>",
    ) as client:
        job = await client.find_similar.create_job(
            source_identifiers=[SourceIdentifiers(doi="10.1000/example")]
        )
        print(f"Job created: {job.job_id}")

        while True:
            job = await client.find_similar.get_job(job.job_id)
            if job.status in TERMINAL_STATUSES:
                break
            await asyncio.sleep(3)

        if job.status == "COMPLETED":
            print(f"Local matches: {job.statistics.total_file_matches if job.statistics else 0}")
            print(f"Metadata-only matches: {job.statistics.total_metadata_only_matches if job.statistics else 0}")
            for source_match in job.result or []:
                for file_match in source_match.files or []:
                    print(f"- {file_match.name}: {file_match.path}")
                for metadata_match in source_match.metadata_only or []:
                    print(f"- metadata only: {metadata_match.search_result_id}")

asyncio.run(main())

Next Steps

Files — index files before matching against local content
Find Similar guide — the same workflow with REST examples
API Reference for complete endpoint schemas

Methods​

create_job()​

get_job()​

list_jobs()​

Reading Results​

Full Example — Create, Poll, and Read Matches​

Next Steps​