endorlabs 0.2.0__py3-none-any.whl

endorlabs/__init__.py

@@ -0,0 +1,202 @@
+"""Endor Labs SDK.
+
+A Python SDK for the Endor Labs platform.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal
+
+from .api_client import APIClient
+from .client_surface import Client
+from .core.exceptions import (
+    AmbiguousError,
+    ConflictError,
+    EndorAPIError,
+    MethodNotSupportedError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ServerError,
+    UnauthorizedError,
+    ValidationError,
+    map_status_code_to_exception,
+)
+from .core.filter import F, FilterExpression
+from .resources import (
+    dependency_metadata,
+    finding,
+    installation,
+    linter_result,
+    malware,
+    metric,
+    namespace,
+    package_version,
+    policy,
+    project,
+    query_malware,
+    query_vulnerability,
+    repository,
+    repository_version,
+    vulnerability,
+)
+
+if TYPE_CHECKING:
+    from .context.models import InitStatus
+
+try:
+    from endorlabs._version import __version__  # generated by hatch-vcs
+except ImportError:  # editable install or no build
+    __version__ = "0.0.0.dev0"
+
+
+def agent_knowledge_dir() -> Path:
+    """Return site-packages path to the shipped agent knowledge package."""
+    from .agent_knowledge import agent_knowledge_dir as _agent_knowledge_dir
+
+    return _agent_knowledge_dir()
+
+
+def agent_knowledge_index_path() -> Path:
+    """Return path to Tier-0 INDEX.md in the shipped agent knowledge package."""
+    from .agent_knowledge import (
+        agent_knowledge_index_path as _agent_knowledge_index_path,
+    )
+
+    return _agent_knowledge_index_path()
+
+
+def agent_knowledge_manifest() -> dict[str, Any]:
+    """Parse MANIFEST.json from the shipped agent knowledge package."""
+    from .agent_knowledge import agent_knowledge_manifest as _agent_knowledge_manifest
+
+    return _agent_knowledge_manifest()
+
+
+def agent_knowledge_rule_ids() -> list[str]:
+    """Return bootstrap rule ids from the shipped agent knowledge manifest."""
+    from .agent_knowledge import agent_knowledge_rule_ids as _agent_knowledge_rule_ids
+
+    return _agent_knowledge_rule_ids()
+
+
+def agent_knowledge_bootstrap_paths() -> list[Path]:
+    """Return INDEX.md and bootstrap rule paths for harness injection."""
+    from .agent_knowledge import (
+        agent_knowledge_bootstrap_paths as _agent_knowledge_bootstrap_paths,
+    )
+
+    return _agent_knowledge_bootstrap_paths()
+
+
+def init(
+    output_dir: str | Path = ".endorlabs-context",
+    include_openapi: bool = False,
+    include_user_docs: bool = False,
+    include_agent_knowledge: bool = True,
+    max_pages: int | None = None,
+    force: bool = False,
+    sync_skills: Literal["none", "cursor", "claude", "both"] = "none",
+    client: APIClient | None = None,
+) -> InitStatus:
+    """Bootstrap Endor Labs context for agentic workflows.
+
+    By default, ``init()`` materializes agent knowledge under ``sdk/``. Pass explicit
+    flags to download platform context or mirror skills.
+
+    Args:
+        output_dir: Directory to save context files (default: .endorlabs-context).
+        include_openapi: Download OpenAPI spec (default: False).
+        include_user_docs: Download user documentation (default: False).
+        include_agent_knowledge: Materialize agent knowledge to sdk/ (default: True).
+        max_pages: Maximum number of user doc pages to download (default: all).
+        force: Force re-download even if files exist (default: False).
+        sync_skills: Mirror skills into runtime discovery directories.
+        client: Optional APIClient instance for OpenAPI download.
+
+    Returns:
+        InitStatus with paths to materialized and downloaded files.
+
+    Raises:
+        UnauthorizedError: If OpenAPI authentication fails.
+        ImportError: If context dependencies are not installed (for user docs).
+            Install with: pip install endorlabs[docs]
+
+    Example::
+
+        >>> import endorlabs
+        >>> status = endorlabs.init()
+        >>> print(status.agent_knowledge_path)
+        .endorlabs-context/sdk
+
+    """
+    from .context import _sync
+
+    return _sync.init(
+        output_dir=output_dir,
+        include_openapi=include_openapi,
+        include_user_docs=include_user_docs,
+        include_agent_knowledge=include_agent_knowledge,
+        max_pages=max_pages,
+        force=force,
+        sync_skills=sync_skills,
+        client=client,
+    )
+
+
+def sync_agent_skills(
+    *,
+    repo_root: str | Path = ".",
+    target: Literal["none", "cursor", "claude", "both"] = "none",
+    source_dir: str | Path | None = None,
+) -> dict[str, Path]:
+    """Mirror ``endor-*`` skills into runtime discovery directories."""
+    from .context import _sync
+
+    return _sync.sync_agent_skills(
+        repo_root=repo_root,
+        target=target,
+        source_dir=source_dir,
+    )
+
+
+__all__ = [
+    "APIClient",
+    "AmbiguousError",
+    "Client",
+    "ConflictError",
+    "EndorAPIError",
+    "F",
+    "FilterExpression",
+    "MethodNotSupportedError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "ServerError",
+    "UnauthorizedError",
+    "ValidationError",
+    "agent_knowledge_bootstrap_paths",
+    "agent_knowledge_dir",
+    "agent_knowledge_index_path",
+    "agent_knowledge_manifest",
+    "agent_knowledge_rule_ids",
+    "dependency_metadata",
+    "finding",
+    "init",
+    "installation",
+    "linter_result",
+    "malware",
+    "map_status_code_to_exception",
+    "metric",
+    "namespace",
+    "package_version",
+    "policy",
+    "project",
+    "query_malware",
+    "query_vulnerability",
+    "repository",
+    "repository_version",
+    "sync_agent_skills",
+    "vulnerability",
+]

endorlabs/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.2.0'
+__version_tuple__ = version_tuple = (0, 2, 0)
+
+__commit_id__ = commit_id = None

endorlabs/agent_knowledge/INDEX.md

@@ -0,0 +1,116 @@
+# Endor Labs SDK — Agent Index (Tier 0)
+
+Shipped with `endorlabs` inside the wheel. **`endorlabs.init()` is optional** — use
+`agent_knowledge_index_path()` to read this file from site-packages, or materialize under
+`.endorlabs-context/sdk/` when a cwd-relative tree is needed.
+
+## Quick start
+
+**Wheel-only** (no disk materialization):
+
+```python
+import endorlabs
+
+print(endorlabs.agent_knowledge_index_path())
+manifest = endorlabs.agent_knowledge_manifest()
+paths = endorlabs.agent_knowledge_bootstrap_paths()  # INDEX + bootstrap rules
+```
+
+**Minimal bootstrap** (rules, contracts, skills; no auth):
+
+```python
+import endorlabs
+
+status = endorlabs.init(include_openapi=False, include_user_docs=False)
+# Read: status.agent_knowledge_index_path  →  .endorlabs-context/sdk/INDEX.md
+```
+
+**Full bootstrap** (agent knowledge + platform OpenAPI/user docs):
+
+```python
+pip install 'endorlabs[docs]'
+import endorlabs
+
+status = endorlabs.init(include_openapi=True, include_user_docs=True)
+# Read: status.agent_knowledge_index_path
+```
+
+## Authentication
+
+Set credentials via environment (never commit secrets):
+
+- `ENDOR_API_CREDENTIALS_KEY` + `ENDOR_API_CREDENTIALS_SECRET`, or
+- `ENDOR_TOKEN` (browser refresh via maintainer tooling writes this only)
+- Optional default namespace: `ENDOR_NAMESPACE`
+
+Verify: `endorlabs.Client().whoami()`.
+
+## Client basics
+
+```python
+import endorlabs
+client = endorlabs.Client(tenant="tenant.namespace")
+projects = client.Project.list(traverse=True, max_pages=2)
+```
+
+- Resource facades use **PascalCase**: `client.Project`, `client.Finding`, …
+- Match `endorctl api … --resource <Kind>` vocabulary.
+- `.get()` / `.lookup()` return typed models; `.list()` returns models unless `mask=` is set.
+
+## Critical footguns
+
+Read **`rules/`** (Tier 1 bootstrap) before project-scoped RCA.
+
+1. **Ambiguous project URL:** `Project.lookup(name=…)` may raise `AmbiguousError`. Use
+   `Project.list(traverse=True)`, pass explicit namespace, or use project UUID.
+2. **Project-scoped list namespace (MUST):** With `Client(tenant=<estate_root>)` and default
+   `traverse=False`, lists hit only that path segment—not child namespaces where projects live.
+   Resolve `Project` first, then pass **`namespace=project.namespace`** on `Finding`, `ScanResult`,
+   `PackageVersion`, `DependencyMetadata`, … Empty rows often mean wrong namespace, not missing data.
+3. **Finding branch refs:** `spec.source_code_version.ref` may be a short branch label, not
+   `refs/heads/main`. List findings without branch filter first; narrow after inspecting stored refs.
+4. **Tenant-wide scan cost:** `fetch_scan_results --all-projects` is O(projects × scans). Prefer
+   project-scoped RCA.
+5. **List masks:** Non-empty `mask=` on `.list()` returns `dict` rows, not Pydantic models.
+   `lookup()` raises if mask is active—use `.list()` for masked rows.
+6. **DependencyMetadata wire path:** List/group uses the **customer tenant namespace**, not the
+   literal `oss` plane. Field `spec.dependency_data.namespace == "oss"` is data semantics only.
+7. **Workflow composition:** Extend workflow JSON/manifests before re-listing the API; escalate
+   CLI → library → `Client` → session script (see `rules/endor-workflow-composition.md`).
+8. **Portable examples:** Use placeholders in docs; never commit customer estate identifiers
+   (`rules/endor-portable-examples.md`).
+
+## Bootstrap (load for Endor SDK work)
+
+Harnesses should prepend `agent_knowledge_bootstrap_paths()` (or read these rules first). In Cursor, `endor-namespace-scoping` and `endor-list-query-performance` are **always-on**; other bootstrap `endor-*.mdc` rules attach when path **globs** match (`src/endorlabs/**`, Python, `.endorlabs-context/`, etc.).
+
+| Rule | Summary |
+|------|---------|
+| `endor-namespace-scoping` | Resolve Project; pass `namespace=project.namespace` on project-scoped lists |
+| `endor-workspace-layout` | Session artifacts under `workspace/sessions/<user>/` |
+| `endor-workflow-composition` | CLI → library → Client → session script; artifact-first |
+| `endor-list-query-performance` | Do not set `page_size` unless asked |
+| `endor-local-context` | Check gitignored `.endorlabs-context/` paths explicitly |
+| `endor-portable-examples` | Placeholders only; no committed tenant/project UUID literals |
+
+See `MANIFEST.json` → `bootstrap.rule_ids` for the machine-readable list.
+
+## Workspace outputs
+
+Session/triage debugging artifacts and temporary probe scripts belong under
+`.endorlabs-context/workspace/sessions/<user>/` (not repo-root `.tmp/`). Project
+bundles go under `workspace/projects/<uuid>/`. See `rules/endor-workspace-layout.md`.
+
+## Read order
+
+1. This file (Tier 0)
+2. `MANIFEST.json` — rules, contracts, skills, workflow CLI index, `bootstrap` block
+3. **`rules/*.md`** — harness bootstrap (always load)
+4. **`contracts/*.md`** — normative SDK semantics on demand
+5. **`skills/*/SKILL.md`** — task playbooks
+6. `../platform/openapi/` and `../platform/user-docs/` — product/API reference (after `init()`)
+7. `../workspace/` — your run outputs
+
+## Maintainer docs (not shipped)
+
+Repo-only: `CONTRIBUTORS.md`, `docs/contributing/`, `devtools/`. Clone the GitHub repo for those.