Skip to main content

​
What is the CSP Service?

The CSP Service is a Java-based microservice that wraps the Choco constraint solver to perform rigorous mathematical validation and analysis of SaaS pricing models. It’s the engine behind the platform’s ability to verify pricing consistency, enumerate valid configurations, and detect logical errors in complex pricing structures.
The CSP Service is based on Choco Solver 4.0.9, a powerful open-source Java library for Constraint Programming.

​
Architecture Position

The CSP Service sits at the core of the pricing analysis pipeline: The Analysis API (Node.js/TypeScript) delegates all constraint satisfaction operations to the CSP Service, which encodes pricing models as constraint satisfaction problems and solves them using Choco.

​
Key Capabilities

The CSP Service provides several critical capabilities for pricing intelligence:

​
1. Model Validation

Validates the mathematical consistency of a pricing model by:
  • Ensuring all plans have at least one feature enabled
  • Verifying add-ons are available for at least one plan
  • Checking dependency and exclusion constraints
  • Detecting duplicate plans or add-ons
  • Validating linked features and usage limits
  • Identifying unreachable features or usage limits

​
2. Configuration Space Enumeration

Enumerates all valid subscription configurations (plan + add-on combinations) that satisfy the model’s constraints:
  • Plan selection constraints
  • Add-on availability rules
  • Dependency relationships (add-on A requires add-on B)
  • Exclusion relationships (add-on A excludes add-on B)
  • Cost calculations

​
3. Constraint Programming

The service models pricing as a CSP with:
  • Variables: Selected plan, selected add-ons, subscription cost
  • Domains: Integer ranges for plans/add-ons, costs in cents
  • Constraints: Availability, dependencies, exclusions, feature requirements

​
Technology Stack

Spring Boot

Java web framework (v3.4.1)

Choco Solver

Constraint solver library (v4.0.9)

Pricing4Java

Pricing model library (v5.5.2)

Maven

Build and dependency management

​
How It Works

The CSP Service follows a multi-step pipeline when processing a pricing model:

​
Step 1: Parse YAML Input

The service receives a YAML file containing the pricing model in the Pricing2YAML format. It uses the Yaml2CSP parser to:
  • Load and validate YAML syntax
  • Parse into a PricingManager object using Pricing4Java
  • Handle various error types (file errors, YAML errors, parsing errors)

​
Step 2: Extract Data Structures

From the PricingManager, the service extracts:
  • Lists: Features, usage limits, plans, add-ons, prices
  • Binary Matrices: Linked features, plan features, add-on availability
  • Numeric Matrices: Usage limits per plan, usage limit extensions
  • Dependency Matrices: Add-on dependencies and exclusions

​
Step 3: Define Choco Variables

The service creates integer variables in the Choco model: 
selectedPlan = model.intVar("selectedPlan", 0, plans.size() - 1)
selectedAddOns = model.intVarArray("selectedAddOns", addOns.size(), 0, 1)
subscriptionCost = model.intVar("subscriptionCost", 0, UNLIMITED)

​
Step 4: Post Constraints

The service adds constraints to the model:
  • Existence constraints: At least one plan or add-on must be selected
  • Availability constraints: Selected add-ons must be available for the selected plan
  • Dependency constraints: If add-on A is selected and depends on B, then B must be selected
  • Exclusion constraints: If add-on A excludes B, they cannot both be selected
  • Feature constraints: Plans must have enabled features for positive usage limits
  • Duplicate detection: No two plans or add-ons should be identical

​
Step 5: Solve and Return Results

Choco’s solver:
  1. Propagates constraints to reduce variable domains
  2. Searches for all solutions using backtracking
  3. Returns the configuration space with all valid subscriptions
If the model is unsatisfiable, the service provides explanations using Choco’s explanation engine to identify which constraints failed.

​
Constraint Types

The CSP Service implements several types of constraints:
  • Each plan must have at least one feature
  • Each add-on must provide at least one feature, usage limit, or extension
  • Each add-on must be available for at least one plan
  • Features and usage limits must be reachable from at least one plan or add-on
  • Add-ons must be available for the selected plan
  • Add-on dependencies: if A depends on B, selecting A forces B to be selected
  • Add-on exclusions: if A excludes B, they cannot both be selected
  • No circular dependencies between add-ons
  • If a feature is linked to usage limits, at least one linked limit must be positive
  • If a usage limit is positive and linked to features, at least one linked feature must be enabled
  • Usage limits must be non-negative
  • No duplicate plans (same features and usage limits)
  • No duplicate add-ons (same features, limits, dependencies, exclusions)
  • Plan cost is determined by the selected plan’s price
  • Add-on costs are calculated only for selected add-ons
  • Total subscription cost = plan cost + sum of selected add-on costs
  • All costs are represented in cents (scaled by 100)

​
Configuration

The CSP Service is configured via Docker Compose:
docker-compose.yml
choco-api:
  build:
    context: .
    dockerfile: csp/Dockerfile
  ports:
    - "8000:8000"
  environment:
    - PORT=8000
    - LOG_LEVEL=INFO
  healthcheck:
    test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
    interval: 30s
    timeout: 10s
    retries: 3

​
Environment Variables

​
PORT
integer
default:"8000"
The port on which the service listens for HTTP requests.
​
LOG_LEVEL
string
default:"INFO"
Logging level. Options: DEBUG, INFO, WARN, ERROR.

​
Service Endpoints

The CSP Service exposes a single REST endpoint:
  • POST /validate - Validates a pricing model and returns the configuration space
See the Solver Endpoint page for detailed API documentation.

​
Dependencies

The service relies on two key Java libraries:

​
Choco Solver 4.0.9

Choco is an open-source Java library for constraint programming. It provides:
  • Integer, Boolean, and Set variables
  • Propagation-based constraint solving
  • Explanation engine for unsatisfiable problems
  • Search strategies and heuristics
  • GitHub Repository

​
Pricing4Java 5.5.2

Pricing4Java is a library developed by the ISA Group for modeling and managing SaaS pricing. It provides:
  • The PricingManager domain model
  • YAML parsing and serialization
  • Feature and usage limit types
  • Version management
  • GitHub Repository

​
Error Handling

The CSP Service returns structured error messages with different error types:
​
messageType
MessageType
required
The type of error encountered:
  • SUCCESS - Model is valid
  • VALIDATION_ERROR - Constraint violation detected
  • FILE_ERROR - File path invalid or file not found
  • YAML_ERROR - YAML syntax error
  • PARSER_ERROR - Error parsing pricing model
​
errors
array
List of error messages explaining what went wrong. Each constraint that fails includes a descriptive name explaining the issue.

​
Performance Considerations

For large pricing models with many plans, add-ons, and constraints, solving can be computationally expensive. The service uses a 2-minute timeout for operations.
The solving time depends on:
  • Number of plans and add-ons
  • Number of features and usage limits
  • Complexity of dependency/exclusion relationships
  • Presence of linked features
Typical solve times:
  • Simple models (2-4 plans, 0-2 add-ons): < 1 second
  • Medium models (5-10 plans, 3-10 add-ons): 1-5 seconds
  • Complex models (10+ plans, 10+ add-ons): 5-30 seconds

​
Next Steps

Solver Endpoint

Detailed API documentation for the /validate endpoint

Analysis API

Learn how the Analysis API uses the CSP Service

Build docs developers (and LLMs) love

Get started for freeTalk to us