tdfs4ds.agentops.preflight¶
Pre-deployment checks — everything catchable before the zip is built.
The AgentOps loop is minutes long: upload, poll to published, build the
image, pull it, start the pod. A notebook loop is seconds. So a misconfiguration
that could have been caught locally costs a hundred times more once it ships,
and is diagnosed from pod logs instead of a traceback.
:func:check_agent_deployment folds in every
:func:tdfs4ds.check_configuration check — the model, the embeddings, the
Vector Store, MCP — because a configuration that is broken locally cannot become
correct by being containerised, and then adds the checks that are specific to
running inside a pod.
Contracts, inherited verbatim from check_configuration and tested:
- never raises — every check individually wrapped;
- never returns or prints a secret — variable names, never values;
live=Falsemakes no outbound call.
module-attribute
¶
_PIP_HINT = "The pod's `pip install -r requirements.txt` cannot resolve this version. Publish it, or build a wheel and vendor it into the agent directory and point requirements.txt at the local file. If the deployment installs from a private mirror that already carries it, this check can be overruled — it queries PyPI, which is a default, not an authority."
module-attribute
¶
_STRUCTURED_HINT = 'Set TDFS4DS_STRUCTURED_OUTPUT_METHOD. An in-cluster LiteLLM gateway commonly relays response_format without enforcing it, and the default json_schema path then fails on the first intent classification. Pinning the method also skips the probe request every pod would otherwise pay.'
module-attribute
¶
_BACKEND_HINT = "Set TDFS4DS_VECTOR_STORE_BACKEND='teradata' (with TDFS4DS_TERADATA_AI_API_TYPE) for a pod. A Chroma index lives on the container filesystem, so it is rebuilt from scratch on every restart and is not shared between replicas."
module-attribute
¶
_BD_HINT = 'The business dictionary is empty, so the agent has nothing to answer from and will deploy mute. Run document_process_incremental / document_dataset_incremental (or rebuild_documentation) first.'
module-attribute
¶
_CONNECTION_HINT = "Set TDFS4DS_TD_HOST / _USERNAME / _PASSWORD. The generated agent opens its connection from these, and tdfs4ds's auto-reconnect needs them to recover the pod's session after an idle timeout. If this environment authenticates with a token rather than a password (AI Studio JWT), generate the package with auth='jwt' instead - the caller's own token is then used per request."
module-attribute
¶
_RUNTIME_HINT = 'These are classified as deployment-supplied and are not set in this session, so they will be absent in the pod. Add them to runtime_config in the deployment payload.'
module-attribute
¶
_DEPLOYMENT_CHECKS = (_check_config_deployable, _check_pip_resolvable, _check_agent_runtime, _check_structured_output, _check_vector_backend, _check_business_dictionary, _check_connection_env, _check_mcp_deployment)
First line of text, truncated — errors are often multi-page.
Exceptions are flattened first, so a task-group wrapper never hides the
cause from the caller or from :func:_match_hint.
Run checks and assemble the report.
Parameters¶
checks : sequence of callable
Each takes (live, context) and returns a :func:_result dict.
context : dict, optional
Passed to every check — the shared state a report needs (an agent URL,
a token, an accumulating latency record).
Returns¶
dict
{"ok", "version", "live", "checks"}. ok is True when nothing
failed; a skipped check does not fail the run.
Every setting is classified, and nothing required is missing.
Versions of tdfs4ds on PyPI, or None when the index cannot be reached.
PyPI is a default signal, not an authority: a deployment may install from a private mirror. So a miss is reported as a failure the user can overrule, and an unreachable index is fail-open rather than a false alarm.
The real installed tdfs4ds distribution: (version, editable).
Deliberately not importlib.metadata.version('tdfs4ds'). That returns the
first match on sys.path, and sys.path[0] is the working
directory — so a leftover tdfs4ds.egg-info/ in a source checkout wins
over the actual installed distribution, and the answer changes depending on
where the interpreter was started. Observed live: 0.3.1.170 from the repo
root (a stale July build artifact) versus 0.3.1.77 from anywhere else.
So: enumerate, ignore .egg-info build artifacts, and report whether the
install is editable — under an editable install the source tree is what
actually runs, and a version difference is expected rather than a defect.
The running version can actually be installed inside the container.
The failure that bites is a package built from an unreleased working tree: it imports perfectly in the notebook and fails the pod's image build minutes later, with a much worse error message.
The platform runtime library will be present in the package.
AgentOps ships agent_runtime as loose files in its tutorial folder and it
is on no package index, so a deployment either carries the platform's copy
or a generated compatibility one. Both are fine; having neither is not, and
fails only at pod start.
The structured-output method is pinned rather than probed.
The vector backend survives a pod restart.
The agent has something to answer from.
Does the database accept this session's token as a JWT logon?
Returns (True|False|None, detail) -- None when it could not be
established, which is not a failure.
Delegates to :func:tdfs4ds.utils.reconnect.jwt_logon_verdict. The same
question now guards the .env generator, and two copies of "is this token a
database credential?" would drift -- one of them silently, which is the
whole failure mode this probe exists to catch. See that function for why it
uses raw teradatasql and why it reads the named variable only.
The pod can open, and later recover, its own connection.
What "can" means depends on the auth mode, and getting this wrong in either direction is costly: demanding a password under JWT fails a correct deployment, while accepting a bare host under service identity ships a pod that cannot log on.
MCP is opt-in and Enterprise-only; check it only when asked for.
check_agent_deployment(*, live=True, display=True, dest=None, auth='service', mcp=False, agent_runtime='auto', database=None, database_view=None, databases_readonly=None, data_domain=None)
Validate that this session can be packaged and deployed to AgentOps.
Runs :func:tdfs4ds.check_configuration's checks first — a configuration
broken here cannot become correct in a container — then the deployment
checks: the config split, package installability, the platform runtime
library, structured output, the vector backend, the business dictionary and
the connection environment.
Parameters¶
live : bool, default True
Make the outbound calls. False inspects configuration only.
display : bool, default True
Print the aligned summary, with a fix hint under anything not passing.
dest : str, optional
The scaffolded agent directory, so agent_runtime/ can be verified.
auth : {'service', 'jwt'}, default 'service'
Which credential model the deployment will use. 'jwt' expects the
caller's token per request, so only TDFS4DS_TD_HOST is required at
deploy time. Must match the auth= passed to
:func:generate_agentops_package.
Returns¶
dict
{"ok", "version", "live", "checks": [...]}, the same shape as
:func:tdfs4ds.check_configuration.
Notes¶
Never raises, and never returns or prints a secret — variable names only.
Examples¶
import tdfs4ds tdfs4ds.check_agent_deployment() # doctest: +SKIP tdfs4ds.check_agent_deployment(live=False) # doctest: +SKIP