Class JobRequirements

java.lang.Object
ai.redouble.nucleo.harness.JobRequirements
public class JobRequirements extends Object
Specifies the configuration for job execution. Contains all operation requirements functionality. Jobs declare: - Zero or more DBResourceProviders that the job will access - Whether automatic transaction management is needed - Maximum execution time for timeout enforcement - Model NEEDS via requireModel(Grade, Depth) / requireEmbeddings(int) / requireDecision(int) - a grade and depth, or a kind, never a concrete model: the harness resolves each returned ModelBinding through the deployment's picker at the requirements-resolution step, before any acquisition The scheduler uses these to: - Resolve model bindings, then assemble the job's whole Demand and hand it to Admission, which grants every account at once or parks the job holding nothing - Create appropriate JobResources with handles from each declared provider - Manage transaction lifecycle if requested - Enforce execution timeouts Note: rate limiting is admission: no request goes upstream before its budget was taken. Connection checkout happens inside each provider implementation, under a permit the admission already holds.
Since:
0.1 (2025-08-10)
Author:
Andrey Santrosyan

  • Constructor Details

    • JobRequirements

      public JobRequirements()

  • Method Details

    • addProvider

      public void addProvider(DBResourceProvider<?> provider)
      Declares that this job needs a handle from the given provider. Jobs may declare multiple providers; JobResources acquires one handle per provider in declaration order.

    • getProviders

      public List<DBResourceProvider<?>> getProviders()
      Returns a copy of the declared providers, in declaration order.

    • requiresTransaction

      public boolean requiresTransaction()

    • setRequiresTransaction

      public void setRequiresTransaction(boolean requiresTransaction)

    • requireModel

      public ModelBinding requireModel(Grade grade, Depth depth)
      Declares an LLM need whose sizes come from a wired conversation: mint the binding here, wire it with conversation.setModelBinding(binding), and the harness counts input under the resolved spec's tokenizer at resolution time.

      One binding per invocation. The dispatcher captures requirements once per attempt, and that capture is the last mint before resolution - so a job stashing the returned binding in a field always holds the cell that resolves.

    • requireModel

      public ModelBinding requireModel(Grade grade, Depth depth, int inTokens, OutputDeclaration output)
      Declares an LLM need with a flat input count and an output declaration - for jobs whose prompt is not built at requirements time. Both sides are required: the input is the job's own estimate, the output is a rung or a count, and the spec's thinking budget for the depth is added at pricing.

    • requireModelForPrompt

      public ModelBinding requireModelForPrompt(Grade grade, Depth depth, String promptText, OutputDeclaration output)
      Declares an LLM need priced from a prompt text the job already holds: the text is counted at resolution time under the resolved spec's tokenizer, plus the declared output and the spec's thinking budget for the depth.

    • requireModel

      public ModelBinding requireModel(ModelSpec pinned, Depth depth)
      Declares an LLM need pinned to an exact spec, wired to a conversation. Discouraged - a grade seat lets the picker keep the system resilient - but first-class: the pin skips only the picker consult; the compliance/kind/vision/deprecation gate still judges it, and a retry re-mints the same spec (no failover for pins).

    • requireModel

      public ModelBinding requireModel(ModelSpec pinned, Depth depth, int inTokens, OutputDeclaration output)
      Declares a pinned LLM need with flat token scalars. Same discouragement and gate posture as the wired pin.

    • requireEmbeddings

      public ModelBinding requireEmbeddings(int tokens)
      Declares an embeddings need. Embeddings are their own channel: no grade, resolved from the deployment's frozen declaration (ModelPicker.embeddingsSpec).

    • requireEmbeddings

      public ModelBinding requireEmbeddings(ModelSpec pinned, int tokens)
      Declares an embeddings need pinned to an exact spec, still subject to the gate.

    • requireDecision

      public ModelBinding requireDecision(int tokens)
      Declares a decision need with a flat input count. Decision models are their own channel: no grade, resolved from the deployment's declaration (ModelPicker.decisionSpec).

    • requireDecisionForText

      public ModelBinding requireDecisionForText(String requestText)
      Declares a decision need priced from the request text the job already holds: the text is counted at resolution time under the resolved spec's tokenizer, and a state past the entry's ceiling fails there instead of on the wire.

    • requireDecision

      public ModelBinding requireDecision(ModelSpec pinned, int tokens)
      Declares a decision need pinned to an exact spec, still subject to the gate.

    • requireDecisionForText

      public ModelBinding requireDecisionForText(ModelSpec pinned, String requestText)
      Declares a decision need pinned to an exact spec and priced from the request text.

    • getModelBindings

      public List<ModelBinding> getModelBindings()
      The declared model bindings, in declaration order. The harness resolves each before acquisition.

    • requireRateLimiter

      public <T> void requireRateLimiter(RateLimiter<T> limiter, T input)
      Adds a custom rate limiter requirement with its amount.
      Type Parameters:
      T - The amount type the limiter expects
      Parameters:
      limiter - The rate limiter to require
      input - The amount the demand carries on the limiter (null for unit permits)

    • getCustomRateLimiters

      public Map<RateLimiter<?>, Object> getCustomRateLimiters()
      Gets all custom rate limiter requirements, in declaration order.
      Returns:
      Map of rate limiters to their amounts

    • requiresCustomRateLimiters

      public boolean requiresCustomRateLimiters()
      Checks if this job requires any custom rate limiters.
      Returns:
      true if custom rate limiters are required

    • isReadOnly

      public boolean isReadOnly()

    • setReadOnly

      public void setReadOnly(boolean readOnly)

    • requiresQueueing

      public boolean requiresQueueing()

    • setRequiresQueueing

      public void setRequiresQueueing(boolean requiresQueueing)

    • requiresDatabase

      public boolean requiresDatabase()
      Returns:
      true if this job requires any database provider

    • requiresLlm

      public boolean requiresLlm()
      Checks if this job requires any LLM resources.
      Returns:
      true if any LLM binding is declared

    • requiresEmbeddings

      public boolean requiresEmbeddings()
      Checks if this job requires any embeddings resources.
      Returns:
      true if any embeddings binding is declared

    • requiresDecision

      public boolean requiresDecision()
      Checks if this job requires any decision resources.
      Returns:
      true if any decision binding is declared

    • requiresResources

      public boolean requiresResources()
      Checks if this job requires ANY resources: database, LLM, embeddings, decision, custom rate limiters, or the shared HTTP connection gate. Every such job has a non-empty demand and holds a permit while it runs, so it must have a timeout and must not block on a child job's completion (deadlock prevention).
      Returns:
      true if any resources are required

    • toleratesDependencyFailures

      public boolean toleratesDependencyFailures()
      Gets whether this job can tolerate dependency failures. If true, the job's execute method will be called even if some dependencies fail. The job can then decide how to handle the failures.
      Returns:
      true if the job tolerates dependency failures

    • setToleratesDependencyFailures

      public void setToleratesDependencyFailures(boolean tolerates)
      Sets whether this job can tolerate dependency failures.
      Parameters:
      tolerates - true to allow execution even with failed dependencies

    • setRequiresHttpConnection

      public void setRequiresHttpConnection(boolean requires)
      Explicitly declares that this job requires HTTP connections. Use this for jobs that make HTTP calls without going through LLM/embeddings APIs.
      Parameters:
      requires - true if HTTP connections are needed

    • requiresHttpConnection

      public boolean requiresHttpConnection()
      Checks if this job needs HTTP connections. Returns true if: explicitly declared, OR uses LLM, OR uses embeddings, OR any custom rate limiter requires HTTP.
      Returns:
      true if HTTP connections are needed