Project namespaces

synth_ai.research.project_namespaces

Nested project namespaces on client.research.projects.

Classes

ResearchProjectsSetupAPI

Prepare projects for launch (onboarding + runnable setup).

Methods:

get

get(self, project_id: str) -> SmrProjectSetup

Return current setup/onboarding state for a project.

prepare

prepare(self, project_id: str) -> SmrProjectSetup

Run setup steps required before runs.check_preflight succeeds.

start_onboarding

start_onboarding(self, project_id: str) -> dict[str, Any]

Start the onboarding workflow for a new project.

complete_onboarding_step

complete_onboarding_step(self, project_id: str) -> dict[str, Any]

Mark an onboarding step complete or failed.

Args:

• project_id: Project identifier.
• step: Onboarding step name.
• status: Step status (for example "complete").
• detail: Optional structured detail payload.

dry_run_onboarding

dry_run_onboarding(self, project_id: str) -> dict[str, Any]

Validate onboarding prerequisites without mutating project state.

onboarding_status

onboarding_status(self, project_id: str) -> dict[str, Any]

Return onboarding progress and blocking issues.

ResearchProjectsWorkspaceAPI

Upload and download project workspace inputs and archives.

Methods:

get

get(self, project_id: str) -> ProjectWorkspaceProjection

Return the current workspace projection for a project.

upload

upload(self, project_id: str, files: Iterable[Mapping[str, object]]) -> WorkspaceUploadResult

Upload workspace files from in-memory file descriptors.

Args:

• project_id: Project identifier.
• files: Iterable of file mappings (path, content, metadata).

upload_directory

upload_directory(self, project_id: str, directory: str | PathLike[str]) -> WorkspaceUploadResult

Upload an entire local directory into the project workspace.

download

download(self, project_id: str, destination: str) -> dict[str, Any]

Download the project workspace archive to a local path.

inputs

inputs(self, project_id: str) -> WorkspaceInputsState

Return workspace input state (uploaded files, git linkage).

upload_url

upload_url(self, project_id: str) -> dict[str, Any]

Mint a presigned URL for direct workspace archive upload.

confirm_push

confirm_push(self, project_id: str) -> dict[str, Any]

Confirm a git push completed and attach the uploaded archive.

Args:

• project_id: Project identifier.
• commit_sha: Git commit SHA for the pushed workspace.
• archive_key: Storage key returned from upload_url.

ResearchProjectsReposAPI

Attach external source repositories to a project workspace.

Methods:

attach

attach(self, project_id: str, url: str) -> dict[str, Any]

Attach a git repository as a workspace input source.

Args:

• project_id: Project identifier.
• url: Repository clone URL.
• default_branch: Branch to track when no commit is pinned.
• commit_sha: Optional pinned commit SHA.

GitCommitRow

One commit summary row from the project git server.

Methods:

from_wire

from_wire(cls, payload: object) -> GitCommitRow

Build a typed commit summary from a git-server response.

GitBranchRow

One unmerged-branch summary row from the project git server.

Methods:

from_wire

from_wire(cls, payload: object) -> GitBranchRow

Build a typed branch summary from a git-server response.

GitRepoStatus

Project git repo status: HEAD, recent commits, unmerged branches, tree.

Methods:

from_wire

from_wire(cls, payload: object) -> GitRepoStatus

Build a typed repository status projection from a git-server response.

GitFileContent

One file read from the project git server (utf-8 or base64 content).

Methods:

from_wire

from_wire(cls, payload: object) -> GitFileContent

Build a typed file-content result from a git-server response.

GitPullRequestRow

One GitHub pull-request row (raw GitHub payload preserved in raw).

Methods:

from_wire

from_wire(cls, payload: object) -> GitPullRequestRow

Build a typed pull-request summary from a git-server response.

ResearchProjectsGitPullRequestsAPI

Read pull requests on the project’s bound GitHub repo.

Methods:

list

list(self, project_id: str) -> tuple[GitPullRequestRow, ...]

List pull requests (state in open/closed/all, limit 1-100).

Backend route: GET /smr/projects/{project_id}/git/pull-requests.

ResearchProjectsGitAPI

Project git source connection, metadata, and read-only git-server views.

Read bindings cover the mounted GET routes only: status, tree, file, diff, and pull-request listing. Branch/commit creation, push, file writes, and PR create/comment are POST routes and are intentionally not bound here.

Methods:

pull_requests

pull_requests(self) -> ResearchProjectsGitPullRequestsAPI

Read pull requests on the project’s bound repo.

status

status(self, project_id: str) -> GitRepoStatus

Read repo status: HEAD, recent commits, unmerged branches, tree.

Backend route: GET /smr/projects/{project_id}/git/status.

tree

tree(self, project_id: str) -> tuple[str, ...]

List tree entry paths at a ref, optionally under a path prefix.

Backend route: GET /smr/projects/{project_id}/git/tree.

file

file(self, project_id: str, path: str) -> GitFileContent

Read one file blob at a ref.

Backend route: GET /smr/projects/{project_id}/git/file.

diff

diff(self, project_id: str) -> dict[str, Any]

Read the diff between two refs (optionally scoped to one path).

Backend route: GET /smr/projects/{project_id}/git/diff.

get

get(self, project_id: str) -> dict[str, Any]

Return git metadata for the project workspace.

connect

connect(self, project_id: str) -> Any

Connect or update the project’s git code source.

ResearchProjectsCodeAPI

Download project code archives.

Methods:

download

download(self, project_id: str, destination: str) -> dict[str, Any]

Download the project code archive to a local path.

ResearchProjectsObjectivesAPI

Directed effort outcomes and objective status for a project.

Methods:

list_directed_effort_outcomes

list_directed_effort_outcomes(self, project_id: str) -> List[dict[str, Any]]

List directed effort outcomes (legacy alias for directed objectives).

list

list(self, project_id: str) -> List[dict[str, Any]]

List objectives for a project, optionally scoped to a run.

get_status

get_status(self, project_id: str, objective_id: str, **kwargs: Any) -> dict[str, Any]

Return status fields for a single objective.

get_progress

get_progress(self, project_id: str, objective_id: str) -> dict[str, Any]

Return progress metrics for a single objective.

ResearchProjectsMilestonesAPI

Project and run-scoped milestones.

Methods:

list

list(self, project_id: str) -> List[dict[str, Any]]

List milestones for a project, optionally filtered to a run.

ResearchProjectsRunsAPI

List runs belonging to a project.

Methods:

list

list(self, project_id: str, **kwargs: Any) -> List[dict[str, Any]]

List runs for a project.

Args:

• project_id: Project identifier.
• active_only: When True, return only non-terminal runs.