agentc Package Documentation

pydantic settings agentc.Auditor[source]

An auditor of various events (e.g., LLM completions) given a catalog.

Show JSON schema

{
   "title": "Auditor",
   "description": "An auditor of various events (e.g., LLM completions) given a catalog.",
   "type": "object",
   "properties": {
      "llm_model_name": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Llm Model Name"
      },
      "agent_name": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Agent Name"
      },
      "conn_string": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Conn String"
      },
      "username": {
         "anyOf": [
            {
               "format": "password",
               "type": "string",
               "writeOnly": true
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Username"
      },
      "password": {
         "anyOf": [
            {
               "format": "password",
               "type": "string",
               "writeOnly": true
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Password"
      },
      "bucket": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Bucket"
      },
      "certificate": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Certificate"
      },
      "catalog": {
         "anyOf": [
            {
               "format": "path",
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Catalog"
      },
      "auditor_output": {
         "anyOf": [
            {
               "format": "path",
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Auditor Output"
      }
   },
   "additionalProperties": false
}

Config:

env_prefix: str = AGENT_CATALOG_

Fields:

agent_name (str | None)
auditor_output (pathlib.Path | None)
bucket (str | None)
catalog (pathlib.Path | None)
certificate (str | None)
conn_string (str | None)
llm_model_name (str | None)
password (pydantic.types.SecretStr | None)
username (pydantic.types.SecretStr | None)

Validators:

_find_local_log » all fields
_find_remote_log » all fields
_initialize_auditor » all fields

field agent_name: str | None = None

Name of the agent tied to this auditor.

This field can be specified on instantiation or on accept(). Agent name specified in accept() overrides a model specified on instantiation.

Validated by:

_find_local_log
_find_remote_log
_initialize_auditor

field auditor_output: Path | None = None

Local audit log file to write to.

If this field and $AGENT_CATALOG_CONN_STRING are not set, we will perform a best-effort search by walking upward from the current working directory until we find the agentc_core.defaults.DEFAULT_ACTIVITY_FOLDER folder and subsequently generate an audit log here.

Audit log files will reach a maximum of 128MB (by default) before they are rotated and compressed.

Validated by:

_find_local_log
_find_remote_log
_initialize_auditor

field bucket: str | None = None

The name of the Couchbase bucket possessing the audit logs.

This field must be specified with conn_string, username, and password.

Validated by:

_find_local_log
_find_remote_log
_initialize_auditor

field catalog: Path | None = None

Location of the catalog path.

This field is used to search for the catalog version. If this field is not set, we will defer to the default behavior of agentc.Provider.

Validated by:

_find_local_log
_find_remote_log
_initialize_auditor

field certificate: str | None = None

Path to the root certificate for TLS associated with the Couchbase cluster.

This field can be specified with conn_string, username, and password for secure connection verification with Couchbase cluster.

Validated by:

_find_local_log
_find_remote_log
_initialize_auditor

field conn_string: str | None = None

Couchbase connection string that points to the audit logs.

This Couchbase instance refers to a CB instance that possesses the audit log collection. This collection is automatically generated on agentc index, so this field is most likely the same instance as the CB instance possessing the catalog. If there exists no local audit log location (e.g., this is deployed in a standalone environment) OR if $AGENT_CATALOG_CATALOG is not explicitly set, we will perform all accept() commands directly on the remote audit log collection.

This field must be specified with username, password, and bucket.

Validated by:

_find_local_log
_find_remote_log
_initialize_auditor

field llm_model_name: str | None = None

Name of the LLM model used to generate the chat messages to-be-audited.

This field can be specified on instantiation or on accept(). A model specified in accept() overrides a model specified on instantiation.

Validated by:

_find_local_log
_find_remote_log
_initialize_auditor

field password: SecretStr | None = None

Password associated with the Couchbase instance possessing the audit logs.

This field must be specified with conn_string, username, and bucket.

Validated by:

_find_local_log
_find_remote_log
_initialize_auditor

field username: SecretStr | None = None

Username associated with the Couchbase instance possessing the audit logs.

This field must be specified with conn_string, password, and bucket.

Validated by:

_find_local_log
_find_remote_log
_initialize_auditor

accept(kind: Kind, content: Any, session: AnyStr, grouping: AnyStr = None, timestamp: datetime = None, model_name: str = None, agent_name: str = None, **kwargs) → None[source]

Parameters:

kind – Kind associated with the message. See analytics.log.Kind for all options here.
content – The (JSON-serializable) message to record. This should be as close to the producer as possible.
session – A unique string associated with the current session / conversation / thread.
grouping – A unique string associated with one “generate” invocation across a group of messages.
timestamp – The time associated with the message production. This must have time-zone information.
model_name – LLM model used with this audit instance. This field can be specified on instantiation or on accept(). A model_name specified in accept() overrides a model specified on instantiation.
agent_name – Agent used with this audit instance. This field can be specified on instantiation or on accept(). An agent_name specified in accept() overrides a model specified on instantiation.

move(node_name: AnyStr, direction: Literal['enter', 'exit'], session: AnyStr, content: Any = None, timestamp: datetime = None, model_name: str = None, agent_name: str = None, **kwargs)[source]

Parameters:

node_name – The node / state this message applies to.
direction – The direction of the move. This can be either “enter” or “exit”.
session – A unique string associated with the current session / conversation / thread.
content – Any additional content that should be recorded with this message.
timestamp – The time associated with the message production. This must have time-zone information.
model_name – LLM model used with this audit instance. This field can be specified on instantiation or on accept(). A model_name specified in accept() overrides a model specified on instantiation.
agent_name – Agent used with this audit instance. This field can be specified on instantiation or on accept(). An agent_name specified in accept() overrides a model specified on instantiation.

pydantic settings agentc.Provider[source]

A provider of indexed “agent building blocks” (e.g., tools).

Show JSON schema

{
   "title": "Provider",
   "type": "object",
   "properties": {
      "conn_string": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Conn String"
      },
      "username": {
         "anyOf": [
            {
               "format": "password",
               "type": "string",
               "writeOnly": true
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Username"
      },
      "password": {
         "anyOf": [
            {
               "format": "password",
               "type": "string",
               "writeOnly": true
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Password"
      },
      "bucket": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Bucket"
      },
      "catalog": {
         "anyOf": [
            {
               "format": "path",
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Catalog"
      },
      "snapshot": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": "__LATEST__",
         "title": "Snapshot"
      },
      "provider_output": {
         "anyOf": [
            {
               "format": "path",
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Provider Output"
      },
      "decorator": {
         "default": null,
         "title": "Decorator"
      },
      "refiner": {
         "default": null,
         "title": "Refiner"
      },
      "secrets": {
         "anyOf": [
            {
               "additionalProperties": {
                  "format": "password",
                  "type": "string",
                  "writeOnly": true
               },
               "type": "object"
            },
            {
               "type": "null"
            }
         ],
         "title": "Secrets"
      },
      "tool_model": {
         "allOf": [
            {
               "$ref": "#/$defs/DataModelType"
            }
         ],
         "default": "typing.TypedDict"
      }
   },
   "$defs": {
      "DataModelType": {
         "enum": [
            "pydantic.BaseModel",
            "pydantic_v2.BaseModel",
            "dataclasses.dataclass",
            "typing.TypedDict",
            "msgspec.Struct"
         ],
         "title": "DataModelType",
         "type": "string"
      }
   },
   "additionalProperties": false
}

Config:

env_prefix: str = AGENT_CATALOG_

Fields:

bucket (str | None)
catalog (pathlib.Path | None)
conn_string (str | None)
decorator (Callable[[agentc_core.provider.provider.ToolProvider.ToolResult], Any] | None)
password (pydantic.types.SecretStr | None)
provider_output (pathlib.Path | tempfile.TemporaryDirectory | None)
refiner (Callable[[list[agentc_core.catalog.catalog.base.SearchResult]], list[agentc_core.catalog.catalog.base.SearchResult]] | None)
secrets (dict[str, pydantic.types.SecretStr] | None)
snapshot (str | None)
tool_model (datamodel_code_generator.DataModelType)
username (pydantic.types.SecretStr | None)

Validators:

_find_local_catalog » all fields
_find_remote_catalog » all fields
_initialize_prompt_provider » all fields
_initialize_tool_provider » all fields
_one_provider_should_exist » all fields

field bucket: str | None = None

The name of the Couchbase bucket possessing the catalog.

This field must be specified with conn_string, username, and password.

Validated by:

_find_local_catalog
_find_remote_catalog
_initialize_prompt_provider
_initialize_tool_provider
_one_provider_should_exist

field catalog: Path | None = None

Location of the catalog path.

If this field and $AGENT_CATALOG_CONN_STRING are not set, we will perform a best-effort search by walking upward from the current working directory until we find the agentc_core.defaults.DEFAULT_ACTIVITY_FOLDER folder.

Validated by:

_find_local_catalog
_find_remote_catalog
_initialize_prompt_provider
_initialize_tool_provider
_one_provider_should_exist

field conn_string: str | None = None

Couchbase connection string that points to the catalog.

This Couchbase instance refers to the CB instance used with the publish command. If there exists no local catalog (e.g., this is deployed in a standalone environment), we will perform all find commands directly on the remote catalog. If this field AND $AGENT_CATALOG_CATALOG are specified, we will issue find on both the remote and local catalog (with local catalog entries taking precedence).

This field must be specified with username, password, and bucket.

Validated by:

_find_local_catalog
_find_remote_catalog
_initialize_prompt_provider
_initialize_tool_provider
_one_provider_should_exist

field decorator: Callable[[ToolResult], Any] | None = <function Provider.<lambda>>

A Python decorator (function) to apply to each result yielded by get_tools_for().

By default, yielded results are callable and possess type annotations + documentation strings, but some agent frameworks may ask for tools whose type is tailored to their own framework. As an example, in LangChain, vanilla Python functions must be converted to langchain_core.tools.BaseTool instances. To avoid having to “box” these tools yourself, we accept a callback to perform this boxing on your behalf.

Validated by:

_find_local_catalog
_find_remote_catalog
_initialize_prompt_provider
_initialize_tool_provider
_one_provider_should_exist

field password: SecretStr | None = None

Password associated with the Couchbase instance possessing the catalog.

This field must be specified with conn_string, username, and bucket.

Validated by:

_find_local_catalog
_find_remote_catalog
_initialize_prompt_provider
_initialize_tool_provider
_one_provider_should_exist

field provider_output: Path | TemporaryDirectory | None = None

Location to save generated Python stubs to, if desired.

On get_tools_for(), tools are dynamically generated and served as annotated Python callables. By default, this code is never written to disk. If this field is specified, we will write all generated files to the given output directory and serve the generated Python callables from these files with a “standard import”.

Validated by:

_find_local_catalog
_find_remote_catalog
_initialize_prompt_provider
_initialize_tool_provider
_one_provider_should_exist

field refiner: Callable[[list[SearchResult]], list[SearchResult]] | None = <function Provider.<lambda>>

A Python function to post-process results (reranking, pruning, etc…) yielded by the catalog.

By default, we perform a strict top-K nearest neighbor search for relevant results. This function serves to perform any additional reranking and pruning before the code generation occurs. This function should accept a list of SearchResult instances (a model with the fields entry and delta) and return a list of SearchResult instances.

We offer an experimental post-processor to cluster closely related results (using delta as the loss function) and subsequently yield the closest cluster (see agentc_core.provider.refiner.ClosestClusterRefiner).

Validated by:

_find_local_catalog
_find_remote_catalog
_initialize_prompt_provider
_initialize_tool_provider
_one_provider_should_exist

field secrets: dict[str, SecretStr] | None [Optional]

A map of identifiers to secret values (e.g., Couchbase usernames, passwords, etc…).

Some tools require access to values that cannot be hard-coded into the tool themselves (for security reasons). As an example, SQL++ tools require a connection string, username, and password. Instead of capturing these raw values in the tool metadata, tool descriptors mandate the specification of a map whose values are secret keys.

secrets:
    - couchbase:
        conn_string: MY_CB_CONN_STRING
        username: MY_CB_USERNAME
        password: MY_CB_PASSWORD

To map the secret keys to values, users will specify their secrets using this field (secrets).

provider = agentc.Provider(secrets={
    "MY_CB_CONN_STRING": "couchbase//23.52.12.254",
    "MY_CB_USERNAME": "admin_7823",
    "MY_CB_PASSWORD": os.getenv("THE_CB_PASSWORD")
})

Validated by:

_find_local_catalog
_find_remote_catalog
_initialize_prompt_provider
_initialize_tool_provider
_one_provider_should_exist

field snapshot: str | None = '__LATEST__'

The snapshot version to find the tools and prompts for.

By default, we use the latest snapshot version if the repo is clean. This snapshot version is retrieved directly from Git (if the repo is clean). If the repo is dirty, we will fetch all tools and prompts from the local catalog (by default). If snapshot is specified at search time (i.e., with get_tools_for() or get_prompt_for()), we will use that snapshot version instead.

Validated by:

_find_local_catalog
_find_remote_catalog
_initialize_prompt_provider
_initialize_tool_provider
_one_provider_should_exist

field tool_model: DataModelType = DataModelType.TypingTypedDict

The target model type for the generated (schema) code for tools.

By default, we generate TypedDict models and attach these as type hints to the generated Python functions. Other options include Pydantic (V2 and V1) models and dataclasses, though these may not be supported by all agent frameworks.

Validated by:

_find_local_catalog
_find_remote_catalog
_initialize_prompt_provider
_initialize_tool_provider
_one_provider_should_exist

field username: SecretStr | None = None

Username associated with the Couchbase instance possessing the catalog.

This field must be specified with conn_string, password, and bucket.

Validated by:

_find_local_catalog
_find_remote_catalog
_initialize_prompt_provider
_initialize_tool_provider
_one_provider_should_exist

get_prompt_for(query: str = None, name: str = None, annotations: str = None, snapshot: str = '__LATEST__') → PromptResult | None[source]

Parameters:

query – A query string (natural language) to search the catalog with.
name – The specific name of the catalog entry to search for.
annotations – An annotation query string in the form of KEY="VALUE" (AND|OR KEY="VALUE")*.
snapshot – The snapshot version to find the tools for. By default, we use the latest snapshot.

Returns:

A single prompt as well any tools attached to the prompt.

get_tools_for(query: str = None, name: str = None, annotations: str = None, snapshot: str = '__LATEST__', limit: int | None = 1) → list[Any][source]

Parameters:

query – A query string (natural language) to search the catalog with.
name – The specific name of the catalog entry to search for.
annotations – An annotation query string in the form of KEY="VALUE" (AND|OR KEY="VALUE")*.
snapshot – The snapshot version to find the tools for. By default, we use the latest snapshot.
limit – The maximum number of results to return.

Returns:

A list of tools (Python functions).

property version: VersionDescriptor

agentc.langchain.audit(chat_model: BaseChatModel, session: AnyStr, auditor: AuditorType) → BaseChatModel[source]

A method to (dynamically) dispatch the BaseChatModel._generate() and BaseChatModel._stream() methods (as well as their asynchronous variants BaseChatModel._agenerate() and BaseChatModel._astream()) to methods that log LLM calls.

Parameters:

chat_model – The LangChain chat model to audit.
session – The session associated with all messages we will audit.
auditor – The auditor to bind to the chat model.

Returns:

The same LangChain chat model that was passed in, but with methods dispatched to audit LLM calls.