cmpnd 0.82.0__tar.gz → 0.84.0__tar.gz

{cmpnd-0.82.0 → cmpnd-0.84.0}/AGENTS.md

@@ -137,7 +137,13 @@ still install against the `dspy>=…` floor in `dependencies`.
 - `scripts/install-test-env.sh <python> <dspy>` builds `.venv` from one group's
   locked tree, as each `sdk-test` leg in `ci-sdk.yml` does. From the repo root,
   run `just sdk-test-env 3.13 3.3.0`, then, from `python-sdk/`,
-  `.venv/bin/python -m pytest tests/ -k "not e2e"`. `uv sync --extra dev` in
+  `.venv/bin/python -m pytest tests/ -k "not e2e"`. The root recipe
+  `SDK_TEST_PYTHON_VERSION=3.13 SDK_TEST_DSPY_VERSION=3.4.0 just sdk-test-linux`
+  runs the same locked environment in Linux. `SDK_TEST_LINUX_IMAGE` selects a
+  pinned CI builder when reproducing a job. The helper copies the worker pins
+  and truncation vectors and mounts Git metadata read-only for revision tests.
+  The revision tests require Git, which the CI builder provides.
+  `uv sync --extra dev` in
   `python-sdk/` returns to the default group.
 - `--latest` resolves every package fresh, as a user's install today would.
   With the DSPy version `newest` it pins no DSPy either. The daily

{cmpnd-0.82.0 → cmpnd-0.84.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cmpnd
-Version: 0.82.0
+Version: 0.84.0
 Summary: DSPy observability and deployment SDK for cmpnd
 Project-URL: Homepage, https://cmpnd.ai
 Author-email: cmpnd <hello@cmpnd.ai>
@@ -66,8 +66,13 @@ uv add cmpnd      # or: pip install cmpnd
 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.Client()` or `cmpnd.configure()`. For a self-hosted cmpnd install, also
-pass the install's URL as `endpoint=`.
+`cmpnd.Client()` or `cmpnd.configure()`, or set `CMPND_API_KEY`. For a
+self-hosted cmpnd install, also pass the install's URL as `endpoint=`, or set
+`CMPND_ENDPOINT`.
+
+The library reads its key and endpoint from those arguments and variables
+alone. It never reads the key that `cmpnd login` stores for the command line,
+so a script that runs after `cmpnd login` still sets `CMPND_API_KEY`.
 
 ## Quick start
 
@@ -176,12 +181,13 @@ client for server-side execution:
 import cmpnd
 import dspy
 
-sdk = cmpnd.Client(api_key="ck_xxx")
+sdk = cmpnd.Client()  # reads CMPND_API_KEY
+openai = cmpnd.credentials.get("openai")  # a credential your organization sealed
 
 qa4 = cmpnd.Program(
     "question-answerer", module=dspy.Predict("question -> answer"), lm=dspy.LM("openai/gpt-6-luna")
 )
-deployed = sdk.deploy_program(qa4)
+deployed = sdk.deploy_program(qa4, credential=openai)
 
 result = sdk.run_deployment(deployed, question="What is DSPy?")  # runs server-side
 print(result.answer)
@@ -219,13 +225,18 @@ deployed = sdk.deploy_program(program, credential=luna)
   the organization does not hold raises `cmpnd.CredentialNotFound`, which lists
   the names it does hold and the nearest one. `cmpnd.credentials.list()`
   returns them all.
+- `cmpnd.credentials.get` reads the key and endpoint the way
+  `cmpnd.configure()` does, and also takes `api_key=` and `endpoint=`.
 - `credential=` takes a `cmpnd.Credential`, never a string. A string raises
   and shows the `cmpnd.credentials.get(...)` line to write.
-- Without `credential=`, the deployment spends the organization's default,
-  which an owner sets with `cmpnd credentials default NAME`.
-- The deployment records the credential's name. Each call spends the newest
-  credential sealed under that name, so an owner who rotates a key needs no
-  redeploy.
+- An organization may have no default credential. Then every deploy and every
+  optimization names its credential. The platform refuses one that names none,
+  and the refusal lists the names the organization holds. An owner sets a
+  default with `cmpnd credentials default NAME`, and a deploy without
+  `credential=` spends it.
+- The deployment records the credential's name. Its runs spend the newest
+  credential sealed under that name, so `run_deployment()` takes no credential,
+  and an owner who rotates a key needs no redeploy.
 - The deploy prints the protocol, model and credential of each binding, as
   above. A server that prints none chose the credential from the model's
   provider prefix, and the SDK warns.
@@ -237,6 +248,24 @@ the platform only through `cmpnd credentials create`. `cmpnd deploy FILE`
 refuses source whose import builds an LM carrying a key, and names the module,
 the model and the field.
 
+### Gateways
+
+An OpenAI-compatible gateway, such as LunaRoute, is a credential of its own.
+Seal its key with the gateway's preset, or with `--preset openai_like` and the
+gateway's address:
+
+```bash
+cmpnd credentials create --name luna-exec --preset lunaroute < key.txt
+cmpnd credentials create --name my-gateway --preset openai_like --api-base https://gateway.example.com/v1 < key.txt
+```
+
+Spell the gateway's models `openai/<model>`, such as
+`openai/deepseek-4.1-flash`, and deploy with
+`credential=cmpnd.credentials.get("luna-exec")`. The `openai/` prefix selects
+the Chat Completions wire protocol, and the gateway receives the model after
+the first `/`. The credential decides the address and the key, so one gateway
+serves every model it routes.
+
 ### The same source on your laptop and hosted
 
 A program's logic runs unchanged on your laptop and hosted. On your laptop it
@@ -259,11 +288,10 @@ def metric(gold, pred, trace=None, pred_name=None, pred_trace=None, lms=None):
     return dspy.Prediction(score=float(verdict.correct), feedback="correct" if verdict.correct else "wrong")
 ```
 
-Seal the key once for the organization and make it the default:
+Seal the key once for the organization:
 
 ```bash
 printf '%s' "$OPENAI_API_KEY" | cmpnd credentials create --name openai --preset openai
-cmpnd credentials default openai
 ```
 
 The entry point is the only code that knows where the run happens:
@@ -287,13 +315,15 @@ lms = {"critic": dspy.LM("openai/gpt-5-mini")}
 train, val = load_examples()  # your dspy.Example lists
 
 if HOSTED:
-    deployed = sdk.deploy_program(qa)  # spends the default credential, openai
+    openai = cmpnd.credentials.get("openai")
+    deployed = sdk.deploy_program(qa, credential=openai)
     print(sdk.run_deployment(deployed, question="What is DSPy?"))
     best = sdk.optimize_deployment(
         deployed,
         trainset=train,
         valset=val,
         metric=metric,  # the platform hands it lms
+        credential=openai,  # every model below spends it
         reflection_lm=cmpnd.HostedLM(reflection),
         lms={name: cmpnd.HostedLM(model) for name, model in lms.items()},
         auto="light",
@@ -305,12 +335,12 @@ else:
 ```
 
 `python main.py` runs everything on your laptop, and `python main.py --hosted`
-runs it on the platform. `cmpnd deploy qa.py qa` deploys the same file from the
-terminal.
+runs it on the platform. `cmpnd deploy qa.py qa --credential openai` deploys
+the same file from the terminal.
 
 | | On your laptop | Hosted |
 |---|---|---|
-| Key | the provider's variable in your environment, such as `OPENAI_API_KEY` | the credential the call names, else the organization's default |
+| Key | the provider's variable in your environment, such as `OPENAI_API_KEY` | the credential the call names, else the organization's default, if one is set |
 | Address | the LM's `api_base`, else the provider's endpoint | the credential's `api_base` |
 | Model | `gpt-5-mini`, the model after its first `/` | `gpt-5-mini` |
 | The metric's `lms` | the dict the entry point binds | the run's `lms=`, which the platform hands it |
@@ -348,7 +378,7 @@ sdk.deploy_program(
     metric=None,       # optional: a metric callable, packaged for optimization
     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
-    credential=None,   # optional: a cmpnd.Credential the program's model spends
+    credential=None,   # a cmpnd.Credential the program's model spends, else the org's default, if one is set
 )
 ```
 
@@ -371,12 +401,13 @@ found. Deploy the program first:
 import cmpnd
 import dspy
 
-sdk = cmpnd.Client(api_key="ck_xxx")
+sdk = cmpnd.Client()  # reads CMPND_API_KEY
+openai = cmpnd.credentials.get("openai")
 
 program = cmpnd.Program(
     "haiku", module=dspy.ChainOfThought("topic -> haiku"), lm=dspy.LM("openai/gpt-6-luna")
 )
-deployed = sdk.deploy_program(program)
+deployed = sdk.deploy_program(program, credential=openai)
 
 # 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):
@@ -391,6 +422,7 @@ best = sdk.optimize_deployment(
     trainset=train,
     valset=val,
     metric=metric,
+    credential=openai,
     reflection_lm=dspy.LM("openai/gpt-6-luna"),
     auto="light",
 )
@@ -429,9 +461,9 @@ best = sdk.optimize_deployment(
 
 `cmpnd.HostedLM(lm, credential=c)` wraps a chat LM, and
 `cmpnd.SystemOne(model, credential=c)` declares a System One model. A binding
-without a credential spends the run's, or the organization's default. The
-platform refuses a credential whose endpoint does not serve a binding's
-protocol, and names the `credential=` to add.
+without a credential spends the run's, else the organization's default, if one
+is set. The platform refuses a credential whose endpoint does not serve a
+binding's protocol, and names the `credential=` to add.
 
 The SDK checks the metric before any network call. GEPA writes each new
 instruction from the textual feedback the metric returns, so it needs a
@@ -466,6 +498,7 @@ def faithfulness(gold, pred, trace, pred_name, pred_trace, lms=None):
 
 best = sdk.optimize_deployment(
     deployed, optimizer="gepa", trainset=train, valset=val, metric=faithfulness,
+    credential=openai,
     reflection_lm=dspy.LM("openai/gpt-6-luna"),
     lms={"critic": dspy.LM("openai/gpt-6-luna")},
     max_metric_calls=300,
@@ -499,7 +532,7 @@ sdk.optimize_deployment(
     config=None,             # optional: optimizer config, allow-listed by the platform
     reflection_lm=None,      # required: a dspy.LM, a bare model name or a cmpnd.HostedLM
     lms=None,                # optional: name -> dspy.LM, cmpnd.HostedLM or cmpnd.SystemOne
-    credential=None,         # optional: the cmpnd.Credential every other binding spends
+    credential=None,         # the cmpnd.Credential every other binding spends, else the org's default, if one is set
     max_metric_calls=None,   # budget: the metric-call ceiling for the run
     auto=None,               # budget: "light", "medium" or "heavy"
     may_author_code=None,    # optional: False keeps each dspy.Flex at its deployed source
@@ -565,13 +598,33 @@ Deploy a source file under a program name, or optimize the program a file
 declares:
 
 ```bash
-cmpnd deploy program.py question-answerer
-cmpnd optimize gepa task.py haiku --reflection-model openai/gpt-6-luna --auto light
+cmpnd deploy program.py question-answerer --credential openai
+cmpnd optimize gepa task.py haiku --credential openai --reflection-model openai/gpt-6-luna --auto light
 ```
 
 `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.
+program name and prints the best deployment ID. `--credential` names the
+credential the program's models spend, and `cmpnd credentials list` shows the
+names your organization holds.
+
+`cmpnd programs rename PROGRAM NAME` gives a program a new name, or names one
+that has none. PROGRAM is a program name or a `p_` id, and the program keeps
+its id and its history. The old name is free at once, so update the code that
+declares it.
+
+A program calls tools on an MCP server once your organization seals the
+server's key, registers the server and allows its tools:
+
+```bash
+cmpnd credentials create --kind mcp --server https://mcp.exa.ai/mcp --name exa-prod \
+    --placement query_param --query-param-name exaApiKey < exa-key.txt
+cmpnd tool-servers create --url https://mcp.exa.ai/mcp --credential exa-prod
+cmpnd tool-servers allow <server_id> web_search_exa
+```
+
+[`docs/cli.md`](docs/cli.md) describes every command, including "Tool
+servers".
 
 ## Custom spans
 
@@ -632,7 +685,7 @@ cmpnd.configure(
     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
+    default_tags={"env": "prod"},          # optional: tags on every trace; a run's own tags override them
 )
 ```
 

{cmpnd-0.82.0 → cmpnd-0.84.0}/README.md

@@ -15,8 +15,13 @@ uv add cmpnd      # or: pip install cmpnd
 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.Client()` or `cmpnd.configure()`. For a self-hosted cmpnd install, also
-pass the install's URL as `endpoint=`.
+`cmpnd.Client()` or `cmpnd.configure()`, or set `CMPND_API_KEY`. For a
+self-hosted cmpnd install, also pass the install's URL as `endpoint=`, or set
+`CMPND_ENDPOINT`.
+
+The library reads its key and endpoint from those arguments and variables
+alone. It never reads the key that `cmpnd login` stores for the command line,
+so a script that runs after `cmpnd login` still sets `CMPND_API_KEY`.
 
 ## Quick start
 
@@ -125,12 +130,13 @@ client for server-side execution:
 import cmpnd
 import dspy
 
-sdk = cmpnd.Client(api_key="ck_xxx")
+sdk = cmpnd.Client()  # reads CMPND_API_KEY
+openai = cmpnd.credentials.get("openai")  # a credential your organization sealed
 
 qa4 = cmpnd.Program(
     "question-answerer", module=dspy.Predict("question -> answer"), lm=dspy.LM("openai/gpt-6-luna")
 )
-deployed = sdk.deploy_program(qa4)
+deployed = sdk.deploy_program(qa4, credential=openai)
 
 result = sdk.run_deployment(deployed, question="What is DSPy?")  # runs server-side
 print(result.answer)
@@ -168,13 +174,18 @@ deployed = sdk.deploy_program(program, credential=luna)
   the organization does not hold raises `cmpnd.CredentialNotFound`, which lists
   the names it does hold and the nearest one. `cmpnd.credentials.list()`
   returns them all.
+- `cmpnd.credentials.get` reads the key and endpoint the way
+  `cmpnd.configure()` does, and also takes `api_key=` and `endpoint=`.
 - `credential=` takes a `cmpnd.Credential`, never a string. A string raises
   and shows the `cmpnd.credentials.get(...)` line to write.
-- Without `credential=`, the deployment spends the organization's default,
-  which an owner sets with `cmpnd credentials default NAME`.
-- The deployment records the credential's name. Each call spends the newest
-  credential sealed under that name, so an owner who rotates a key needs no
-  redeploy.
+- An organization may have no default credential. Then every deploy and every
+  optimization names its credential. The platform refuses one that names none,
+  and the refusal lists the names the organization holds. An owner sets a
+  default with `cmpnd credentials default NAME`, and a deploy without
+  `credential=` spends it.
+- The deployment records the credential's name. Its runs spend the newest
+  credential sealed under that name, so `run_deployment()` takes no credential,
+  and an owner who rotates a key needs no redeploy.
 - The deploy prints the protocol, model and credential of each binding, as
   above. A server that prints none chose the credential from the model's
   provider prefix, and the SDK warns.
@@ -186,6 +197,24 @@ the platform only through `cmpnd credentials create`. `cmpnd deploy FILE`
 refuses source whose import builds an LM carrying a key, and names the module,
 the model and the field.
 
+### Gateways
+
+An OpenAI-compatible gateway, such as LunaRoute, is a credential of its own.
+Seal its key with the gateway's preset, or with `--preset openai_like` and the
+gateway's address:
+
+```bash
+cmpnd credentials create --name luna-exec --preset lunaroute < key.txt
+cmpnd credentials create --name my-gateway --preset openai_like --api-base https://gateway.example.com/v1 < key.txt
+```
+
+Spell the gateway's models `openai/<model>`, such as
+`openai/deepseek-4.1-flash`, and deploy with
+`credential=cmpnd.credentials.get("luna-exec")`. The `openai/` prefix selects
+the Chat Completions wire protocol, and the gateway receives the model after
+the first `/`. The credential decides the address and the key, so one gateway
+serves every model it routes.
+
 ### The same source on your laptop and hosted
 
 A program's logic runs unchanged on your laptop and hosted. On your laptop it
@@ -208,11 +237,10 @@ def metric(gold, pred, trace=None, pred_name=None, pred_trace=None, lms=None):
     return dspy.Prediction(score=float(verdict.correct), feedback="correct" if verdict.correct else "wrong")
 ```
 
-Seal the key once for the organization and make it the default:
+Seal the key once for the organization:
 
 ```bash
 printf '%s' "$OPENAI_API_KEY" | cmpnd credentials create --name openai --preset openai
-cmpnd credentials default openai
 ```
 
 The entry point is the only code that knows where the run happens:
@@ -236,13 +264,15 @@ lms = {"critic": dspy.LM("openai/gpt-5-mini")}
 train, val = load_examples()  # your dspy.Example lists
 
 if HOSTED:
-    deployed = sdk.deploy_program(qa)  # spends the default credential, openai
+    openai = cmpnd.credentials.get("openai")
+    deployed = sdk.deploy_program(qa, credential=openai)
     print(sdk.run_deployment(deployed, question="What is DSPy?"))
     best = sdk.optimize_deployment(
         deployed,
         trainset=train,
         valset=val,
         metric=metric,  # the platform hands it lms
+        credential=openai,  # every model below spends it
         reflection_lm=cmpnd.HostedLM(reflection),
         lms={name: cmpnd.HostedLM(model) for name, model in lms.items()},
         auto="light",
@@ -254,12 +284,12 @@ else:
 ```
 
 `python main.py` runs everything on your laptop, and `python main.py --hosted`
-runs it on the platform. `cmpnd deploy qa.py qa` deploys the same file from the
-terminal.
+runs it on the platform. `cmpnd deploy qa.py qa --credential openai` deploys
+the same file from the terminal.
 
 | | On your laptop | Hosted |
 |---|---|---|
-| Key | the provider's variable in your environment, such as `OPENAI_API_KEY` | the credential the call names, else the organization's default |
+| Key | the provider's variable in your environment, such as `OPENAI_API_KEY` | the credential the call names, else the organization's default, if one is set |
 | Address | the LM's `api_base`, else the provider's endpoint | the credential's `api_base` |
 | Model | `gpt-5-mini`, the model after its first `/` | `gpt-5-mini` |
 | The metric's `lms` | the dict the entry point binds | the run's `lms=`, which the platform hands it |
@@ -297,7 +327,7 @@ sdk.deploy_program(
     metric=None,       # optional: a metric callable, packaged for optimization
     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
-    credential=None,   # optional: a cmpnd.Credential the program's model spends
+    credential=None,   # a cmpnd.Credential the program's model spends, else the org's default, if one is set
 )
 ```
 
@@ -320,12 +350,13 @@ found. Deploy the program first:
 import cmpnd
 import dspy
 
-sdk = cmpnd.Client(api_key="ck_xxx")
+sdk = cmpnd.Client()  # reads CMPND_API_KEY
+openai = cmpnd.credentials.get("openai")
 
 program = cmpnd.Program(
     "haiku", module=dspy.ChainOfThought("topic -> haiku"), lm=dspy.LM("openai/gpt-6-luna")
 )
-deployed = sdk.deploy_program(program)
+deployed = sdk.deploy_program(program, credential=openai)
 
 # 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):
@@ -340,6 +371,7 @@ best = sdk.optimize_deployment(
     trainset=train,
     valset=val,
     metric=metric,
+    credential=openai,
     reflection_lm=dspy.LM("openai/gpt-6-luna"),
     auto="light",
 )
@@ -378,9 +410,9 @@ best = sdk.optimize_deployment(
 
 `cmpnd.HostedLM(lm, credential=c)` wraps a chat LM, and
 `cmpnd.SystemOne(model, credential=c)` declares a System One model. A binding
-without a credential spends the run's, or the organization's default. The
-platform refuses a credential whose endpoint does not serve a binding's
-protocol, and names the `credential=` to add.
+without a credential spends the run's, else the organization's default, if one
+is set. The platform refuses a credential whose endpoint does not serve a
+binding's protocol, and names the `credential=` to add.
 
 The SDK checks the metric before any network call. GEPA writes each new
 instruction from the textual feedback the metric returns, so it needs a
@@ -415,6 +447,7 @@ def faithfulness(gold, pred, trace, pred_name, pred_trace, lms=None):
 
 best = sdk.optimize_deployment(
     deployed, optimizer="gepa", trainset=train, valset=val, metric=faithfulness,
+    credential=openai,
     reflection_lm=dspy.LM("openai/gpt-6-luna"),
     lms={"critic": dspy.LM("openai/gpt-6-luna")},
     max_metric_calls=300,
@@ -448,7 +481,7 @@ sdk.optimize_deployment(
     config=None,             # optional: optimizer config, allow-listed by the platform
     reflection_lm=None,      # required: a dspy.LM, a bare model name or a cmpnd.HostedLM
     lms=None,                # optional: name -> dspy.LM, cmpnd.HostedLM or cmpnd.SystemOne
-    credential=None,         # optional: the cmpnd.Credential every other binding spends
+    credential=None,         # the cmpnd.Credential every other binding spends, else the org's default, if one is set
     max_metric_calls=None,   # budget: the metric-call ceiling for the run
     auto=None,               # budget: "light", "medium" or "heavy"
     may_author_code=None,    # optional: False keeps each dspy.Flex at its deployed source
@@ -514,13 +547,33 @@ Deploy a source file under a program name, or optimize the program a file
 declares:
 
 ```bash
-cmpnd deploy program.py question-answerer
-cmpnd optimize gepa task.py haiku --reflection-model openai/gpt-6-luna --auto light
+cmpnd deploy program.py question-answerer --credential openai
+cmpnd optimize gepa task.py haiku --credential openai --reflection-model openai/gpt-6-luna --auto light
 ```
 
 `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.
+program name and prints the best deployment ID. `--credential` names the
+credential the program's models spend, and `cmpnd credentials list` shows the
+names your organization holds.
+
+`cmpnd programs rename PROGRAM NAME` gives a program a new name, or names one
+that has none. PROGRAM is a program name or a `p_` id, and the program keeps
+its id and its history. The old name is free at once, so update the code that
+declares it.
+
+A program calls tools on an MCP server once your organization seals the
+server's key, registers the server and allows its tools:
+
+```bash
+cmpnd credentials create --kind mcp --server https://mcp.exa.ai/mcp --name exa-prod \
+    --placement query_param --query-param-name exaApiKey < exa-key.txt
+cmpnd tool-servers create --url https://mcp.exa.ai/mcp --credential exa-prod
+cmpnd tool-servers allow <server_id> web_search_exa
+```
+
+[`docs/cli.md`](docs/cli.md) describes every command, including "Tool
+servers".
 
 ## Custom spans
 
@@ -581,7 +634,7 @@ cmpnd.configure(
     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
+    default_tags={"env": "prod"},          # optional: tags on every trace; a run's own tags override them
 )
 ```