PR #1, Weeks 3-4: implement core protocol + bind_observation

[Jocho-Smith]

Implements the first GSoC 2026 deliverable for the PotentialFunction API redesign.

Layer 1 - Core Protocol:

• Add PotentialFunction protocol (stateless callable: theta, x -> log_prob)
• Add PotentialFunctionWithDevice protocol with device property
  • maybe over-engineered that these are two separate protocols?
• Add validate_potential() helper for runtime protocol validation
  • (somewhat optional). Is something like this of use?
  • "import inspect" inside function. What do you think about this?

Layer 2 - Binding Utilities:

• Add bind_observation() utility for creating sampler-ready functions
• Add BoundPotential class as alternative class-based binding
• Implement IID handling via sum_iid parameter
• Implement device validation with error messages

Testing:

• Add comprehensive unit tests (18 tests) covering:
  • Protocol validation and compliance
  • bind_observation functionality
  • IID handling (sum_iid)
  • Device validation and mismatch errors
  • Statelessness (property-based: repeated calls yield identical outputs)
  • Gradient tracking (pure pytorch)
  • Backward compatibility with existing LikelihoodBasedPotential

Open questions:

• should I (and maybe Satwik too) merge this to another 'gsoc specific' branch instead of sbi/main? Or use the github functionality "Create draft pull request"?
  • I think it might be useful to stage the 'half ready' PRs instead of merging them directly. That way core maintainers don't have to worry about unfinished code in the repo and 'we developers' can work in iterated PRs without having to worry about 'breaking things' too much too early. Does that make sense?

Note:

• I tried opencode for this PR, especially for the tests and doc strings. I didn't use any agent.md/skill.md files for now.
• This PR#1 does not enable the new potential routine yet, only after PR#2 we can start checking numerical tests, deprecation scenarios and first migrations.

[codecov]

Codecov Report

❌ Patch coverage is 81.25000% with 12 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.85%. Comparing base (9cf0d9e) to head (7601c08).

Files with missing lines	Patch %	Lines
sbi/inference/potentials/binding.py	75.00%	11 Missing ⚠️
sbi/inference/potentials/protocol.py	94.44%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1876      +/-   ##
==========================================
- Coverage   87.89%   87.85%   -0.04%     
==========================================
  Files         143      145       +2     
  Lines       13353    13417      +64     
==========================================
+ Hits        11736    11788      +52     
- Misses       1617     1629      +12     

Flag	Coverage Δ
fast	81.39% <81.25%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
sbi/inference/potentials/__init__.py	100.00% <100.00%> (ø)
sbi/inference/potentials/protocol.py	94.44% <94.44%> (ø)
sbi/inference/potentials/binding.py	75.00% <75.00%> (ø)

[satwiksps]

should I (and maybe Satwik too) merge this to another 'gsoc specific' branch instead of sbi/main? Or use the github functionality "Create draft pull request"?

I was thinking the same thing. For NN Builder API Refactor also there would be 8 PRs. Also my upcoming PR 2 requires my PR 1 to be merged, so I would be creating PR 2 as draft PR. Maybe a GSoC specific branch would be a good thing. Am okay with whatever maintainers prefer.

[janfb]

Thanks, @Jocho-Smith and @satwiksps! just briefly here to unblock you. Yes, it's actually a good idea, if your PRs are introducing breaking changes. We are planning to do a release soon, and we don't want to introduce breaking changes in there.

That said, the PRs that go into that branch should be treated as if they go into main, e.g., fully reviewed by us and functional. We want to avoid the situation where half ready PRs accumulate in a branch with a massive diff to main, that we then have to review again.

So, yes, let's merge your PRs, into an intermediate gsoc-2026 branch, treat it as your main branch, i.e., you both use the same one.

Hope this helps!