Update documentation with Product API instructions

Author: szemate

DEVELOPMENT.md

@@ -0,0 +1,44 @@
+# Development
+
+The package uses [`uv`](https://docs.astral.sh/uv/) as project manager.
+
+- Install dependencies with the `uv sync` command.
+- Execute linters with the `uv run poe lint` command.
+- Run tests with the `uv run poe test` command.
+- Check distributions before release with the `uv run poe check-dist` command.
+- Generate markdown API documentation with the `uv run poe doc-gen` command.
+
+## Product Specification
+
+A product specification is represented as a single JSON object, but it is stored
+at two different places:
+
+- The object under the `product` attribute is uploaded to the Product Registry contract.
+- The other nested objects constitute the extended metadata and are uploaded to IPFS.
+- The `extendedMetadata` property of the on-chain product specification stores
+  the root CID of the IPFS DAG.
+
+### Updating Extended Metadata Schemas
+
+Extended metadata schemas are versioned and an IPFS CID is associated with each
+version of each schema. For each schema there is also a matching Pydantic model
+in the `afp.schemas` module.
+
+When extended metadata schemas are updated, the related model updates should be
+backwards-compatible to make sure existing products that use old schemas can be still
+be downloaded from IPFS and parsed.
+
+To modify models in backwards-compatible way, e.g. when the `OracleFallback` schema
+is updated from v0.2.0 to v0.2.1, do the following:
+
+- Make a private duplicate of the Pydantic model that needs to be updated, e.g.
+  duplicate `OracleFallback` as `_OracleFallbackV020`.
+- Modify the fields of the public model (`OracleFallback`) to match the updated
+  schema.
+- Update `OracleFallback.SCHEMA_CID` to the CID of the updated schema. Keep the
+  old CID in `_OracleFallbackV020.SCHEMA_CID`.
+
+With the above changes, if a product is downloaded that still uses the old
+`OracleFallback` schema then it will be parsed using the `_OracleFallbackV020`
+model, however users will see the updated `OracleFallback` schema as part of the
+public API.

README.md

@@ -162,49 +162,73 @@ fills = trading.order_fills(product_id=PRODUCT_ID)
 print(fills)
 ```
 
-See further code examples in the [examples](./examples/) directory.
+### Product API
 
-## Development
+Use the `Product` session object to validate a product schema, pin the
+specification to IPFS, and register it on-chain.
+
+In order to use the product API for product building, connection parameters of
+an IPFS pinning service like [Filebase](https://filebase.com/) should be
+included in the `AFP` constructor parameters.
+
+```py
+IPFS_API_URL = "https://rpc.filebase.io"
+IPFS_API_KEY = os.environ["IPFS_API_KEY"]
+
+app = afp.AFP(
+    rpc_url=AUTONITY_RPC_URL,
+    authenticator=afp.PrivateKeyAuthenticator(PRIVATE_KEY),
+    ipfs_api_url=IPFS_API_URL,
+    ipfs_api_key=IPFS_API_KEY,
+)
+
+product = app.Product()
+```
 
-The package uses [`uv`](https://docs.astral.sh/uv/) as project manager.
+A JSON product specification can be parsed and validated with
+`product.validate_json()`.
 
-- Install dependencies with the `uv sync` command.
-- Execute linters with the `uv run poe lint` command.
-- Run tests with the `uv run poe test` command.
-- Check distributions before release with the `uv run poe check-dist` command.
-- Generate markdown API documentation with the `uv run poe doc-gen` command.
+```py
+with open("product-spec.json") as spec_file:
+    specification = product.validate_json(spec_file.read())
+```
+
+Alternatively, it can also be validated from a Python dictionary.
 
-## Product Specification
+```py
+spec_dict = {
+    "product": {...},
+    "outcome_space": {...},
+    "outcome_point": {...},
+    "oracle_config": {...},
+    "oracle_fallback": {...},
+}
+specification = product.validate(spec_dict)
+```
 
-A product specification is represented as a single JSON object, but it is stored
-at two different places:
+Product specifications are stored at two different places, the `PredictionProductV1`
+object is stored on-chain in the Product Registry contract, while the rest of the
+product specification is referred to as _extended metadata_ and it is uploaded to IPFS.
 
-- The object under the `product` attribute is uploaded to the Product Registry contract.
-- The other nested objects constitute the extended metadata and are uploaded to IPFS.
-- The `extendedMetadata` property of the on-chain product specification stores
-  the root CID of the IPFS DAG.
+The first step therefore is to upload the extended metadata of the product to
+IPFS and to pin the root node of the DAG. `product.pin()` returns a modified
+copy of the specification that incudes the extended metadata CID.
 
-### Updating Extended Metadata Schemas
+```py
+pinned_specification = product.pin(specification)
+```
 
-Extended metadata schemas are versioned and an IPFS CID is associated with each
-version of each schema. For each schema there is also a matching Pydantic model
-in the `afp.schemas` module.
+The product can then be registered with the Product Registry contract via a
+blockchain transaction.
 
-When extended metadata schemas are updated, the related model updates should be
-backwards-compatible to make sure existing products that use old schemas can be still
-be downloaded from IPFS and parsed.
+```
+tx = product.register(
+    pinned_specification, initial_builder_stake=Decimal("10")
+)
+```
 
-To modify models in backwards-compatible way, e.g. when the `OracleFallback` schema
-is updated from v0.2.0 to v0.2.1, do the following:
+See further code examples in the [examples](./examples/) directory.
 
-- Make a private duplicate of the Pydantic model that needs to be updated, e.g.
-  duplicate `OracleFallback` as `_OracleFallbackV020`.
-- Modify the fields of the public model (`OracleFallback`) to match the updated
-  schema.
-- Update `OracleFallback.SCHEMA_CID` to the CID of the updated schema. Keep the
-  old CID in `_OracleFallbackV020.SCHEMA_CID`.
+## Development
 
-With the above changes, if a product is downloaded that still uses the old
-`OracleFallback` schema then it will be parsed using the `_OracleFallbackV020`
-model, however users will see the updated `OracleFallback` schema as part of the
-public API.
+See [DEVELOPMENT.md](./DEVELOPMENT.md) for developer documentation.

afp/api/product.py

@@ -58,6 +58,11 @@ def validate(self, product_dict: dict[str, Any]) -> PredictionProduct:
         Returns
         -------
         afp.schemas.PredictionProduct
+
+        Raises
+        ------
+        ValueError, afp.exceptions.ValidationError
+            If the product specification fails validation.
         """
         return self._verify_product_spec(PredictionProduct.model_validate(product_dict))
 
@@ -74,6 +79,11 @@ def validate_json(self, product_json: str) -> PredictionProduct:
         Returns
         -------
         afp.schemas.PredictionProduct
+
+        Raises
+        ------
+        ValueError, afp.exceptions.ValidationError
+            If the product specification fails validation.
         """
         return self._verify_product_spec(
             PredictionProduct.model_validate_json(product_json)
@@ -147,6 +157,11 @@ def pin(self, product_spec: PredictionProduct) -> PredictionProduct:
         -------
         afp.schemas.PredictionProduct
             The product specification with extended metadata CID included.
+
+        Raises
+        ------
+        afp.exceptions.IPFSError
+            If there is an error uploading to the IPFS node.
         """
         extended_metadata_cid = self._ipfs_client.upload_extended_metadata(
             ExtendedMetadata(