bridge.services package

Public Interface

This section documents user-facing interface of the bridge.services package (as defined in its __init__.py file).

Classes

GitHubRepoProvider()	Provide GitHub repository operations.
GitHubIngestor(owner, repo)	Ingest GitHub repository metadata via the GitHub REST API (raw JSON).
BiotoolsIngestor(biotools_id)	Ingest metadata from bio.tools ID via the bio.tools REST API.
HuggingFaceProvider([model, provider])	Hugging Face provider for chat-capable models using InferenceClient.
ChatMessage(**data)	A message in a chat conversation.
EuropePMCIngestor([pmid, pmcid, doi])	Ingest a publication record from Europe PMC using one or more identifiers.
SPDXLicenseIngestor(spdx_id)	Ingest license metadata from the SPDX license list by SPDX identifier.

Infrastructure layer that handles all interactions with external systems and services: repository and registry clients, repository operations, and an LLM provider.

class bridge.services.BiotoolsIngestor(biotools_id)

Bases: Ingestor

Ingest metadata from bio.tools ID via the bio.tools REST API.

Parameters:

biotools_id (str) – The bio.tools identifier for the tool to fetch.

async fetch()

Fetch the bio.tools entry for the specified tool ID.

Returns:

JSON metadata for the bio.tools entry.

Return type:

dict

class bridge.services.ChatMessage(**data)

Bases: BaseModel

A message in a chat conversation.

Parameters:

• role (Literal['system', 'user', 'assistant'])

• content (str)

role

The role of the message sender. One of: - “system”: Instructions or global context for the LLM assistant. - “user”: A message from the user. - “assistant”: A message from the LLM assistant.

Type:

Literal[“system”, “user”, “assistant”]

content

The content of the message.

Type:

str

content: str

role: Literal['system', 'user', 'assistant']

class bridge.services.EuropePMCIngestor(pmid=None, pmcid=None, doi=None)

Bases: Ingestor

Ingest a publication record from Europe PMC using one or more identifiers.

Parameters:

• pmid (str, optional) – PubMed identifier (e.g., “36173614”).

• pmcid (str, optional) – PubMed Central identifier (e.g., “PMC9903320”).

• doi (str, optional) – Digital Object Identifier (e.g., “10.1021/acs.jproteome.2c00457”).

async fetch()

Fetch the Europe PMC record matching the provided identifiers.

Returns:

The first matching Europe PMC record.

Return type:

dict

Raises:

• EuropePMCNotFoundError – If no record matches the provided identifiers.

• httpx.RequestError, httpx.HTTPStatusError – For network/HTTP issues.

class bridge.services.GitHubIngestor(owner, repo)

Bases: Ingestor

Ingest GitHub repository metadata via the GitHub REST API (raw JSON).

Parameters:

• owner (str)

• repo (str)

async fetch()

Fetch the full repository object (single endpoint).

Returns:

Raw JSON for the repository from GET /repos/{owner}/{repo}.

Return type:

dict

async fetch_github_pages()

Fetch the GitHub Pages information for the repository.

Returns:

Raw JSON for the GitHub Pages from GET /repos/{owner}/{repo}/pages.

Return type:

dict

async fetch_languages()

Fetch the programming languages used in the repository.

Returns:

Raw JSON for the languages from GET /repos/{owner}/{repo}/languages.

Return type:

dict | None

async fetch_latest_release()

Fetch the latest release (raw JSON) or return None if the repo has no releases.

Returns:

Latest release JSON, or None when GitHub returns 404 (no releases).

Return type:

dict | None

async fetch_readme()

Fetch the README content (decoded) or return None if not found.

Returns:

Decoded README content, or None if not found.

Return type:

str | None

async fetch_repo()

Fetch the full repository object (raw JSON).

Returns:

Raw JSON for the repository from GET /repos/{owner}/{repo}.

Return type:

dict

async get_user(username)

Fetch a GitHub user by username.

Parameters:

username (str) – GitHub username.

Returns:

Raw JSON for the user from GET /users/{username}.

Return type:

dict

class bridge.services.GitHubRepoProvider

Bases: RepoProvider

Provide GitHub repository operations.

apply_changes_and_push(repo_path, branch_name, file_changes)

Create a new branch from a local cloned repo, apply changes, and push.

Parameters:

• repo_path (str) – Path to the local cloned GitHub repository.

• branch_name (str) – Name of the new branch to create.

• file_changes (dict) – Dictionary mapping file paths to their new content.

clone_context(repo_full_name)

Use context manager to clone a GitHub repo into a temp dir and delete it afterward.

Parameters:

repo_full_name (str) – Full name of the repository (e.g., “owner/repo”).

async create_issue(owner, repo, title, body='', labels=None, assignees=None)

Create a new issue on a GitHub repository.

Parameters:

• owner (str) – GitHub user or organization that owns the repository.

• repo (str) – Repository name.

• title (str) – Title of the issue.

• body (str, optional) – Description of the issue.

• labels (list of str, optional) – List of label names to assign to the issue.

• assignees (list of str, optional) – List of GitHub usernames to assign to the issue.

Returns:

JSON response from the GitHub API representing the created issue.

Return type:

dict

Raises:

HTTPError – If the API request fails.

async create_pull_request(owner, repo, title, body, head_branch, base_branch)

Create a pull request via GitHub REST API.

Parameters:

• owner (str) – GitHub user or organization that owns the repository.

• repo (str) – Repository name.

• title (str) – Title of the pull request.

• body (str) – Description of the pull request.

• head_branch (str) – Name of the branch with the proposed changes.

• base_branch (str, optional) – Target branch to merge into (default is ‘main’).

Returns:

JSON response from the GitHub API representing the created pull request.

Return type:

dict

Raises:

HTTPError – If the API request fails.

async fork(owner, repo, replace_existing=True, wait_ready=True, max_wait=20)

Fork a GitHub repository (or return an existing fork).

Parameters:

• owner (str) – The owner of the repository to fork.

• repo (str) – The name of the repository to fork.

• replace_existing (bool) – Whether to delete an existing fork (if present) before creating a new one. Default is True.

• wait_ready (bool) – Whether to wait until the fork is fully ready. Default is True.

• max_wait (int) – Maximum number of seconds to wait for the fork to become ready. Default is 20.

Returns:

JSON metadata for the forked repository.

Return type:

dict

Raises:

HTTPError – If the fork operation fails.

class bridge.services.HuggingFaceProvider(model='Qwen/Qwen3-8B', provider='featherless-ai')

Bases: LLMProvider

Hugging Face provider for chat-capable models using InferenceClient. Supports models compatible with the chat.completions API.

Parameters:

• model (str) – The Hugging Face model identifier to use for chat generation. Default is “Qwen/Qwen3-8B” (https://huggingface.co/Qwen/Qwen2.5-7B).

• provider (HF_Provider) – The inference provider to use. Default is “featherless-ai”.

async generate(messages, **kwargs)

Generate a chat-based response from the model.

Parameters:

• messages (list[ChatMessage]) – A list of chat messages forming the conversation history.

• **kwargs – Additional generation parameters such as max_new_tokens and temperature.

Returns:

The generated chat message (response) from the model.

Return type:

ChatMessage

Raises:

• ValueError – If messages is empty.

• RuntimeError – If the model response is missing required fields.

• Exception – For any other errors during generation.

class bridge.services.SPDXLicenseIngestor(spdx_id)

Bases: Ingestor

Ingest license metadata from the SPDX license list by SPDX identifier.

This client fetches the JSON representation of a single license from the SPDX license list, which includes the canonical license text (licenseText), name, and other metadata.

Parameters:

spdx_id (str) – SPDX license identifier (e.g. "MIT", "GPL-3.0-only").

async fetch()

Fetch the SPDX license record for the specified SPDX identifier.

Returns:

JSON metadata for the SPDX license, including at least licenseId, name, and licenseText fields.

Return type:

dict

Raises:

• SPDXLicenseNotFoundError – If the SPDX service does not return a valid license record.

• httpx.RequestError, httpx.HTTPStatusError – For network/HTTP issues.

Subpackages

biotools	bio.tools integrations: async metadata ingestor from the bio.tools registry.
europe_pmc	Europe PMC integrations: async metadata ingestor from Europe PMC.
github	GitHub integrations: async metadata ingestor and repository provider for forking, cloning, pushing, and opening pull requests.
huggingface	Hugging Face integrations: model provider for accessing chat LLMs hosted on Hugging Face.
protocols	Protocols and base classes for services.
spdx	SPDX integrations: async metadata ingestor from SPDX license list.

Dependencies diagram

Each architecture diagram below visualizes the internal dependency structure of the bridge.services package. It shows how modules and subpackages within the package depend on each other, based on direct Python imports.

• Packages are shown as purple rectangles

• Modules are shown as pink rectangles

• Arrows (A → B) indicate that A directly imports B

Each subpackage’s diagram focuses only on its own internal structure, it does not include imports to or from higher-level packages (those appear in the parent package’s diagram).