cmpnd 0.53.0__tar.gz → 0.55.0__tar.gz

{cmpnd-0.53.0 → cmpnd-0.55.0}/AGENTS.md

@@ -95,6 +95,13 @@ knowing:
   `include`, so `basedpyright cmpnd` skips `tests/e2e` and `tests/stress` and
   passes changes CI rejects.
 
+**This tree's SDK and CLI run against each live self-host release.**
+`scripts/selfhost_compat.py` deploys and runs a program through
+`cmpnd.Client` and through `cmpnd deploy --run` against the serve that
+`CMPND_ENDPOINT` names. The advisory `sdk-selfhost-compat` job in `ci-sdk.yml`
+runs it on every SDK pull request, once per self-host app. A failure there
+means a self-hosted install would break on the next SDK release.
+
 **Never run pytest processes in parallel.** Do not use `pytest-xdist`, and do
 not start a run while another is in the background. DSPy uses a lot of memory
 on import, and parallel runs crash the machine.
@@ -145,12 +152,15 @@ Before you touch either `pyproject.toml`:
 
 - `ingest/cmpnd_ingest/exporter_http.py`: the ingest transport (`cmpnd.exporter_http`)
 - `ingest/cmpnd_ingest/retry.py`: the client half of the retryable-error contract (`cmpnd.retry`)
+- `ingest/cmpnd_ingest/client_floor.py`: warns once when serve's `X-Cmpnd-Minimum-Client-Version` header names a floor above the installed release
+- `ingest/cmpnd_ingest/program_names.py`: keeps the program ids serve gave for the program names a process declared
 - `cmpnd/identity.py`: hash computations (xxhash, SHA256). See the `cmpnd-hash-handling` skill.
 - `cmpnd/ir/`: the structural program-identity IR (algebra, encoder, hash, reflector)
 - `cmpnd/callback.py`: DSPy instrumentation and signature extraction
 - `cmpnd/optimizers/tracker.py`: optimization tracking
 - `cmpnd/packaging.py`: builds the source ZIP that deploy uploads
-- `cmpnd/deployment.py`: `deploy()` packages the module, creates the deployment
+- `cmpnd/deployment.py`: `deploy_program()`, which `cmpnd.Client.deploy_program`
+  calls, packages the module, creates the deployment
   on serve, PUTs the bundle to the upload slot serve returns, and polls the
   parser
 
@@ -195,8 +205,8 @@ its `add_parser` call in `top.register()`, and add the entity method or the
 When you touch a handler:
 
 - **Write user-facing hints with the `_hint_*` helpers** in
-  `cli/commands/top.py` (`_hint_ps`, `_hint_run`, `_hint_status`,
-  `_hint_inspect`, `_hint_traces_list`). They check `_SHELL_MODE` and emit
+  `cli/commands/top.py` (`_hint_ps`, `_hint_run`, `_hint_program_name`,
+  `_hint_status`, `_hint_inspect`, `_hint_traces_list`). They check `_SHELL_MODE` and emit
   `deps.d_xxx.run({...})` in the shell or `cmpnd run d_xxx '{...}'` outside
   it. Never hardcode a `cmpnd <verb>` string in handler output.
 - **Add a shell entity** by subclassing `Entity` in `cli/shell.py`. Add a

{cmpnd-0.53.0 → cmpnd-0.55.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cmpnd
-Version: 0.53.0
+Version: 0.55.0
 Summary: DSPy observability and deployment SDK for cmpnd
 Project-URL: Homepage, https://cmpnd.ai
 Author-email: cmpnd <hello@cmpnd.ai>
@@ -52,7 +52,8 @@ Description-Content-Type: text/markdown
 # cmpnd
 
 The `cmpnd` package traces DSPy programs and deploys and optimizes them on the
-cmpnd platform. One call turns on tracing, and one more deploys a program.
+cmpnd platform. One call turns on tracing, and a client deploys, runs and
+optimizes named programs.
 
 ## Installation
 
@@ -135,7 +136,7 @@ gepa = dspy.GEPA(metric=metric, reflection_lm=dspy.LM("openai/gpt-6-luna"), auto
 with cmpnd.Client(api_key="ck_xxx", project_tags="my-project") as sdk:
     # the trace will go to the program "question-answerer"
     result = sdk.run_program(qa1, question="What is DSPy?")
-    qa2 = sdk.run_optimization(gepa, qa1, trainset=train, valset=val)
+    qa2 = sdk.optimize_program(qa1, gepa, trainset=train, valset=val)
 ```
 
 A client is active from construction. The `with` form flushes the client's
@@ -163,38 +164,41 @@ qa3 = cmpnd.Program(
 - A program name starts with an ASCII letter or digit, then has letters,
   digits, `.`, `_` or `-`, at most 64 characters. It does not start with `p_`.
   A bad name raises `ValueError`. Declaring a program makes no network call.
-- `run_optimization` returns a copy of the program that holds the optimized
-  module. The copy keeps the program name and the LM.
+- `optimize_program` runs the optimizer in your process and returns a copy of
+  the program that holds the optimized module. The copy keeps the program name
+  and the LM.
 - Calling a `cmpnd.Program` directly while `auto_instrument()` is on raises a
   `TypeError` that points to `cmpnd.Client`.
 
 ## Deployed programs
 
 Every deployment belongs to a program, and each program has a program name.
-Give a DSPy module a program name with `cmpnd.Program`, then deploy it for
-server-side execution:
+Give a DSPy module a program name with `cmpnd.Program`, then deploy it through a
+client for server-side execution:
 
 ```python
 import cmpnd
 import dspy
 
-cmpnd.configure(api_key="ck_xxx")
+sdk = cmpnd.Client(api_key="ck_xxx")
 
 qa4 = cmpnd.Program(
     "question-answerer", module=dspy.Predict("question -> answer"), lm=dspy.LM("openai/gpt-6-luna")
 )
-deployed = cmpnd.deploy(qa4)
+deployed = sdk.deploy_program(qa4)
 
-result = deployed(question="What is DSPy?")  # runs server-side
+result = sdk.run_deployment(deployed, question="What is DSPy?")  # runs server-side
 print(result.answer)
 ```
 
-`deploy()` packages the module's source, sends it to the platform and waits
-until the platform has read it. It then returns a `DeployedProgram`. Call the program to execute it
-server-side. `str(deployed)` and `deployed.deployment_id` return the
-deployment ID. `deployed.artifact_metadata` holds the typed artifact record
-when the platform has inspected it. An unknown interface leaves `input_fields`
-and `output_fields` as `None`. A known interface with no fields returns empty
+`deploy_program()` packages the module's source, sends it to the platform and
+waits until the platform has read it. It then returns a `DeployedProgram`.
+`run_deployment()` runs it server-side on the client's account, and also takes
+a deployment ID. A `DeployedProgram` is not callable, because a run needs a
+client. `str(deployed)` and `deployed.deployment_id` return the deployment ID.
+`deployed.artifact_metadata` holds the typed artifact record when the platform
+has inspected it. An unknown interface leaves `input_fields` and
+`output_fields` as `None`. A known interface with no fields returns empty
 lists.
 
 The platform makes the program the first time your organization uses the
@@ -204,7 +208,7 @@ program, and so do the traces of a client that runs it.
 ### Options
 
 ```python
-cmpnd.deploy(
+sdk.deploy_program(
     program,           # required: a cmpnd.Program
     metric=None,       # optional: a metric callable, packaged for optimization
     timeout=300,       # optional: seconds to wait for the deployment to be ready
@@ -218,23 +222,25 @@ cmpnd.deploy(
    signature and types.
 2. The platform reads the program, the model string and the sampling settings
    from that source.
-3. `deploy()` returns the `DeployedProgram` when the deployment is ready.
+3. `deploy_program()` returns the `DeployedProgram` when the deployment is
+   ready.
 
 ## Optimization on the platform
 
-`cmpnd.optimize()` optimizes a program through the platform. Like `deploy()`,
-it returns a `DeployedProgram` that you call directly, and the program's
-`score` is the best score found.
+`optimize_deployment()` optimizes a deployment through the platform. It returns
+the best deployment as a `DeployedProgram`, whose `score` is the best score
+found. Deploy the program first:
 
 ```python
 import cmpnd
 import dspy
 
-cmpnd.configure(api_key="ck_xxx")
+sdk = cmpnd.Client(api_key="ck_xxx")
 
 program = cmpnd.Program(
     "haiku", module=dspy.ChainOfThought("topic -> haiku"), lm=dspy.LM("openai/gpt-6-luna")
 )
+deployed = sdk.deploy_program(program)
 
 # GEPA needs a five-argument feedback metric that returns dspy.Prediction(score=, feedback=)
 def metric(example, pred, trace=None, pred_name=None, pred_trace=None):
@@ -243,8 +249,8 @@ def metric(example, pred, trace=None, pred_name=None, pred_trace=None):
         score=float(ok), feedback=None if ok else "Don't name the season."
     )
 
-best = cmpnd.optimize(
-    program,
+best = sdk.optimize_deployment(
+    deployed,
     optimizer="gepa",
     trainset=train,
     valset=val,
@@ -254,9 +260,13 @@ best = cmpnd.optimize(
 )
 
 print(best.score)
-print(best(topic="late autumn").haiku)
+print(sdk.run_deployment(best, topic="late autumn").haiku)
 ```
 
+`optimize_deployment()` also takes the ID of a ready deployment. The
+optimization belongs to the deployment's program, and the program's model comes
+from the deployment.
+
 `reflection_lm` is the model that proposes each new instruction. The search is
 only as good as this model, so it is usually a strong model and not the one
 being optimized. A `dspy.LM` passes its sampling settings to the provider. A
@@ -273,9 +283,10 @@ positional arguments, because such a run would report success and learn
 nothing. A `*args` metric cannot be checked, and the SDK accepts it with a
 warning.
 
-`gepa` is the only optimizer the platform runs. `optimize()` raises
-`ValueError` for the retired `bootstrap_fewshot` and `random_search` before
-any network call, and the platform answers them with a 404 that names gepa.
+`gepa` is the default and the only optimizer the platform runs.
+`optimize_deployment()` raises `ValueError` for the retired `bootstrap_fewshot`
+and `random_search` before any network call, and the platform answers them with
+a 404 that names gepa.
 
 ### A metric with its own model
 
@@ -296,8 +307,8 @@ def faithfulness(gold, pred, trace, pred_name, pred_trace, lms=None):
     return dspy.Prediction(score=verdict.score, feedback=verdict.feedback)
 
 
-best = cmpnd.optimize(
-    program, optimizer="gepa", trainset=train, valset=val, metric=faithfulness,
+best = sdk.optimize_deployment(
+    deployed, optimizer="gepa", trainset=train, valset=val, metric=faithfulness,
     reflection_lm=dspy.LM("openai/gpt-6-luna"),
     lms={"critic": dspy.LM("openai/gpt-6-luna")},
     max_metric_calls=300,
@@ -319,28 +330,16 @@ The `lms` parameter does not change the arity check. Five or more positional
 arguments make a feedback metric, and a metric without `lms` never receives
 it.
 
-### Reusing a deployment
-
-Pass the `deployment_id` of a ready deployment to skip the initial deploy:
-
-```python
-best = cmpnd.optimize(program, optimizer="gepa",
-                      trainset=train, valset=val, metric=metric,
-                      reflection_lm="openai/gpt-6-luna", auto="light",
-                      deployment_id=deployed.deployment_id)
-```
-
 ### Options
 
 ```python
-cmpnd.optimize(
-    program,                 # required: the DSPy module to optimize
-    optimizer="gepa",        # required: the only optimizer the platform runs
+sdk.optimize_deployment(
+    deployed,                # required: a DeployedProgram or a deployment ID
+    optimizer="gepa",        # optional: the only optimizer the platform runs
     trainset=train,          # required: training examples
     valset=val,              # required: validation examples
     metric=metric,           # required: the metric, arity-checked
     config=None,             # optional: optimizer config, allow-listed by the platform
-    deployment_id=None,      # optional: a ready deployment to start from
     reflection_lm=None,      # required: a dspy.LM or a bare model name
     lms=None,                # optional: name -> dspy.LM, the run's named models
     max_metric_calls=None,   # budget: the metric-call ceiling for one step
@@ -358,7 +357,7 @@ Pass exactly one budget: `max_metric_calls`, `auto` or
 `config["max_full_evals"]`. The SDK raises before any network call when the
 budget is missing.
 
-`optimize()` raises `cmpnd.OptimizeError` when the platform answers a step's
+`optimize_deployment()` raises `cmpnd.OptimizeError` when the platform answers a step's
 initiation with a 4xx, such as a 409 for missing data or a metric mismatch. It
 raises `cmpnd.OptimizeFailed` when a step reaches `failed`.
 
@@ -373,7 +372,7 @@ usage: cmpnd [-h] [--version] [--api-key API_KEY] [--endpoint ENDPOINT]
              {auth,login,logout,org,credentials,tool-servers,optimizations,programs,signatures,traces,evals,datasets,deployments,ps,status,logs,inspect,schema,sample,run,deploy,optimize}
              ...
 
-CMPND platform CLI — deploy, invoke, and inspect DSPy programs.
+CMPND platform CLI — deploy, run, and inspect DSPy programs.
 
 options:
   -h, --help           show this help message and exit
@@ -442,8 +441,7 @@ def run_pipeline(query: str):
 
 ### `cmpnd.configure()`
 
-Sets the global API key, endpoint and options that `auto_instrument()`,
-`deploy()`, `optimize()` and `execute()` use:
+Sets the global API key, endpoint and options that `auto_instrument()` uses:
 
 ```python
 cmpnd.configure(
@@ -474,10 +472,17 @@ global config. Use it as a context manager or as a plain object.
 
 - `run_program(program, **inputs)` runs a `cmpnd.Program` and records its trace
   under the program name.
-- `run_optimization(optimizer, program, trainset=..., valset=...)` compiles a
-  `cmpnd.Program` with a DSPy optimizer, records every rollout, and returns a
-  copy of the program that holds the optimized module. For `dspy.GEPA`, it
-  also records the optimization run.
+- `optimize_program(program, optimizer, trainset=..., valset=...)` compiles a
+  `cmpnd.Program` with a DSPy optimizer in your process, records every
+  rollout, and returns a copy of the program that holds the optimized module.
+  For `dspy.GEPA`, it also records the optimization run.
+- `deploy_program(program)` deploys a `cmpnd.Program` under its program name
+  and returns a `DeployedProgram`.
+- `run_deployment(deployment, **inputs)` runs a deployment and returns a
+  `dspy.Prediction`. The section below describes it.
+- `optimize_deployment(deployment, ...)` optimizes a deployment on the platform
+  and returns the best `DeployedProgram`, whose `.score` is the best score
+  found. It raises `cmpnd.OptimizeError` or `cmpnd.OptimizeFailed` on failure.
 - `list_traces(**filters)` and `get_trace(trace_id)` read traces with the
   client's credentials. They flush the client's traces first.
 - `close()` flushes the client's traces and closes the client. A closed
@@ -508,50 +513,41 @@ cmpnd.configure(api_key="ck_xxx")
 dspy.configure(callbacks=[cmpnd.CmpndCallback()])
 ```
 
-### `cmpnd.deploy()`
-
-Deploys a `cmpnd.Program` under its program name and returns a callable
-`DeployedProgram`.
-
-### `cmpnd.optimize()`
-
-Optimizes a program through the platform. It returns the best
-`DeployedProgram`, whose `.score` is the best score found. It raises
-`cmpnd.OptimizeError` or `cmpnd.OptimizeFailed` on failure.
-
-### `cmpnd.execute()`
+### `cmpnd.Client.run_deployment()`
 
-Submits one durable run by `deployment_id`, waits for the result within the
-local timeout and returns a `dspy.Prediction`. A `DeployedProgram` call goes
-through this function. A fast result returns at once, and the SDK never
-submits one run twice.
+Submits one durable run of a `DeployedProgram` or a deployment ID, waits for
+the result within the local timeout and returns a `dspy.Prediction`. A fast
+result returns at once, and the SDK never submits one run twice. A deployment
+of another account answers 404.
 
 `timeout` is the whole submit-and-wait budget in seconds, 30 by default, or
-`None` for no local limit. `program_name` and `lm` select a module and model
-and travel beside the inputs. `metadata` and `tags` take `dict[str, str]`
-values that the platform applies to the run's root trace. Names the platform sets, such as
-`deployment_run_id` raise `TypeError` before anything is sent. The errors:
+`None` for no local limit. `entrypoint` and `lm` select a module and model and
+travel beside the inputs. `metadata` and `tags` take `dict[str, str]` values
+that the platform applies to the run's root trace. Names the platform sets,
+such as `deployment_run_id`, raise `TypeError` before anything is sent. The
+errors:
 
 - A refused request raises `httpx.HTTPStatusError`.
 - A lost or failed submission reply raises `RunSubmissionUncertain`.
 - A spent budget raises `RunWaitTimeout`, which holds the run ID.
 - An answer that expired before it was read raises `RunResultExpired`.
 
-`cmpnd.deployment_run_id(result)` returns the run ID of a result, or of an
+`sdk.deployment_run_id(result)` returns the run ID of a result, or of an
 exception when the platform had assigned a run.
 
-`cmpnd.submit_deployment_run(id, inputs)` returns the accepted handle without
-waiting. `cmpnd.list_deployment_runs()`, `get_deployment_run(id)`,
+`sdk.submit_deployment_run(deployment, inputs)` returns the accepted handle
+without waiting. `sdk.list_deployment_runs()`, `get_deployment_run(id)`,
 `get_deployment_run_result(id)` and `wait_deployment_run(id)` find, inspect and
-resume runs. `list_deployment_runs(deployment_id=...)` limits the list to one
-deployment. `RunSubmissionUncertain` names the list command to check before
-you send new work.
+resume runs. `list_deployment_runs(deployment)` limits the list to one
+deployment. `RunSubmissionUncertain` names the list command to check before you
+send new work.
 
 ### `cmpnd.DeployedProgram`
 
-The callable program that `deploy()` and `optimize()` return. Call it with the
-deployed artifact's input fields. `str()` and `.deployment_id` return its ID.
-`.score` is its score when it came from `optimize()`, and `None` otherwise.
+The deployment that `deploy_program()` and `optimize_deployment()` return. Run
+it with `run_deployment()`. `str()` and `.deployment_id` return its ID.
+`.score` is its score when it came from `optimize_deployment()`, and `None`
+otherwise.
 `.deployment_signature` holds the typed deployment response, and
 `.artifact_metadata` holds its metadata when available.