Metadata-Version: 2.4
Name: connic-composer-sdk
Version: 0.1.40
Summary: The Connic Composer SDK for building agents and enterprise-level tools.
Author-email: Connic Team <hello@connic.co>
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: watchdog>=3.0.0
Requires-Dist: nats-py>=2.7.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: packaging>=23.0
Requires-Dist: websockets>=12.0
Requires-Dist: simpleeval>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# Connic Composer SDK

<div align="center">

Build Connic agents in code.

Define agents in YAML, extend them with Python, test them with hot reload against Connic cloud, and deploy them to Connic-managed environments.

[![PyPI version](https://img.shields.io/pypi/v/connic-composer-sdk.svg)](https://pypi.org/project/connic-composer-sdk/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[Documentation](https://connic.co/docs/v1/build/project-structure) • [Quickstart](https://connic.co/docs/v1/quickstart) • [AI Agent Setup](https://connic.co/docs/v1/ai-agent-setup) • [Agent Templates](https://connic.co/agents) • [Dashboard](https://connic.co/projects)

</div>

---

## What It Is

`connic-composer-sdk` is the Python SDK and CLI for Connic's code-first agent workflow.

Use it to:

- define agents in YAML
- write custom tools as plain Python functions
- add middleware, schemas, sessions, retries, concurrency, and guardrails
- connect MCP servers and use Connic's predefined tools
- validate projects locally before uploading anything
- run hot-reload test sessions in isolated cloud environments
- deploy to Connic from the CLI or through a connected Git repository

## Installation

```bash
pip install connic-composer-sdk
```

Requires Python 3.10 or newer.

## Quick Start

```bash
# Create a new project
connic init my-agents --skill
cd my-agents

# Authenticate this project with Connic
connic login

# Validate the project locally
connic lint

# Start a hot-reload dev session in Connic cloud
connic dev

# Run declarative test suites against an environment
connic test
```

The default scaffold is intentionally minimal. If you want a starter project with working examples, use templates:

```bash
connic init my-agents --templates=invoice,customer-support --skill
```

Browse available templates at [connic.co/agents](https://connic.co/agents).

The optional `--skill` flag installs the Connic AI coding-agent skill into both `.agents/skills/connic` and `.claude/skills/connic` so supported coding agents can use the current Connic project layout, YAML fields, CLI flags, connector patterns, and best practices while editing your repo. For an existing project, run:

```bash
connic skill
```

In an interactive terminal, both commands detect Codex and Claude Code and ask whether to install the full Connic plugin for each detected client. The plugin bundles the same skill with Connic MCP. Declining leaves the project-local skill installation unchanged. See [AI agent setup](https://connic.co/docs/v1/ai-agent-setup) for manual and client-specific paths.

The CLI checks for SDK and installed-skill updates when commands run. To check without updating, including from an AI coding-agent session, run:

```bash
connic update --check
```

## Example Project

```text
my-agents/
├── agents/
│   ├── _defaults.yaml          # optional — shared defaults for every agent
│   └── support-assistant.yaml
├── tools/
│   └── billing.py
├── middleware/
│   └── support-assistant.py
├── schemas/
└── requirements.txt
```

`_defaults.yaml` is optional and can live at any depth under `agents/`. Its values are merged into every agent at that directory level and below (deeper layers and the agent file itself override earlier ones). Lists like `tools`, `mcp_servers`, and `guardrails.input/output` concat with dedup-by-ref so children add to inherited entries. `name` and `description` are not allowed in defaults.

### `agents/support-assistant.yaml`

```yaml
version: "1.0"

name: support-assistant
type: llm
model: connic/glm-5.2
description: "Customer support agent with billing and retrieval access"
system_prompt: |
  You are a concise support agent.
  Use tools when they help produce a more accurate answer.

tools:
  - billing.lookup_invoice
  - retrieval_query

session:
  key: input.user_id
  ttl: 86400

guardrails:
  input:
    - type: prompt_injection
      mode: block
  output:
    - type: system_prompt_leakage
      mode: block
```

### `tools/billing.py`

```python
def lookup_invoice(invoice_id: str) -> dict:
    """Look up invoice status by invoice ID.

    Args:
        invoice_id: The invoice identifier

    Returns:
        Invoice details for the requested invoice
    """
    return {
        "invoice_id": invoice_id,
        "status": "paid",
        "amount": 199.0,
        "currency": "USD",
    }
```

Run:

```bash
connic lint
connic tools
connic test
```

## Core Concepts

### Agent Types

See [Agent Configuration](https://connic.co/docs/v1/build/agent-configuration) for the full YAML reference.

- `llm`: an LLM-driven agent with prompts, tools, MCP servers, schemas, and guardrails
- `tool`: a direct wrapper around a Python tool
- `sequential`: a pipeline that executes multiple agents in order

### Tools

Custom tools are plain Python functions discovered from `tools/`, including nested modules. Type hints and docstrings are used to generate tool schemas automatically. Positional-only parameters, `*args`, and `**kwargs` are not supported. See [Writing Tools](https://connic.co/docs/v1/build/tools) for details.

The SDK also exposes predefined Connic tools such as the ones documented in [Predefined Tools](https://connic.co/docs/v1/build/tools):

- `trigger_agent`
- `trigger_agent_at`
- `retrieval_query`
- `retrieval_store`
- `retrieval_delete`
- `retrieval_list_namespaces`
- `web_search`
- `web_read_page`
- `db_find`
- `db_insert`
- `db_update`
- `db_delete`
- `db_count`
- `db_list_collections`

### Middleware and Runtime Controls

Per-agent middleware lets you modify inputs, enrich context, attach files, stop execution early, and transform outputs. See [Middleware](https://connic.co/docs/v1/build/middleware).

The YAML model also supports:

- retries
- timeouts
- max iteration limits
- key-based concurrency control
- persistent sessions
- output schemas
- MCP server connections
- input and output guardrails

Related docs:

- [MCP](https://connic.co/docs/v1/build/tools/mcp)
- [Guardrails](https://connic.co/docs/v1/build/guardrails)
- [Variables](https://connic.co/docs/v1/platform/environments#environment-variables)
- [Retrieval Tools](https://connic.co/docs/v1/build/tools/retrieval)
- [Database Tools](https://connic.co/docs/v1/build/tools/database)

## CLI Commands

| Command                              | Description                                                     |
| ------------------------------------ | --------------------------------------------------------------- |
| `connic init [name]`                  | Create a new project scaffold                                   |
| `connic init [name] --templates=...`  | Create a project from one or more starter templates             |
| `connic init [name] --skill`          | Create a project, install the skill, and offer detected client plugins |
| `connic skill`                        | Install the project skill and offer detected client plugins     |
| `connic update [--check|--sdk|--skill]` | Check for or install available SDK and skill updates          |
| `connic login`                        | Save project credentials in `.connic`                           |
| `connic lint`                         | Validate agents, tools, middleware, and schemas locally         |
| `connic tools`                        | List discovered tools and signatures                            |
| `connic dev [name]`                   | Start an isolated cloud dev environment with hot reload         |
| `connic test`                         | Run declarative test suites from `tests/` against an environment |
| `connic deploy`                       | Deploy from the CLI to a Connic environment for projects without a connected Git repository |
| `connic migrate`                      | Migrate a LangChain or Google ADK project into a Connic project |

Run `connic <command> --help` for flags and examples.

## Development Workflow

### Local Validation

`connic lint` loads your project locally and catches issues like:

- invalid YAML
- missing required agent fields
- unresolved tool references
- duplicate agent names
- schema and middleware loading problems

### Hot-Reload Testing

`connic dev` creates an isolated development environment in Connic cloud, uploads your local files, and re-syncs changes in a few seconds while you iterate.

This is the main development loop when you need real connectors, predefined tools, and environment-scoped services.

Use `connic test` for one-shot declarative test suites from `tests/`, including CI runs and deploy-gate parity.

### Deployment

Deployment targets Connic-managed environments.

- If your Connic project is connected to a Git repository, pushing to the configured branch is the primary deployment flow.
- `connic deploy` is available for CLI-driven deployments and for projects that do not use a connected repository.

## Documentation

| Topic               | Link                                                                                                     |
| ------------------- | -------------------------------------------------------------------------------------------------------- |
| Overview            | [connic.co/docs/v1/build/project-structure](https://connic.co/docs/v1/build/project-structure)                       |
| Quickstart          | [connic.co/docs/v1/quickstart](https://connic.co/docs/v1/quickstart)                                     |
| Agent Configuration | [connic.co/docs/v1/build/agent-configuration](https://connic.co/docs/v1/build/agent-configuration) |
| Writing Tools       | [connic.co/docs/v1/build/tools](https://connic.co/docs/v1/build/tools)                 |
| Middleware          | [connic.co/docs/v1/build/middleware](https://connic.co/docs/v1/build/middleware)                   |
| Predefined Tools    | [connic.co/docs/v1/build/tools](https://connic.co/docs/v1/build/tools)       |
| MCP                 | [connic.co/docs/v1/build/tools/mcp](https://connic.co/docs/v1/build/tools/mcp)                                 |
| Testing             | [connic.co/docs/v1/test](https://connic.co/docs/v1/test)                         |
| Variables           | [connic.co/docs/v1/platform/environments#environment-variables](https://connic.co/docs/v1/platform/environments#environment-variables)                     |
| Guardrails          | [connic.co/docs/v1/build/guardrails](https://connic.co/docs/v1/build/guardrails)                   |
| Retrieval Tools     | [connic.co/docs/v1/build/tools/retrieval](https://connic.co/docs/v1/build/tools/retrieval)         |
| Database Tools      | [connic.co/docs/v1/build/tools/database](https://connic.co/docs/v1/build/tools/database)           |

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## Support

- Issues: [github.com/connic-org/connic-composer-sdk/issues](https://github.com/connic-org/connic-composer-sdk/issues)
- Email: [support@connic.co](mailto:support@connic.co)

## License

MIT. See [LICENSE](LICENSE).
