Metadata-Version: 2.4
Name: histserv
Version: 0.1.0
Summary: Histogramming as a Service
Project-URL: Homepage, https://github.com/pfackeldey/histserv
Project-URL: Bug Tracker, https://github.com/pfackeldey/histserv/issues
Project-URL: Discussions, https://github.com/pfackeldey/histserv/discussions
Author-email: pfackeldey <fackeldey.peter@gmail.com>
License-Expression: BSD-3-Clause
License-File: LICENSE
Keywords: boost-histogram,distributed,histogram,serving
Classifier: Development Status :: 1 - Planning
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: boost-histogram>=1.7.1
Requires-Dist: grpcio-tools>=1.78.0
Requires-Dist: grpcio>=1.76.0
Requires-Dist: hist>=2.9.0
Requires-Dist: numcodecs>=0.13.1
Requires-Dist: uhi>=1.0.0
Description-Content-Type: text/markdown

# Histogramming as a Service (HistServ)

## Install
```shell
uv pip install .
```

## Example

See `example/`.

Start gRPC server (or just `./example/start_server.sh`):
```shell
histserv-server --port 50051 --n-threads 4
# INFO:histserv-server:Histogram server started, listening on [::]:50051 with 4 threads
```

Run example client:
```shell
python example/client.py
# Remote hist initialized: RemoteHist<ID=765396215d2a4cef8c232b8085ea369f @[::]:50051>
# Histogram remote_hist received: success: true
#
# Snapshotting current hist: Hist(
#   Regular(10, -2, 2, name='x', label='X Axis'),
#   Regular(10, -2, 2, name='y', label='Y Axis'),
#   StrCategory(['data', 'drell-yan'], growth=True, name='dataset', label='Dataset'),
#   storage=Weight()) # Sum: WeightedSum(value=911611, variance=911611) (WeightedSum(value=1e+06, variance=1e+06) with flow)
#
# Histogram remote_hist received: success: true
#
# Histogram remote_hist received: success: true
# 
# Histogram remote_hist received: Histogram flushed successfully to hist.h5.
```

Or an example coffea Processor:
```shell
python example/coffea_processor.py
# All remote fills succeeded!
# Output hist: Hist(
#   Regular(10, -2, 2, name='x', label='X Axis'),
#   Regular(10, -2, 2, name='y', label='Y Axis'),
#   StrCategory(['data', 'drell-yan'], growth=True, name='dataset', label='Dataset'),
#   storage=Weight()) # Sum: WeightedSum(value=3.64502e+06, variance=3.64502e+06) (WeightedSum(value=4e+06, variance=4e+06) with flow)
```


And the server logs additionally (after running the client script):
```shell
# INFO:histserv-server:Filled histogram with 24,000,000 bytes
# INFO:histserv-server:Filled histogram with 24,000,000 bytes
# INFO:histserv-server:Filled histogram with 24,000,000 bytes
# INFO:histserv-server:Flushed histogram to hist.h5
```

## Current supported types

Axis support:
- `hist.axis.Regular`
- `hist.axis.Boolean`
- `hist.axis.Variable`
- `hist.axis.Integer`
- `hist.axis.IntCategory`
- `hist.axis.StrCategory`

`np.dtype` support for `hist.axis.{Regular,Variable,Integer}`:
- `np.float64`
- `np.float32`
- `np.int64`
- `np.int32`


## Developer Info

### Install
```shell
uv pip install -e . --group=dev
```

### protobuf codegen

```shell
python -m grpc_tools.protoc -Isrc/histserv/protos --python_out=src/histserv/protos --pyi_out=src/histserv/protos --grpc_python_out=src/histserv/protos src/histserv/protos/hist.proto
```
Maybe adjust imports in `src/histserv/protos/hist_pb2_grpc.py`.
