infra PR1: deployment provider registry + plugin discovery

[hudsonaikins]

Summary

• add neural.deployment provider registry APIs: register_provider, create_provider, list_providers
• add plugin discovery from entry points group neural.deployment.providers
• register built-in Docker provider in the registry when deployment extras are available
• add explicit missing/unloadable provider errors and preserve optional deployment import behavior
• add docs for external provider plugin authoring and wire it into docs navigation
• add unit tests for register/create/list/discovery and failure modes

Validation

• ruff check neural/deployment/__init__.py neural/deployment/registry.py tests/deployment/test_registry.py
• pytest -q tests/deployment/test_registry.py
• pytest -q tests/test_public_api.py

Greptile Summary

This PR implements a deployment provider registry and plugin discovery system that enables external packages to contribute deployment backends without modifying SDK source code.

Core Infrastructure Changes:

• Added neural.deployment.registry module with register_provider, create_provider, and list_providers APIs
• Plugin discovery via Python entry points under neural.deployment.providers group
• Built-in Docker provider auto-registration when deployment extras are installed
• Graceful fallback behavior: stub implementations raise ProviderNotFoundError when Docker dependencies are unavailable

Error Handling:

• Provider names are normalized and validated
• Plugin load failures are tracked separately and surfaced with clear error messages when accessed
• Factory validation ensures only DeploymentProvider instances are returned

Testing & Documentation:

• Comprehensive unit tests covering registration, discovery, error cases, and monkeypatched entry point loading
• New documentation page for external provider plugin authoring with usage examples and checklist
• Updated infrastructure docs to explain the runtime model

Unrelated Changes:

• Added docstrings to neural.auth.polymarket_us_env helper functions
• Formatting improvements in neural.auth.signers.polymarket_us and tests.exchanges.test_polymarket_streaming

The architecture follows established Python packaging patterns (entry points) and maintains backward compatibility by preserving direct DockerDeploymentProvider imports while adding the registry layer.

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The changes introduce well-architected infrastructure with comprehensive test coverage, clear error handling, and no breaking changes to existing APIs. The plugin discovery pattern follows established Python conventions, and graceful degradation ensures the module remains functional when optional dependencies are missing.
• No files require special attention

Important Files Changed

Filename	Overview
neural/deployment/registry.py	New provider registry with entry point discovery, comprehensive error handling, and well-tested plugin loading
neural/deployment/init.py	Added registry APIs to public interface and graceful fallback stubs when Docker dependencies are missing
tests/deployment/test_registry.py	Comprehensive test coverage for registration, discovery, error handling, and plugin loading failure scenarios
docs/workflows/deployment-providers.mdx	Clear documentation for external provider authoring with usage examples and plugin authoring checklist

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[User calls create_provider name] --> B[discover_providers]
    B --> C{Plugins discovered?}
    C -->|No| D[Load entry points from neural.deployment.providers]
    C -->|Yes| E[Check normalized name]
    D --> F{Entry point loads?}
    F -->|Success| G[register_provider]
    F -->|Failure| H[Store in _provider_load_errors]
    G --> E
    H --> E
    E --> I{Name in _provider_load_errors?}
    I -->|Yes| J[Raise ProviderNotFoundError with load error]
    I -->|No| K{Name in _provider_factories?}
    K -->|No| L[Raise ProviderNotFoundError with available list]
    K -->|Yes| M[Call factory with kwargs]
    M --> N{Returns DeploymentProvider?}
    N -->|No| O[Raise ConfigurationError]
    N -->|Yes| P[Return provider instance]

Loading

_{Last reviewed commit: acafb9f}

[github-actions]

📚 Documentation Status

✅ Code changes detected

• Docstring coverage checked
• API documentation validation completed
  ✅ Documentation changes detected
• Documentation structure validated
• Links checked for broken references

---

This comment is automatically generated by the documentation workflow.

[greptile-apps]

_{9 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Inaccurate pragma comment

The # pragma: no cover comment says "exercised via tests with monkeypatch", which contradicts the purpose of a no cover annotation. The monkeypatch test test_discover_providers_loads_entry_points_and_tracks_broken_plugins does exercise the _bad_loader path through this except block. If the test is already covering this branch, the pragma: no cover should be removed so coverage accurately reflects the tested paths.

Prompt To Fix With AI

This is a comment left during a code review.
Path: neural/deployment/registry.py
Line: 82

Comment:
**Inaccurate pragma comment**

The `# pragma: no cover` comment says "exercised via tests with monkeypatch", which contradicts the purpose of a `no cover` annotation. The monkeypatch test `test_discover_providers_loads_entry_points_and_tracks_broken_plugins` does exercise the `_bad_loader` path through this `except` block. If the test is already covering this branch, the `pragma: no cover` should be removed so coverage accurately reflects the tested paths.

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

Incorrect mypy suppression directive

The # type: ignore[override] comment is not the correct mypy error code for this situation. Redefining a name in the same module scope is flagged by mypy as no-redef, not override (which is for method override mismatches in subclasses). This should be # type: ignore[no-redef] to suppress the correct diagnostic.

Suggested change

	class DockerDeploymentProvider: # type: ignore[override]
	class DockerDeploymentProvider: # type: ignore[no-redef]

Prompt To Fix With AI

This is a comment left during a code review.
Path: neural/deployment/__init__.py
Line: 81

Comment:
**Incorrect mypy suppression directive**

The `# type: ignore[override]` comment is not the correct mypy error code for this situation. Redefining a name in the same module scope is flagged by mypy as `no-redef`, not `override` (which is for method override mismatches in subclasses). This should be `# type: ignore[no-redef]` to suppress the correct diagnostic.

```suggestion
    class DockerDeploymentProvider:  # type: ignore[no-redef]
```

How can I resolve this? If you propose a fix, please make it concise.