cmpnd 0.82.0__tar.gz → 0.83.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cmpnd
-Version: 0.82.0
+Version: 0.83.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
 

{cmpnd-0.82.0 → cmpnd-0.83.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
 

{cmpnd-0.82.0 → cmpnd-0.83.0}/cmpnd/cli/__init__.py

@@ -60,13 +60,18 @@ class _LazyVersionAction(argparse.Action):
 _EPILOG = """\
 deploy-flow workflow (Docker-style; the path an agent should reach for first):
 
-  cmpnd deploy program.py qa --run '{"question": "..."}'   # deploy program name qa + smoke test
+  cmpnd credentials list                                # the credential names a deploy may spend
+  cmpnd deploy program.py qa --credential NAME --run '{"question": "..."}'
+                                                        # deploy program name qa + smoke test
   cmpnd ps                                              # list deployments
   cmpnd status <id> -f                                  # wait for terminal state
   cmpnd run <id> '{"...": "..."}'                       # invoke a ready deployment
   cmpnd logs <id>                                       # narrative timeline + traces
   cmpnd inspect <id>                                    # full JSON record
 
+A deploy without --credential spends the organization's default credential, if
+one is set.
+
 answering a question (question-shaped flows, resolved in one or two calls):
 
   "get the last 3 traces and tell me where it's slow"

{cmpnd-0.82.0 → cmpnd-0.83.0}/cmpnd/cli/commands/top.py

@@ -1478,8 +1478,8 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
         "--credential",
         metavar="NAME",
         default=None,
-        help="The provider credential the program's model spends (default: the organization's default "
-        "credential). `cmpnd credentials list` shows the names",
+        help="The provider credential the program's model spends, else the organization's default "
+        "credential, if one is set. `cmpnd credentials list` shows the names",
     )
     dp.add_argument("--json", action="store_true", help="Emit --run output as JSON")
     dp.set_defaults(func=_handler("deploy"))
@@ -1559,7 +1559,7 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
         metavar="NAME",
         default=None,
         help="The provider credential the run spends: the program's model, and every model that names no "
-        "credential of its own (default: the organization's default credential). "
+        "credential of its own. Else the organization's default credential, if one is set. "
         "`cmpnd credentials list` shows the names",
     )
     opt.add_argument(

{cmpnd-0.82.0 → cmpnd-0.83.0}/docs/cli.md

@@ -22,11 +22,12 @@ first time the organization uses the program name. The deployment carries that
 id. A Python process that declares the same program name with
 `cmpnd.Program(name, ...)` traces to the same program.
 
-A deploy or an optimize with no program name warns that it should have one. An
-optimize with `--deployment-id` needs no program name, because that deployment
-already has its program, and a program name with it is refused when the file
-binds no program. In the shell, `deploy()` and `optimize()` take the
-program name as `program=`.
+A deploy or an optimize with no program name warns in the CLI. Serve then
+refuses the deploy with a `400`, and the CLI reports an error that shows the
+`cmpnd deploy SOURCE PROGRAM_NAME` form. An optimize with `--deployment-id`
+needs no program name, because that deployment already has its program, and a
+program name with it is refused when the file binds no program. In the shell,
+`deploy()` and `optimize()` take the program name as `program=`.
 
 The platform deploys and optimizes only a program a user named. A program name
 given here, to `cmpnd.Program(name, ...)` or to `cmpnd programs rename` is one.
@@ -312,7 +313,8 @@ model and the field, never the value. Seal the key with
 `cmpnd credentials create` instead.
 
 `--credential NAME` names the provider credential the program's model spends.
-Without it, the deployment spends the organization's default. The CLI looks
+Without it, the deployment spends the organization's default, if one is set,
+and serve refuses the deploy when the organization has none. The CLI looks
 the name up before it stages the source. A name the organization does not hold
 fails with the names it does hold and the nearest one, and nothing is sent.
 The platform checks the name again at the deploy, which catches a credential
@@ -684,16 +686,23 @@ server, the credential it uses and the allow-list of tools a deploy may name.
 cmpnd tool-servers create --url https://mcp.exa.ai/mcp --credential exa-prod [--name exa]
 cmpnd tool-servers list [--text]
 cmpnd tool-servers show <server_id> [--text [--schemas]]
+cmpnd tool-servers allow <server_id> [TOOL ...] [--all]
+cmpnd tool-servers deny <server_id> [TOOL ...] [--all]
 cmpnd tool-servers refresh <server_id>
 cmpnd tool-servers delete <server_id> --force
 ```
 
 `create` registers the server and has the platform list its tools. The
-platform contacts the server, and the CLI never does. `refresh` lists the
-tools again after a vendor changes them. `list` and `show` print the API's
-JSON. With `--text`, `show` prints each tool with its allow-list state and a
-one-line description, and `--schemas` adds the reduced argument schema the
-platform enforces. `create`, `allow`, `deny` and `refresh` render the server
+platform contacts the server, and the CLI never does. Registering grants
+nothing. `allow` names the tools a deploy may call, such as
+`cmpnd tool-servers allow ts_ZdYFc5Zg2fGR web_search_exa`, and until an owner
+runs it, the platform refuses a deploy that names a tool on the server.
+`allow --all` grants every tool on the server, including tools it lists later.
+`deny` withdraws named tools, and `deny --all` clears the standing grant and
+every named one. `refresh` lists the tools again after a vendor changes
+them. `list` and `show` print the API's JSON. With `--text`, `show` prints
+each tool with its allow-list state and a one-line description, and
+`--schemas` adds the reduced argument schema the platform enforces. `create`, `allow`, `deny` and `refresh` render the server
 as it now stands, and `--json` prints the raw payload instead.
 
 When the platform cannot list a server's tools because of the server itself,
@@ -773,9 +782,10 @@ organization must hold provider credentials for every model the run uses.
 Named model declarations hold model names and sampling settings, and the CLI
 refuses a provider key on them.
 
-A run spends the organization's default credential unless the command names
-another. `--credential NAME` names the run's credential. The program's model
-spends it, and so does every model that names no credential of its own.
+`--credential NAME` names the run's credential. The program's model spends
+it, and so does every model that names no credential of its own. Without it,
+those models spend the organization's default, if one is set, and serve
+refuses the run when the organization has none.
 `--reflection-credential NAME` names the credential the reflection model
 spends. `--lm-credential BINDING=NAME` names the credential one model in the
 file's `lms` spends, and repeats once per binding:

{cmpnd-0.82.0 → cmpnd-0.83.0}/docs/client.md

@@ -140,32 +140,44 @@ plain DSPy on its LM and traces nothing.
 A client deploys, runs and optimizes on the platform with its own key and
 endpoint. None of these reads the global config:
 
-- `sdk.deploy_program(program, metric=..., timeout=..., metadata=...)` deploys a
-  `cmpnd.Program` and returns a `cmpnd.DeployedProgram`.
-- `sdk.run_deployment(deployment, *, entrypoint=None, **inputs)` runs one
-  deployment and returns a `dspy.Prediction`. `deployment` is a
-  `DeployedProgram` or a deployment id. `entrypoint` picks the module to run
-  inside a deployment that holds more than one. A `program_name` among the
-  inputs raises `TypeError` and names `entrypoint=`.
+- `sdk.deploy_program(program, *, metric=None, timeout=300, metadata=None,
+  credential=None)` deploys a `cmpnd.Program` and returns a
+  `cmpnd.DeployedProgram`. `credential` is the `cmpnd.Credential` the
+  program's model spends, from `cmpnd.credentials.get(NAME)`. Without one, the
+  deployment spends the organization's default, if one is set, and the platform
+  refuses the deploy when the organization has none. `metadata` is a
+  JSON-serializable dict stored with the deployment record.
+- `sdk.run_deployment(deployment, *, entrypoint=None, timeout=30,
+  metadata=None, tags=None, lm=None, **inputs)` runs one deployment and returns
+  a `dspy.Prediction`. `deployment` is a `DeployedProgram` or a deployment id.
+  `entrypoint` picks the module to run inside a deployment that holds more than
+  one. `metadata` and `tags` are `dict[str, str]` values the platform applies
+  to the run's root trace. The run spends the credential its deployment
+  recorded. A `program_name` among the inputs raises `TypeError` and names
+  `entrypoint=`.
 - `sdk.submit_deployment_run`, `list_deployment_runs`, `get_deployment_run`,
   `get_deployment_run_result` and `wait_deployment_run` submit, find and resume
   runs without waiting in one call. `sdk.deployment_run_id(result)` reads the run
   id of a prediction or an exception. `sdk.get_trace_id(result)` reads the
   id of the run's root trace the same way, or returns `None` when serve named no
   trace.
-- `sdk.optimize_deployment(deployment, optimizer="gepa", ...)` runs the
-  platform's optimization on a deployment and returns the best
+- `sdk.optimize_deployment(deployment, optimizer="gepa", ..., credential=None)`
+  runs the platform's optimization on a deployment and returns the best
   `DeployedProgram`, with `.score`. It never deploys. The program's model comes
-  from the deployment.
+  from the deployment. `credential` names the `cmpnd.Credential` every model
+  that names none spends, else the organization's default, if one is set.
 
 A `DeployedProgram` is not callable: a run needs a client's account, so calling
 one raises `TypeError` and names `run_deployment`. The platform finds a
 deployment by its id within the caller's organization, so another account's
 client gets a 404 for it.
 
-`cmpnd.deploy()`, `cmpnd.execute()`, `cmpnd.optimize()`, the top-level run
-functions and `sdk.run_optimization()` raise a `TypeError` that names the
-client method that replaces them.
+`cmpnd.deploy()`, `cmpnd.deploy_bundle()`, `cmpnd.execute()`,
+`cmpnd.optimize()`, the top-level run functions and `sdk.run_optimization()`
+raise a `TypeError` that names the call that replaces them.
+`cmpnd.deploy_bundle()` names two: `cmpnd deploy SOURCE PROGRAM_NAME` for a
+source file, and `cmpnd.Client().deploy_program(program)` for a
+`cmpnd.Program`.
 
 ## Membership
 

{cmpnd-0.82.0 → cmpnd-0.83.0}/docs/custom-proposer.md

@@ -9,13 +9,15 @@ The proposer does the rewriting. The platform supplies one by default, and
 import generalizing_proposer
 
 client = cmpnd.Client()
-deployment = client.deploy_program(cmpnd.Program("my-program", module=program, lm=lm))
+openai = cmpnd.credentials.get("openai")                         # a credential your organization sealed
+deployment = client.deploy_program(cmpnd.Program("my-program", module=program, lm=lm), credential=openai)
 client.optimize_deployment(
     deployment,
     optimizer="gepa",
     trainset=train,
     valset=val,
     metric=my_metric,
+    credential=openai,                                           # every model below spends it
     proposer=generalizing_proposer.propose,                      # yours
     lms={"proposer-lm": dspy.LM("openai/gpt-6-luna")},          # what it may spend
     reflection_lm=dspy.LM("openai/gpt-6-luna"),