httpstan

Warnings

• breaking httpstan requires a modern C++ compiler (gcc >=9.0 or clang >=10.0) on the system. Installing on environments with older compilers will lead to build failures or runtime errors with 'undefined symbol'.
  Fix: Ensure your system has an up-to-date C++ compiler. For Linux, this often means upgrading `build-essential`. For macOS, ensure Xcode command line tools are updated.
• gotcha httpstan officially supports only Linux and macOS on x86-64 CPUs. Installation on Windows is not supported via PyPI wheels and will likely result in 'No matching distribution found' errors or complex build failures if attempting from source.
  Fix: Use a Linux or macOS environment, or consider using Windows Subsystem for Linux (WSL), a virtual machine, or Docker.
• gotcha Users may encounter 'No matching distribution found for httpstan' when trying to install, especially for newer Python versions or on specific platforms. This can be due to an outdated `pip` or delayed wheel availability for a specific Python version.
  Fix: First, upgrade `pip`: `python -m pip install --upgrade pip`. If the issue persists for a new Python version, check httpstan's GitHub releases or issues for announcements regarding wheel availability. Building from source might be an option if documented.
• deprecated The primary maintainer of httpstan has announced a hiatus from active maintenance starting September 2024. While the project is stable, this might impact the cadence of future updates, feature development, and responsiveness to issues unless new maintainers step forward.
  Fix: Monitor the Stan developer forums and GitHub repository for updates on project stewardship and maintenance plans. Be prepared for potentially slower response times or consider contributing to the project.

Install

• pip install httpstan Install via pip

Imports

• httpstan module (as server)

  python3 -m httpstan

  httpstan is primarily designed to be run as a separate HTTP server process, not typically imported directly for user-facing functions within client Python code. Client applications (like PyStan) interact with it via its REST API. Internal modules such as `httpstan.models` or `httpstan.services` are used by client libraries, but rarely by end-users directly.

Quickstart

To use httpstan, first run it as a standalone server. Then, interact with its REST API using HTTP requests to compile Stan models and draw samples. This example demonstrates compiling a simple Stan program and initiating sampling using the `requests` library.

import os
import subprocess
import time
import requests

# Ensure httpstan is running in the background
# In a real application, you might use a more robust process management.
# For this example, we assume it's already running or launched separately.
# If not running, uncomment the subprocess call below and handle its lifecycle.
# subprocess.Popen(['python3', '-m', 'httpstan'])
# time.sleep(5) # Give the server a moment to start

# Define a simple Stan program
program_code = """
parameters {real y;} model {y ~ normal(0,1);}
"""

# Compile the Stan program
response = requests.post(
    'http://localhost:8080/v1/models',
    json={'program_code': program_code}
)
response.raise_for_status()
model_name = response.json()['name']
print(f"Model compiled with name: {model_name}")

# Draw samples from the compiled model
sample_response = requests.post(
    f'http://localhost:8080/v1/{model_name}/actions',
    json={'type': 'stan::services::sample::hmc_nuts_diag_e_adapt'}
)
sample_response.raise_for_status()

# In a real scenario, you'd typically stream the results from the response.iter_lines()
# For simplicity, this example just prints the first few lines of the output.
print("\nFirst few lines of sampling output:")
for line in sample_response.iter_lines():
    print(line.decode('utf-8'))
    # Break after a few lines for brevity in quickstart
    if len(line) > 100: # Heuristic to get some actual output
        break