Project¶

class Project:
    """
    User-friendly wrapper for a Nexus project.

    This class provides a synchronous interface to project operations,
    including listing collections, creating new collections, and displaying
    project information. It acts as a facade over AsyncProject to provide
    a simpler, synchronous API.

    Attributes:
        uuid: Unique identifier for the project
        name: Human-readable name of the project
        owner_id: ID of the project owner
        created_at: Project creation timestamp
        updated_at: Last modification timestamp
        metadata: Dictionary containing project metadata
        project_uuid: Alias for uuid (for backward compatibility)
        project_name: Alias for name (for backward compatibility)
    """

    def __init__(
        self,
        project_data: Dict[str, Any],
        nexus_client: Any,  # NexusClient from parent
        runner: Any,  # _LoopThread from parent Nexus
        async_project: AsyncProject,  # AsyncProject instance (required)
    ):
        """
        Initialize a Project wrapper.

        Args:
            project_data: Project information dictionary
            nexus_client: The underlying NexusClient instance (from parent)
            runner: The loop thread for executing async operations (from parent Nexus)
            async_project: AsyncProject instance (required)
        """
        # Store reference to parent Nexus's runner (shared loop)
        self._nexus_client = nexus_client
        self._runner = runner

        # Store AsyncProject instance and extract attributes
        self._async = async_project
        self._uuid = async_project.id
        self.name = async_project.name
        self.owner_id = async_project.owner_id
        self.created_at = async_project.created_at
        self.updated_at = async_project.updated_at
        self.metadata = async_project.metadata

        # Initialize logger after name is set (instance-specific namespace)
        self.logger = get_logger(f"{__name__}.{self.name}")

        # Store project_data for Collection instantiation
        self._project_data = project_data

    @property
    def id(self) -> str:
        """Stable project identifier (value may be a UUID)."""
        return self._uuid

    @property
    def uuid(self) -> str:
        """Alias for id (UUID), same as :attr:`AsyncProject.uuid`."""
        return self._uuid

    def _handle_auth_errors(self, e: Exception) -> None:
        """Delegate to :func:`miura.api.auth_errors.handle_auth_errors`."""
        from miura.api.auth_errors import handle_auth_errors

        handle_auth_errors(self.logger, e)

    def list_collections(
        self,
        retry_policy: Optional[RetryPolicy] = None,
        timeouts: Optional[Timeouts] = None,
        hooks: Optional[ApiHooks] = None,
    ) -> List["Collection"]:
        """
        List all collections in this project.

        Returns:
            List of Collection wrapper objects

        Raises:
            RuntimeError: If AsyncProject is not available
            Exception: If the API request fails or authentication errors occur
        """
        from .collection import Collection
        from miura.api.collection import AsyncCollection

        try:
            future = self._runner.submit(
                self._async.list_collections(
                    retry_policy=retry_policy,
                    timeouts=timeouts,
                    hooks=hooks,
                )
            )
            collection_infos = future.result()

            # Convert CollectionInfo to Collection wrappers
            collections = []
            for collection_info in collection_infos:
                # Convert CollectionInfo to dict format
                collection_data = {
                    "uuid": collection_info.id,
                    "name": collection_info.name,
                    "created_at": collection_info.created_at,
                    "updated_at": collection_info.updated_at,
                    "metadata": collection_info.metadata,
                }

                # Create AsyncCollection from collection data
                async_collection = AsyncCollection(
                    collection_data=collection_data,
                    project=self._async,
                    nexus_client=self._nexus_client,
                )

                # Wrap in Collection
                collection = Collection(
                    collection_data=collection_data,
                    project_data=self._project_data,
                    nexus_client=self._nexus_client,
                    runner=self._runner,
                    async_collection=async_collection,
                )
                collections.append(collection)

            return collections
        except Exception as e:
            self._handle_auth_errors(e)
            self.logger.error(f"Error in list_collections: {e}")
            raise

    def get_collection(
        self,
        collection_name: str,
        retry_policy: Optional[RetryPolicy] = None,
        timeouts: Optional[Timeouts] = None,
        hooks: Optional[ApiHooks] = None,
    ) -> "Collection":
        """
        Get a collection by name, returning a Collection wrapper object.

        Args:
            collection_name: Name of the collection to retrieve

        Returns:
            Collection wrapper object for the specified collection

        Raises:
            RuntimeError: If AsyncProject is not available
            CollectionNotFoundError: If the collection with the given name is not found
            Exception: If the API request fails or authentication errors occur
        """
        from .collection import Collection

        try:
            future = self._runner.submit(
                self._async.get_collection(
                    collection_name,
                    retry_policy=retry_policy,
                    timeouts=timeouts,
                    hooks=hooks,
                )
            )
            async_collection = future.result()

            # Convert AsyncCollection to Collection wrapper
            collection_data = {
                "uuid": async_collection.id,
                "name": async_collection.name,
                "created_at": async_collection.created_at,
                "updated_at": async_collection.updated_at,
                "metadata": {"attributes": dict(async_collection.attributes)},
            }

            collection = Collection(
                collection_data=collection_data,
                project_data=self._project_data,
                nexus_client=self._nexus_client,
                runner=self._runner,
                async_collection=async_collection,
            )
            return collection
        except CollectionNotFoundError:
            # Expected miss path for get_or_create_collection; do not log as error
            raise
        except Exception as e:
            self._handle_auth_errors(e)
            self.logger.error(f"Error in get_collection: {e}")
            raise

    def create_collection(
        self,
        collection_name: str,
        schema: Any,
        *,
        retry_policy: Optional[RetryPolicy] = None,
        timeouts: Optional[Timeouts] = None,
        hooks: Optional[ApiHooks] = None,
    ) -> "Collection":
        """
        Create a new collection in this project.

        Args:
            collection_name: Name of the collection (same parameter as
                :meth:`miura.api.project.AsyncProject.create_collection`)
            schema: Schema definition for the collection

        Returns:
            Collection wrapper object for the newly created collection

        Raises:
            ConflictError: If a collection with the same name already exists
        """
        from .collection import Collection

        try:
            compiled_schema = normalize_collection_schema(schema)
            create_kwargs: dict[str, Any] = {
                "retry_policy": retry_policy,
                "timeouts": timeouts,
                "hooks": hooks,
            }
            future = self._runner.submit(
                self._async.create_collection(collection_name, compiled_schema, **create_kwargs)
            )
            async_collection = future.result()

            # Convert AsyncCollection to Collection wrapper
            collection_data = {
                "uuid": async_collection.id,
                "name": async_collection.name,
                "created_at": async_collection.created_at,
                "updated_at": async_collection.updated_at,
                "metadata": {"attributes": dict(async_collection.attributes)},
            }

            collection = Collection(
                collection_data=collection_data,
                project_data=self._project_data,
                nexus_client=self._nexus_client,
                runner=self._runner,
                async_collection=async_collection,
            )
            return collection
        except Exception as e:
            self._handle_auth_errors(e)
            self.logger.error(f"Error in create_collection for project '{self.name}': {e}")
            raise

    def get_or_create_collection(
        self,
        collection_name: str,
        schema: Dict[str, Any],
        *,
        retry_policy: Optional[RetryPolicy] = None,
        timeouts: Optional[Timeouts] = None,
        hooks: Optional[ApiHooks] = None,
    ) -> "Collection":
        """
        Get an existing collection by name, or create it if it does not exist.

        Args:
            collection_name: Name of the collection to get or create (same as
                :meth:`miura.api.project.AsyncProject.get_or_create_collection`)
            schema: Schema definition (used only when creating)

        Returns:
            Collection wrapper object for the existing or newly created collection
        """
        try:
            return self.get_collection(
                collection_name,
                retry_policy=retry_policy,
                timeouts=timeouts,
                hooks=hooks,
            )
        except CollectionNotFoundError:
            return self.create_collection(
                collection_name,
                schema,
                retry_policy=retry_policy,
                timeouts=timeouts,
                hooks=hooks,
            )

    def iter_collections(
        self,
        prefetch_pages: int = 1,
        page_size: int = 50,
        retry_policy: Optional[RetryPolicy] = None,
        timeouts: Optional[Timeouts] = None,
        hooks: Optional[ApiHooks] = None,
    ) -> Iterator["Collection"]:
        """
        Iterate over all collections with transparent pagination.

        This method provides a sync iterator that yields collections one at a time,
        handling pagination transparently. It wraps the async iterator from AsyncProject.

        Args:
            prefetch_pages: Number of pages to prefetch (default: 1, max: 5)
            page_size: Number of items per page (default: 50, max: 1000)

        Yields:
            Collection wrapper objects

        Note:
            Pagination stability: Results may be reordered if backend changes.
            For deterministic ordering, backend should support sort_by parameter.
        """
        from .collection import Collection
        from miura.api.collection import AsyncCollection

        # Get async generator from AsyncProject
        agen = self._async.iter_collections(
            prefetch_pages=prefetch_pages,
            page_size=page_size,
            retry_policy=retry_policy,
            timeouts=timeouts,
            hooks=hooks,
        )

        try:
            while True:
                # Submit __anext__ to get next item
                fut = self._runner.submit(agen.__anext__())
                try:
                    collection_info = fut.result()

                    # Convert CollectionInfo to Collection wrapper
                    collection_data = {
                        "uuid": collection_info.id,
                        "name": collection_info.name,
                        "created_at": collection_info.created_at,
                        "updated_at": collection_info.updated_at,
                        "metadata": collection_info.metadata,
                    }

                    # Create AsyncCollection from collection data
                    async_collection = AsyncCollection(
                        collection_data=collection_data,
                        project=self._async,
                        nexus_client=self._nexus_client,
                    )

                    # Wrap in Collection
                    collection = Collection(
                        collection_data=collection_data,
                        project_data=self._project_data,
                        nexus_client=self._nexus_client,
                        runner=self._runner,
                        async_collection=async_collection,
                    )
                    yield collection
                except StopAsyncIteration:
                    break
        except (GeneratorExit, KeyboardInterrupt):
            # Graceful cancellation: cancel underlying async generator
            try:
                close_fut = self._runner.submit(agen.aclose())
                close_fut.result(timeout=2.0)
            except Exception:
                pass  # Ignore errors during cleanup
            raise

    def update_project(
        self,
        metadata: Optional[Dict[str, Any]] = None,
        retry_policy: Optional[RetryPolicy] = None,
        timeouts: Optional[Timeouts] = None,
        hooks: Optional[ApiHooks] = None,
    ) -> None:
        """
        Update project metadata.

        Args:
            metadata: Optional metadata dictionary to update

        Raises:
            NotImplementedError: Same as :meth:`AsyncProject.update_project` until implemented.
        """
        try:
            future = self._runner.submit(
                self._async.update_project(
                    metadata,
                    retry_policy=retry_policy,
                    timeouts=timeouts,
                    hooks=hooks,
                )
            )
            future.result()
        except Exception as e:
            self._handle_auth_errors(e)
            self.logger.error(f"Error in update_project for project '{self.name}': {e}")
            raise

    def delete_project(
        self,
        retry_policy: Optional[RetryPolicy] = None,
        timeouts: Optional[Timeouts] = None,
        hooks: Optional[ApiHooks] = None,
    ) -> None:
        """
        Delete this project and all associated resources.

        Raises:
            RuntimeError: If AsyncProject is not available
            ProjectNotFoundError: If project is not found
            NetworkError: If network request fails
            PermissionError: If authentication fails
        """
        try:
            future = self._runner.submit(
                self._async.delete_project(
                    retry_policy=retry_policy,
                    timeouts=timeouts,
                    hooks=hooks,
                )
            )
            future.result()
        except Exception as e:
            self._handle_auth_errors(e)
            self.logger.error(f"Error deleting project '{self.name}': {e}")
            raise

    @property
    def info(self) -> "ProjectInfo":
        """
        Get the underlying ProjectInfo DTO.

        This provides access to the raw data structure for serialization,
        caching, or other internal operations.

        Returns:
            The underlying ProjectInfo data
        """
        from miura.sdk.types import ProjectInfo, normalize_owner_profile

        return ProjectInfo(
            uuid=self._uuid,
            name=self.name,
            owner_id=self.owner_id,
            created_at=self.created_at or "",
            updated_at=self.updated_at or "",
            metadata=self.metadata or {},
            owner_profile=normalize_owner_profile(self._project_data.get("owner")),
        )

    def print_info(self) -> None:
        """Print comprehensive information about the project, collections, and recipes."""
        project_info = self.info

        try:
            collections = self.list_collections()
            recipes = self.list_recipes()
            # Convert collections to CollectionInfo for display
            collection_infos = [
                CollectionInfo(
                    uuid=c.id,
                    name=c.name,
                    project_uuid=c.project_id,
                    created_at=c.created_at or "",
                    updated_at=c.updated_at or "",
                    metadata={"attributes": dict(c.attributes)},
                )
                for c in collections
            ]
            print_project_info(project_info, collections=collection_infos, recipes=recipes)
        except Exception as e:
            self.logger.error(f"Error in print_info: {e}")
            # Print project info without collections/recipes
            print_project_info(project_info, collections=None, recipes=None)
            raise

    def __str__(self):
        """String representation of the project for printing."""
        return self._get_info_string()

    def __repr__(self):
        """Detailed representation of the project."""
        collections_count = len(self.list_collections()) if hasattr(self, "_collections_cache") else "unknown"
        return f"Project(name='{self.name}', id='{self._uuid}', collections_count={collections_count})"

    def _format_metadata_value(self, value: Any) -> str:
        """Format metadata values for pretty display."""
        if isinstance(value, dict):
            # Show key names and types for better understanding
            if len(value) > 6:  # Large dictionary
                key_preview = ", ".join(list(value.keys())[:3])
                remaining = len(value) - 3
                if remaining > 0:
                    return f"<dict: {key_preview}... (+{remaining} more)>"
                else:
                    return f"<dict: {key_preview}>"
            else:
                # Pretty format smaller dictionaries
                items = []
                for k, v in value.items():
                    if isinstance(v, (dict, list)):
                        items.append(f"{k}: <{type(v).__name__}>")
                    elif isinstance(v, str) and len(v) > 30:
                        items.append(f"{k}: {v[:27]}...")
                    else:
                        items.append(f"{k}: {v}")
                return "{" + ", ".join(items) + "}"
        elif isinstance(value, list):
            if len(value) > 5:  # Long list
                return f"<list with {len(value)} items>"
            else:
                return str(value)
        elif isinstance(value, str) and len(value) > 50:
            return f"{value[:47]}..."
        else:
            return str(value)

    def _get_info_string(self) -> str:
        """Get the information string without printing."""
        import io
        import sys

        # Capture the print output
        old_stdout = sys.stdout
        sys.stdout = buffer = io.StringIO()

        try:
            self.print_info()
            return buffer.getvalue()
        finally:
            sys.stdout = old_stdout

    def list_recipes(
        self,
        source_collection_name: Optional[str] = None,
        source_group_name: Optional[str] = None,
        target_collection_name: Optional[str] = None,
        target_group_name: Optional[str] = None,
        retry_policy: Optional[RetryPolicy] = None,
        timeouts: Optional[Timeouts] = None,
        hooks: Optional[ApiHooks] = None,
    ) -> List[RecipeResponse]:
        """
        List all recipes in this project.

        Args:
            source_collection_name: Optional filter by source collection name
            source_group_name: Optional filter by source group name
            target_collection_name: Optional filter by target collection name
            target_group_name: Optional filter by target group name
            retry_policy: Optional per-call retry policy override (same as :meth:`AsyncProject.list_recipes`)
            timeouts: Optional per-call timeout override
            hooks: Optional per-call hooks override

        Returns:
            List of RecipeResponse objects
        """
        try:
            future = self._runner.submit(
                self._async.list_recipes(
                    source_collection_name=source_collection_name,
                    source_group_name=source_group_name,
                    target_collection_name=target_collection_name,
                    target_group_name=target_group_name,
                    retry_policy=retry_policy,
                    timeouts=timeouts,
                    hooks=hooks,
                )
            )
            return to_sync_recipe_responses(
                future.result(),
                project=self,
                async_project=self._async,
                runner=self._runner,
            )
        except Exception as e:
            self._handle_auth_errors(e)
            self.logger.error(f"Error in list_recipes for project '{self.name}': {e}")
            raise

    def get_recipe(
        self,
        recipe_name: str,
        retry_policy: Optional[RetryPolicy] = None,
        timeouts: Optional[Timeouts] = None,
        hooks: Optional[ApiHooks] = None,
    ) -> RecipeResponse:
        """
        Get a recipe by name.

        Args:
            recipe_name: Name of the recipe (must be unique within project)
            retry_policy: Optional per-call retry policy override (same as :meth:`AsyncProject.get_recipe`)
            timeouts: Optional per-call timeout override
            hooks: Optional per-call hooks override

        Returns:
            RecipeResponse with recipe data

        Raises:
            RecipeNotFoundError: If recipe not found
        """
        try:
            future = self._runner.submit(
                self._async.get_recipe(
                    recipe_name,
                    retry_policy=retry_policy,
                    timeouts=timeouts,
                    hooks=hooks,
                )
            )
            return to_sync_recipe_response(
                future.result(),
                project=self,
                async_project=self._async,
                runner=self._runner,
            )
        except RecipeNotFoundError:
            # Expected miss path for get_or_create_recipe (async); do not log as error
            raise
        except Exception as e:
            self._handle_auth_errors(e)
            self.logger.error(f"Error in get_recipe for project '{self.name}': {e}")
            raise

    def get_or_create_recipe(
        self,
        name: str,
        spec: RecipeSpec,
        *,
        description: str = "",
        submit: bool = False,
        options: Optional[RecipeCreateOptions] = None,
        retry_policy: Optional[RetryPolicy] = None,
        timeouts: Optional[Timeouts] = None,
        hooks: Optional[ApiHooks] = None,
    ) -> RecipeResponse:
        """
        Get a recipe by name, or create it from a spec if not found (same contract as async).

        Raises ``RecipeSpecConflictError`` when an existing recipe's stored executable
        specification differs from ``spec`` (existing recipe is left unchanged).
        """
        from miura.sdk.exceptions import RecipeSpecConflictError

        try:
            future = self._runner.submit(
                self._async.get_or_create_recipe(
                    name,
                    spec,
                    description=description,
                    submit=submit,
                    options=options,
                    retry_policy=retry_policy,
                    timeouts=timeouts,
                    hooks=hooks,
                )
            )
            return to_sync_recipe_response(
                future.result(),
                project=self,
                async_project=self._async,
                runner=self._runner,
            )
        except RecipeSpecConflictError:
            raise
        except Exception as e:
            self._handle_auth_errors(e)
            self.logger.error(f"Error in get_or_create_recipe for project '{self.name}': {e}")
            raise

    def validate_recipe_spec(self, spec: RecipeSpec) -> ValidationResult:
        """
        Validate a RecipeSpec (same contract as :meth:`AsyncProject.validate_recipe_spec`).

        A writer id the project does not publish raises
        :class:`~miura.sdk.exceptions.ValidationError` before the call is made.
        A Converter reader id that is not published raises the same error.
        """
        try:
            future = self._runner.submit(self._async.validate_recipe_spec(spec))
            return future.result()
        except Exception as e:
            self._handle_auth_errors(e)
            self.logger.error(f"Error in validate_recipe_spec for project '{self.name}': {e}")
            raise

    def validate_recipe_payload(self, payload: Dict[str, Any]) -> ValidationResult:
        """Validate a recipe payload dict (same contract as :meth:`AsyncProject.validate_recipe_payload`)."""
        try:
            future = self._runner.submit(self._async.validate_recipe_payload(payload))
            return future.result()
        except Exception as e:
            self._handle_auth_errors(e)
            self.logger.error(f"Error in validate_recipe_payload for project '{self.name}': {e}")
            raise

    def validate_recipe(self, spec_or_payload: Union[RecipeSpec, Dict[str, Any]]) -> ValidationResult:
        """Validate a recipe (same contract as :meth:`AsyncProject.validate_recipe`)."""
        try:
            future = self._runner.submit(self._async.validate_recipe(spec_or_payload))
            return future.result()
        except Exception as e:
            self._handle_auth_errors(e)
            self.logger.error(f"Error in validate_recipe for project '{self.name}': {e}")
            raise

    def get_recipe_capabilities(self, *, refresh: bool = False) -> Capabilities:
        """
        Return typed recipe capabilities (cached on the async twin).

        Same contract as :meth:`AsyncProject.get_recipe_capabilities`. Prefer
        :attr:`available_writers` / :attr:`available_readers` when you only need
        a single id.
        """
        try:
            future = self._runner.submit(self._async.get_recipe_capabilities(refresh=refresh))
            return future.result()
        except Exception as e:
            self._handle_auth_errors(e)
            self.logger.error(f"Error in get_recipe_capabilities for project '{self.name}': {e}")
            raise

    @property
    def available_writers(self) -> CapabilityCatalog:
        """
        Writer ids this project can produce, fetched once and cached.

        Recipe specs take the writer id directly (``writer="parquet_tabular"``)
        and :meth:`deploy_recipe` rejects an id the project does not publish.
        Reach for this catalog when you want to see what is on offer, or to
        resolve an id yourself and get a "did you mean" hint for a typo::

            print(list(project.available_writers))
            writer = project.available_writers.require("parquet_tabular")
        """
        try:
            future = self._runner.submit(self._async.available_writers())
            return future.result()
        except Exception as e:
            self._handle_auth_errors(e)
            self.logger.error(f"Error in available_writers for project '{self.name}': {e}")
            raise

    @property
    def available_readers(self) -> CapabilityCatalog:
        """
        Reader ids this project can consume, fetched once and cached.

        These ids are the Sigma reader ``class_name`` values registered on the
        deployment (e.g. ``"vtkXdmfReader"``). Pass the same string to
        ``SigmaClassRef(class_name=...)`` when building a converter;
        :meth:`deploy_recipe` rejects a Converter whose reader is not published.
        Leave the Sigma reader unset for auto-detect — that path is not checked.

        Use this catalog to list what is on offer, or to resolve an id yourself::

            print(list(project.available_readers))
            reader = project.available_readers.require("vtkXdmfReader")
        """
        try:
            future = self._runner.submit(self._async.available_readers())
            return future.result()
        except Exception as e:
            self._handle_auth_errors(e)
            self.logger.error(f"Error in available_readers for project '{self.name}': {e}")
            raise

    def deploy_recipe(
        self,
        name: str,
        spec: RecipeSpec,
        *,
        description: str = "",
        cases: "CaseBinding | None" = None,
    ) -> RecipeResponse:
        """
        Deploy a recipe definition as the current executable version.

        Same contract as :meth:`AsyncProject.deploy_recipe` (create / no-op / revise).
        Pass ``cases=`` with ``upload.cases`` / ``plan.cases``
        (:class:`~miura.nexus.case_grouping.AdmittedCases`) to bind the case
        universe at deploy time.

        A writer id the project does not publish raises
        :class:`~miura.sdk.exceptions.ValidationError` before anything is
        created. A Converter reader id that is not published raises the same
        error. Use :attr:`available_writers` / :attr:`available_readers` to
        list the supported ids.
        """
        try:
            future = self._runner.submit(
                self._async.deploy_recipe(
                    name,
                    spec,
                    description=description,
                    cases=cases,
                )
            )
            return to_sync_recipe_response(
                future.result(),
                project=self,
                async_project=self._async,
                runner=self._runner,
            )
        except Exception as e:
            self._handle_auth_errors(e)
            self.logger.error(f"Error in deploy_recipe for project '{self.name}': {e}")
            raise

    def create_recipe(
        self,
        name: str,
        spec: RecipeSpec,
        *,
        description: str = "",
        submit: bool = False,
        retry_policy: Optional[RetryPolicy] = None,
        timeouts: Optional[Timeouts] = None,
        hooks: Optional[ApiHooks] = None,
    ) -> RecipeResponse:
        """
        Explicitly create a new recipe identity and its first immutable revision.

        Same contract as :meth:`AsyncProject.create_recipe`. Prefer
        :meth:`deploy_recipe` for repeatable authoring scripts.
        """
        try:
            future = self._runner.submit(
                self._async.create_recipe(
                    name,
                    spec,
                    description=description,
                    submit=submit,
                    retry_policy=retry_policy,
                    timeouts=timeouts,
                    hooks=hooks,
                )
            )
            return to_sync_recipe_response(
                future.result(),
                project=self,
                async_project=self._async,
                runner=self._runner,
            )
        except Exception as e:
            self._handle_auth_errors(e)
            self.logger.error(f"Error in create_recipe for project '{self.name}': {e}")
            raise

    def run_recipe(
        self,
        recipe: Union[RecipeResponse, str],
        execution_profile: Optional[str] = None,
        tags: Optional[dict[str, str]] = None,
        idempotency_key: Optional[str] = None,
        execution_plan_version_suffix: Optional[str] = None,
        target_collection_mode: Optional[str] = None,
        inputs: Optional[str] = None,
        request_schema_version: int = 1,
        execution_options: Optional[dict[str, Any]] = None,
        retry_policy: Optional[RetryPolicy] = None,
        timeouts: Optional[Timeouts] = None,
        hooks: Optional[ApiHooks] = None,
    ) -> "SyncRecipeRunHandle":
        """
        Execute a recipe (queue for execution). Same behavior as :meth:`AsyncProject.run_recipe`.

        Returns:
            :class:`SyncRecipeRunHandle` for blocking ``wait`` / ``refresh`` / ``cancel``.
        """
        from .recipe_run import SyncRecipeRunHandle

        try:
            async_recipe = recipe._async if isinstance(recipe, RecipeResponse) else recipe
            future = self._runner.submit(
                self._async.run_recipe(
                    async_recipe,
                    execution_profile=execution_profile,
                    tags=tags,
                    idempotency_key=idempotency_key,
                    execution_plan_version_suffix=execution_plan_version_suffix,
                    target_collection_mode=target_collection_mode,
                    inputs=inputs,
                    request_schema_version=request_schema_version,
                    execution_options=execution_options,
                    retry_policy=retry_policy,
                    timeouts=timeouts,
                    hooks=hooks,
                )
            )
            async_handle = future.result()
            return SyncRecipeRunHandle(async_handle, self._runner)
        except Exception as e:
            self._handle_auth_errors(e)
            self.logger.error(f"Error in run_recipe for project '{self.name}': {e}")
            raise

    def list_runs(
        self,
        *,
        state: Optional[List[str]] = None,
        sort_by: str = "created_at",
        sort_order: str = "desc",
        page: int = 1,
        limit: int = 50,
    ) -> "RunListResponse":
        """List runs scoped to this project (same contract as :meth:`miura.api.project.AsyncProject.list_runs`)."""
        try:
            future = self._runner.submit(
                self._async.list_runs(
                    state=state,
                    sort_by=sort_by,
                    sort_order=sort_order,
                    page=page,
                    limit=limit,
                )
            )
            return future.result()
        except Exception as e:
            self._handle_auth_errors(e)
            self.logger.error(f"Error in list_runs for project '{self.name}': {e}")
            raise

    def delete_recipe(
        self,
        name: str,
        *,
        confirm: bool = True,
        retry_policy: Optional[RetryPolicy] = None,
        timeouts: Optional[Timeouts] = None,
        hooks: Optional[ApiHooks] = None,
    ) -> None:
        """Delete a recipe by name (same behavior as :meth:`AsyncProject.delete_recipe`)."""
        try:
            future = self._runner.submit(
                self._async.delete_recipe(
                    name,
                    confirm=confirm,
                    retry_policy=retry_policy,
                    timeouts=timeouts,
                    hooks=hooks,
                )
            )
            future.result()
        except CancelledError:
            raise
        except Exception as e:
            self._handle_auth_errors(e)
            self.logger.error(f"Error in delete_recipe for project '{self.name}': {e}")
            raise

    def help(self) -> None:
        """
        Display help information about available methods.

        Shows a terse summary of available methods with key parameters and examples.
        """
        print_project_help()