Omit examples specifications (#105)

docs/index.rst

@@ -4,13 +4,7 @@ Opvious SDK
 ===========
 
 A Python SDK for solving linear, mixed-integer, and quadratic optimization 
-models
-
-.. note::
-  Opvious is currently in beta. You can preview the SDK's functionality on small 
-  datasets without registering but you will need an API key to solve larger 
-  instances. You can request to join `here <https://www.opvious.io/signup>`_ or 
-  by contacting us at [email protected].
+models with the `Opvious platform`_
 
 
 Highlights
@@ -39,10 +33,9 @@ First install the SDK, for example using `pip`:
   be omitted for compatibility with `Pyodide`_ environments, for example in 
   `JupyterLite`_ kernels.
 
-If you are a beta member (see above), we recommend you generate an API access 
-token in the `Optimization Hub`_ and set it as `OPVIOUS_TOKEN` environment 
-variable. This optional step allows you to optimize larger datasets and 
-increases rate limits.
+We recommend you generate an `API access token`_ and set it as `OPVIOUS_TOKEN` 
+environment variable. This optional step allows you to optimize larger datasets 
+and increases rate limits.
 
 You are now ready to hop on over to the :ref:`Overview` section!
 
@@ -69,7 +62,8 @@ External resources
 + `PyPI entry`_
 
 
-.. _Optimization Hub: https://hub.beta.opvious.io/
+.. _Opvious platform: https://www.opvious.io
+.. _API access token: https://hub.cloud.opvious.io/authorizations
 .. _pandas: https://pandas.pydata.org
 .. _Pyodide: https://pyodide.org
 .. _JupyterLite: https://jupyterlite.readthedocs.io

opvious/client/handlers.py

@@ -95,7 +95,7 @@ def default(
                 authentication will be set.
             endpoint: API endpoint. If absent, defaults to the
                 `$OPVIOUS_ENDPOINT` environment variable, falling back to the
-                Cloud production endpoint if neither is present.
+                cloud endpoint if neither is present.
         """
         authorization = None
         if token is True or (not token and token is not False):
@@ -137,7 +137,7 @@ def executor(self) -> Executor:
 
     @property
     def authenticated(self) -> bool:
-        """Returns true if the client was created with a non-empty API token"""
+        """Returns true if the client is using a non-empty API token"""
         return self._executor.authenticated
 
     async def annotate_specification(
@@ -292,11 +292,15 @@ async def summarize(self, problem: Problem) -> SolveSummary:
         ) as res:
             return solve_summary_from_json(res.json_data())
 
-    async def inspect_instructions(self, problem: Problem) -> str:
+    async def inspect_instructions(
+        self, problem: Problem, include_line_comments=False
+    ) -> str:
         """Returns the problem's representation in `LP format`_
 
         Args:
             problem: :class:`.Problem` instance to inspect
+            include_line_comments: Include comment lines in the output. By
+                default these lines are only logged as DEBUG messages.
 
         The LP formatted output will be fully annotated with matching keys and
         labels:
@@ -334,6 +338,8 @@ async def inspect_instructions(self, problem: Problem) -> str:
             async for line in res.lines():
                 if line.startswith("\\"):
                     _logger.debug(line[2:].strip())
+                    if not include_line_comments:
+                        continue
                 lines.append(line)
             return "".join(lines)
 
@@ -360,7 +366,7 @@ async def solve(
 
             solution = await client.solve(
                 opvious.Problem(
-                    specification=opvious.RemoteSpecification.example(
+                    specification=opvious.FormulationSpecification(
                         "porfolio-selection"
                     ),
                     parameters={
@@ -475,17 +481,7 @@ async def queue(self, problem: Problem) -> Attempt:
         as enough capacity is available.
 
         Args:
-            specification: Model :class:`.FormulationSpecification` or
-                formulation name
-            parameters: Input data, keyed by parameter label. Values may be any
-                value accepted by :meth:`.Tensor.from_argument` and must match
-                the corresponding parameter's definition.
-            dimensions: Dimension items, keyed by dimension label. If omitted,
-                these will be automatically inferred from the parameters.
-            transformations: :ref:`Transformations`
-            strategy: :ref:`Multi-objective strategy <Multi-objective
-                strategies>`
-            options: Solve options
+            problem: :class:`.Problem` instance to solve
 
         The returned :class:`Attempt` instance can be used to:
 

opvious/specifications/external.py

@@ -6,30 +6,13 @@
 from ..executors import Executor, PlainTextExecutorResult
 
 
-_EXAMPLE_URL_PREFIX = (
-    "https://raw.githubusercontent.com/opvious/examples/main/sources"  # noqa
-)
-
-
 @dataclasses.dataclass(frozen=True)
 class RemoteSpecification:
-    """A model specification from a remote URL
-
-    This is typically useful for examples.
-    """
+    """A model specification from a remote URL"""
 
     url: str
     """The specification's http(s) URL"""
 
-    @classmethod
-    def example(cls, name: str):
-        """Returns a standard example's specification
-
-        Standard examples are available here:
-        https://github.com/opvious/examples/tree/main/sources
-        """
-        return RemoteSpecification(url=f"{_EXAMPLE_URL_PREFIX}/{name}.md")
-
     async def fetch_sources(self, executor: Executor) -> list[str]:
         async with executor.execute(
             result_type=PlainTextExecutorResult,
@@ -51,7 +34,7 @@ class FormulationSpecification:
     <https://github.com/opvious/register-specification-action>`_ provides a
     convenient way to automatically create formulations from CI workflows.
 
-    .. _Optimization Hub: https://hub.beta.opvious.io
+    .. _Optimization Hub: https://hub.cloud.opvious.io
     """
 
     formulation_name: str

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "opvious"
-version = "0.17.0rc2"
+version = "0.17.0rc3"
 description = "Opvious Python SDK"
 authors = ["Opvious Engineering <[email protected]>"]
 readme = "README.md"

tests/test_client.py

@@ -2,7 +2,7 @@
 import pytest
 
 
-client = opvious.Client.from_environment()
+client = opvious.Client.default()
 
 
 @pytest.mark.skipif(
@@ -372,7 +372,9 @@ async def test_summarize(self):
     async def test_solve_sudoku_from_url(self):
         solution = await client.solve(
             opvious.Problem(
-                specification=opvious.RemoteSpecification.example("sudoku"),
+                specification=opvious.RemoteSpecification(
+                    "https://gist.githubusercontent.com/mtth/82a21baacba4827bc1710b7526775315/raw/4e2b17c1509dfd40595f47167e8d859fa4ec8334/sudoku.md"  # noqa
+                ),
                 parameters={"input": [(0, 0, 3)]},
             )
         )

tests/test_modeling.py

@@ -3,7 +3,7 @@
 
 
 om = opvious.modeling
-client = opvious.Client.from_environment()
+client = opvious.Client.default()
 
 
 class SetCover(om.Model):