feat: discovery module with config model

README.md

@@ -97,6 +97,11 @@ additional code to set up error handling and basic Bento service boilerplate.
 
 `db` contains common base classes for setting up database managers.
 
+### `discovery`
+
+`discovery` contains models and helper functions for the Bento Discovery Configuration specification, used
+in [Katsu](https://github.com/bento-platform/katsu).
+
 ### `drs`
 
 `drs` provides utilities for fetching data and record metadata from 

bento_lib/__init__.py

@@ -2,6 +2,7 @@
 
 from . import apps
 from . import auth
+from . import discovery
 from . import drs
 from . import events
 from . import schemas
@@ -12,5 +13,15 @@
 
 __version__ = metadata.version(__name__)
 __all__ = [
-    "__version__", "apps", "auth", "drs", "events", "schemas", "search", "service_info", "streaming", "workflows"
+    "__version__",
+    "apps",
+    "auth",
+    "discovery",
+    "drs",
+    "events",
+    "schemas",
+    "search",
+    "service_info",
+    "streaming",
+    "workflows",
 ]

bento_lib/discovery/__init__.py

@@ -0,0 +1,4 @@
+from . import helpers
+from . import models
+
+__all__ = ["helpers", "models"]

bento_lib/discovery/models/config.py

@@ -0,0 +1,22 @@
+from pydantic import BaseModel
+
+from .fields import DateFieldDefinition, NumberFieldDefinition, StringFieldDefinition
+from .overview import OverviewSection
+from .search import SearchSection
+
+__all__ = [
+    "DiscoveryConfigRules",
+    "DiscoveryConfig",
+]
+
+
+class DiscoveryConfigRules(BaseModel):
+    count_threshold: int
+    max_query_parameters: int
+
+
+class DiscoveryConfig(BaseModel):
+    overview: list[OverviewSection]
+    search: list[SearchSection]
+    fields: dict[str, DateFieldDefinition | NumberFieldDefinition | StringFieldDefinition]
+    rules: DiscoveryConfigRules

bento_lib/discovery/models/fields.py

@@ -0,0 +1,69 @@
+from pydantic import AliasChoices, BaseModel, Field
+from typing import Literal
+
+__all__ = [
+    "BaseFieldDefinition",
+    # string
+    "StringFieldConfig",
+    "StringFieldDefinition",
+    # number
+    "BaseNumberFieldConfig",
+    "ManualBinsNumberFieldConfig",
+    "AutoBinsNumberFieldConfig",
+    "NumberFieldDefinition",
+    # date
+    "DateFieldConfig",
+    "DateFieldDefinition",
+]
+
+
+class BaseFieldDefinition(BaseModel):
+    mapping: str
+    title: str  # TODO: make optional and pull from Bento schema if not set
+    description: str  # TODO: make optional and pull from Bento schema if not set
+    datatype: Literal["string", "number", "date"] = Field(validation_alias=AliasChoices("data_type", "datatype"))
+    # --- The below fields are currently valid, but need to be reworked for new search ---------------------------------
+    mapping_for_search_filter: str | None = None
+    group_by: str | None = None
+    group_by_value: str | None = None
+    value_mapping: str | None = None
+    # ------------------------------------------------------------------------------------------------------------------
+
+
+class StringFieldConfig(BaseModel):
+    enum: list[str] | None
+
+
+class StringFieldDefinition(BaseFieldDefinition):
+    datatype: Literal["string"]
+    config: StringFieldConfig
+
+
+class BaseNumberFieldConfig(BaseModel):
+    units: str
+
+
+class ManualBinsNumberFieldConfig(BaseNumberFieldConfig):
+    bins: list[int]
+
+
+class AutoBinsNumberFieldConfig(BaseNumberFieldConfig):
+    bin_size: int
+    taper_left: int
+    taper_right: int
+    minimum: int
+    maximum: int
+
+
+class NumberFieldDefinition(BaseFieldDefinition):
+    datatype: Literal["number"]
+    config: ManualBinsNumberFieldConfig | AutoBinsNumberFieldConfig
+
+
+class DateFieldConfig(BaseModel):
+    bin_by: str  # TODO
+
+
+class DateFieldDefinition(BaseFieldDefinition):
+    datatype: Literal["date"]
+    config: DateFieldConfig

bento_lib/discovery/models/overview.py

@@ -0,0 +1,17 @@
+from pydantic import BaseModel
+from typing import Literal
+
+__all__ = [
+    "OverviewChart",
+    "OverviewSection",
+]
+
+
+class OverviewChart(BaseModel):
+    field: str
+    chart_type: Literal["bar", "choropleth", "histogram", "pie"]
+
+
+class OverviewSection(BaseModel):
+    section_title: str
+    charts: list[OverviewChart]

bento_lib/discovery/models/search.py

@@ -0,0 +1,8 @@
+from pydantic import BaseModel
+
+__all__ = ["SearchSection"]
+
+
+class SearchSection(BaseModel):
+    section_title: str
+    fields: list[str]