cmpnd 0.51.0__tar.gz → 0.53.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cmpnd
-Version: 0.51.0
+Version: 0.53.0
 Summary: DSPy observability and deployment SDK for cmpnd
 Project-URL: Homepage, https://cmpnd.ai
 Author-email: cmpnd <hello@cmpnd.ai>
@@ -60,8 +60,20 @@ cmpnd platform. One call turns on tracing, and one more deploys a program.
 uv add cmpnd      # or: pip install cmpnd
 ```
 
+## Authentication
+
+The `cmpnd` library works with the cmpnd service at
+[platform.cmpnd.ai](https://platform.cmpnd.ai). Create an API key on the
+platform under Settings → API keys, and pass it as `api_key=` to
+`cmpnd.configure()` or `cmpnd.Client()`. For a self-hosted cmpnd install, also
+pass the install's URL as `endpoint=`.
+
 ## Quick start
 
+`cmpnd.auto_instrument()` records a trace of every DSPy call in the process.
+Your code needs no other change. Use it to sketch a [DSPy program](https://dspy.ai/) and see what it
+does.
+
 ```python
 import cmpnd
 import dspy
@@ -78,109 +90,137 @@ cmpnd.trace_id(result)  # "a1b2c3d4-...", or None outside instrumentation
 ```
 
 `cmpnd.trace_id()` links a result to its platform trace, for example to attach
-feedback later.
+feedback later. Traces recorded this way have no program name. The platform
+groups them by the structure of the program's modules. The API reference
+below lists the other options of `cmpnd.configure()`.
 
-## Configuration
+## Program names
 
-`cmpnd.configure()` reads `CMPND_API_KEY` and `CMPND_ENDPOINT` when you pass
-no arguments. The endpoint defaults to `https://platform.cmpnd.ai`.
+When you’re ready to name programs, evolve them, and share them with your team, switch
+to `cmpnd.Client`. A client replaces `configure()` and `auto_instrument()` and offers
+more features. A client records only the programs you run through it, and each of
+those programs has a program name. A client takes most of the same arguments as `configure()`.
 
-```bash
-export CMPND_API_KEY="ck_your_api_key"
-export CMPND_ENDPOINT="https://platform.cmpnd.ai"  # optional
-export CMPND_PROGRAM_ID="p_0123456789Ab"            # optional: the program these traces belong to
+A program name is the name your organization gives a program, such as `question-answerer`.
+Traces, deployments and optimization runs under one program name go to one
+program. The platform makes the program the first time your organization uses
+the program name.
+
+`@cmpnd.program(name)` above a `dspy.Module` class gives the class a program
+name. Building the class takes its own arguments and a required `lm=`. The
+`lm=` argument is the `dspy.LM` that the program runs on:
+
+```python
+import cmpnd
+import dspy
+
+class Answer(dspy.Signature):
+    """Answer the question in one short sentence."""
+    question: str = dspy.InputField()
+    answer: str = dspy.OutputField()
+
+@cmpnd.program("question-answerer")
+class QA(dspy.Predict):
+    def __init__(self):
+        super().__init__(Answer)
+
+qa1 = QA(lm=dspy.LM("openai/gpt-6-luna"))
 ```
 
+A client runs the program and records its trace under the program name:
+
 ```python
-cmpnd.configure(
-    api_key="ck_xxx",                      # required, or CMPND_API_KEY
-    endpoint="https://platform.cmpnd.ai",  # optional, or CMPND_ENDPOINT
-    project_tags="my-project",             # optional: one tag or a list of tags
-    program_id="p_0123456789Ab",           # optional, or CMPND_PROGRAM_ID: the id `cmpnd programs create` prints
-    batch_size=100,                        # optional: spans per export batch
-    flush_interval_seconds=5.0,            # optional: seconds between flushes
-    capture_inputs=True,                   # optional: record span inputs
-    capture_outputs=True,                  # optional: record span outputs
-    default_tags={"env": "prod"},          # optional: tags on every trace
-)
+gepa = dspy.GEPA(metric=metric, reflection_lm=dspy.LM("openai/gpt-6-luna"), auto="light")
+
+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)
 ```
 
-`project` is a deprecated alias for `project_tags`. Passing both raises
-`ValueError`. `CMPND_MAX_INPUT_SIZE` and `CMPND_MAX_OUTPUT_SIZE` set the
-captured input and output size limits, 65,536 bytes each by default.
+A client is active from construction. The `with` form flushes the client's
+traces and closes it on exit. Without `with`, the client stays active until
+you call `close()` or the process exits, and its traces go out at exit:
+
+```python
+sdk = cmpnd.Client(api_key="ck_xxx", project_tags="my-project")
+sdk.run_program(qa2, question="What is DSPy?")
 
-## Deployment
+# optional: flushes the traces now, so a later read sees them
+sdk.close()
+```
 
-Every deployment belongs to a program, and the platform issues each program
-an id. Create a program first. The command prints its id:
+The `cmpnd.Program` constructor gives a program name to a module you already
+have, such as a `dspy.Predict`. It makes the same kind of
+program as the decorator:
 
-```bash
-cmpnd programs create --name qa
+```python
+qa3 = cmpnd.Program(
+    "question-answerer", module=dspy.Predict("question -> answer"), lm=dspy.LM("openai/gpt-6-luna")
+)
 ```
 
-Then deploy a DSPy module under that program for server-side execution:
+- 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.
+- 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:
 
 ```python
 import cmpnd
 import dspy
 
-cmpnd.configure(api_key="ck_xxx", program_id="p_0123456789Ab")
-dspy.configure(lm=dspy.LM("openai/gpt-6-luna"))
+cmpnd.configure(api_key="ck_xxx")
 
-module = dspy.Predict("question -> answer")
-deployed = cmpnd.deploy(module)
+qa4 = cmpnd.Program(
+    "question-answerer", module=dspy.Predict("question -> answer"), lm=dspy.LM("openai/gpt-6-luna")
+)
+deployed = cmpnd.deploy(qa4)
 
 result = deployed(question="What is DSPy?")  # runs server-side
 print(result.answer)
 ```
 
-`deploy()` packages the module's source into a ZIP, uploads it and polls until
-the server-side parser finishes. It then reads the deployment's persisted
-interface and returns a `DeployedProgram`. Call the program to execute it
+`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
 lists.
 
-`cmpnd.deploy(module, program_id="p_…")` names the program for one call.
-Without a configured or passed id, `deploy` raises `ValueError` before it
-packages or sends anything.
-
-To deploy a source file, run `cmpnd deploy program.py --program-id p_…`, or
-set `CMPND_PROGRAM_ID`. The CLI uploads the file's exact bytes and does not
-reconstruct the source from a live object. Use `--source-root` and repeated
-`--include` flags for sibling modules or data, and `cmpnd inspect <id>
---source` to read the deployed entry file back. [`docs/cli.md`](docs/cli.md)
-covers the CLI.
+The platform makes the program the first time your organization uses the
+program name. Later deploys under the same program name go to the same
+program, and so do the traces of a client that runs it.
 
 ### Options
 
 ```python
 cmpnd.deploy(
-    module,            # required: a DSPy module
+    program,           # required: a cmpnd.Program
     metric=None,       # optional: a metric callable, packaged for optimization
-    timeout=300,       # optional: seconds to wait for the parser after the upload
+    timeout=300,       # optional: seconds to wait for the deployment to be ready
     metadata=None,     # optional: a JSON-serializable dict, at most 64 KiB, stored with the deployment
-    program_id="p_…",  # the program the deployment belongs to; serve requires it after self-host 2026-001
 )
 ```
 
 ### How it works
 
-1. The SDK generates source from the live module, including its LM
-   configuration, signature and types.
-2. `POST /api/v1/deployments` creates the deployment and returns an upload
-   URL.
-3. The SDK uploads the source ZIP to that URL. The bytes go to the worker.
-4. The worker's parser extracts the program and its LM configuration.
-5. The SDK polls until the status is `ready`, reads the artifact metadata and
-   returns the `DeployedProgram`.
-
-The parser reads the model string, such as `openai/gpt-6-luna`, and its
-sampling settings from the source.
+1. The SDK packages the module's source, including its LM configuration,
+   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.
 
-## Optimization
+## 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
@@ -190,16 +230,18 @@ it returns a `DeployedProgram` that you call directly, and the program's
 import cmpnd
 import dspy
 
-cmpnd.configure(api_key="ck_xxx", program_id="p_0123456789Ab")  # from `cmpnd programs create`
-dspy.configure(lm=dspy.LM("openai/gpt-6-luna"))
+cmpnd.configure(api_key="ck_xxx")
 
-program = dspy.ChainOfThought("topic -> haiku")
+program = cmpnd.Program(
+    "haiku", module=dspy.ChainOfThought("topic -> haiku"), lm=dspy.LM("openai/gpt-6-luna")
+)
 
 # 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):
     ok = example.season.lower() not in pred.haiku.lower()
-    return dspy.Prediction(score=float(ok),
-                           feedback=None if ok else "Don't name the season.")
+    return dspy.Prediction(
+        score=float(ok), feedback=None if ok else "Don't name the season."
+    )
 
 best = cmpnd.optimize(
     program,
@@ -233,7 +275,7 @@ 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 serve answers them with a 404 that names gepa.
+any network call, and the platform answers them with a 404 that names gepa.
 
 ### A metric with its own model
 
@@ -269,7 +311,7 @@ rules:
   names.
 - `"default-lm"` is reserved for the program's own model, which comes from the
   deployment. Declaring it raises an error that names it.
-- Serve refuses a model your org holds no credential for when it dispatches
+- The platform refuses a model your org holds no credential for when it dispatches
   the run, before the run starts. These LMs, like `reflection_lm`, must not set
   `api_key`, `api_base` or `base_url`.
 
@@ -277,9 +319,6 @@ 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.
 
-A run can also bring its own instruction proposer through `proposer`.
-[`docs/custom-proposer.md`](docs/custom-proposer.md) describes it.
-
 ### Reusing a deployment
 
 Pass the `deployment_id` of a ready deployment to skip the initial deploy:
@@ -300,8 +339,7 @@ cmpnd.optimize(
     trainset=train,          # required: training examples
     valset=val,              # required: validation examples
     metric=metric,           # required: the metric, arity-checked
-    proposer=None,           # optional: the run's own instruction proposer
-    config=None,             # optional: optimizer config, allow-listed by serve
+    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
@@ -311,7 +349,7 @@ cmpnd.optimize(
     max_steps=10,            # optional: the most optimize steps
     patience=2,              # optional: stop after this many steps without improvement
     seed=0,                  # optional: the starting seed, advanced each step
-    poll_interval=3.0,       # optional: seconds between status polls
+    poll_interval=3.0,       # optional: seconds between status checks
     timeout=600.0,           # optional: seconds to wait for each step
 )
 ```
@@ -320,20 +358,41 @@ 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 serve answers a step's
+`optimize()` 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`.
 
-### From the CLI
+## Command line
+
+The package installs the `cmpnd` command. `cmpnd login` saves your API key for
+the command line. `cmpnd -h` lists the commands, and `cmpnd COMMAND -h`
+describes one:
+
+```
+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.
+
+options:
+  -h, --help           show this help message and exit
+  --version            show program's version number and exit
+  --api-key API_KEY    API key (or set CMPND_API_KEY)
+  --endpoint ENDPOINT  API endpoint (or set CMPND_ENDPOINT)
+```
+
+Deploy a source file under a program name, or optimize the program a file
+declares:
 
 ```bash
-cmpnd optimize gepa task.py --program-id p_0123456789Ab --reflection-model openai/gpt-6-luna --auto light
+cmpnd deploy program.py question-answerer
+cmpnd optimize gepa task.py haiku --reflection-model openai/gpt-6-luna --auto light
 ```
 
-The file, or `-` for stdin, binds `program`, `trainset`, `valset` and
-`metric`. The CLI prints the best deployment ID. The CLI deploys the file's
-program first, so it needs `--program-id` or `CMPND_PROGRAM_ID`. With
-`--deployment-id`, the program id is optional.
+`cmpnd deploy` uploads the file as written. `cmpnd optimize` reads `program`,
+`trainset`, `valset` and `metric` from the file, deploys the program under the
+program name and prints the best deployment ID.
 
 ## Custom spans
 
@@ -383,11 +442,59 @@ def run_pipeline(query: str):
 
 ### `cmpnd.configure()`
 
-Sets the API key, endpoint and options.
+Sets the global API key, endpoint and options that `auto_instrument()`,
+`deploy()`, `optimize()` and `execute()` use:
+
+```python
+cmpnd.configure(
+    api_key="ck_xxx",                      # required, or CMPND_API_KEY
+    endpoint="https://platform.cmpnd.ai",  # optional, or CMPND_ENDPOINT
+    project_tags="my-project",             # optional: one tag or a list of tags
+    batch_size=100,                        # optional: spans per export batch
+    flush_interval_seconds=5.0,            # optional: seconds between flushes
+    capture_inputs=True,                   # optional: record span inputs
+    capture_outputs=True,                  # optional: record span outputs
+    default_tags={"env": "prod"},          # optional: tags on every trace
+)
+```
+
+`api_key` and `endpoint` fall back to the `CMPND_API_KEY` and
+`CMPND_ENDPOINT` environment variables. `project` is a deprecated alias for
+`project_tags`. Passing both raises `ValueError`. `CMPND_MAX_INPUT_SIZE` and `CMPND_MAX_OUTPUT_SIZE` set the
+captured input and output size limits, 65,536 bytes each by default.
 
 ### `cmpnd.auto_instrument()`
 
-Registers the callback with DSPy.
+Registers the callback with DSPy, so every DSPy call records a trace.
+
+### `cmpnd.Client()`
+
+Takes most of the same arguments as `cmpnd.configure()` and keeps them apart from the
+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.
+- `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
+  client raises `RuntimeError` on every method.
+
+### `cmpnd.program()`
+
+`@cmpnd.program(name)` above a `dspy.Module` class returns a `cmpnd.Program`
+class with the same class name. Building it takes the class's own arguments
+and a required `lm=` keyword. The decorator refuses a class whose
+constructor already takes `lm`. Give an instance of it to `cmpnd.Program` instead.
+
+### `cmpnd.Program()`
+
+`cmpnd.Program(name, *, module, lm)` gives a DSPy module a program name and
+the `dspy.LM` it runs on. `@cmpnd.program(name)` builds the same thing from a
+`dspy.Module` class.
 
 ### `cmpnd.CmpndCallback`
 
@@ -403,8 +510,8 @@ dspy.configure(callbacks=[cmpnd.CmpndCallback()])
 
 ### `cmpnd.deploy()`
 
-Deploys a DSPy module under a program id and returns a callable
-`DeployedProgram`. It uses `program_id=`, else the configured id.
+Deploys a `cmpnd.Program` under its program name and returns a callable
+`DeployedProgram`.
 
 ### `cmpnd.optimize()`
 
@@ -416,14 +523,13 @@ Optimizes a program through the platform. It returns the best
 
 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. The SDK sends `Prefer: wait=5`, shortened to fit the
-remaining budget, so a fast result arrives without polling. It never repeats
-the submission POST.
+through this function. A fast result returns at once, and the SDK never
+submits one run twice.
 
 `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 serve applies to the run's root trace. Serve-owned names such as
+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`.
@@ -432,7 +538,7 @@ values that serve applies to the run's root trace. Serve-owned names such as
 - 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
-exception when serve had assigned a run.
+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)`,