smartify-ai 0.1.0
Local runtime for Agent Swarms using the Smartify Grid specification
Requires Python: >=3.11
Keywords: agents, ai, automation, orchestration

# Smartify Runtime

Open-source runtime for AI agent swarms. Orchestrate multiple agents with guardrails, plug-and-play tool integrations (including MCP), and coordinate complex workflows for SaaS applications.

## Features

- **Agent Swarms** - Coordinate multiple AI agents in a hierarchy (controller → relay → substation)
- **Multi-Provider** - Anthropic and OpenAI adapters, easily extensible to other providers
- **MCP Integration** - Plug-and-play with any [Model Context Protocol](https://modelcontextprotocol.io) server
- **Guardrails** - Token, time, and cost limits with configurable breaker actions
- **Parallel Execution** - Run tasks concurrently within constraints
- **Grid YAML** - Declarative workflow specification
- **CLI & API** - Command-line and REST API interfaces
- **Checkpoint/Resume** - Persist and resume long-running workflows

## Quick Start

### Installation

```bash
# Basic installation
pip install smartify

# With MCP support (for external tool servers)
pip install smartify[mcp]

# Development (includes tests, linting)
pip install -e ".[dev]"

# Everything
pip install -e ".[all]"
```

### Validate a Grid

```bash
smartify validate examples/minimal.yaml
```

### Run a Grid

```bash
smartify run examples/calculator.yaml --input project_name=myapp
```

### Check Status

```bash
smartify status <run_id>
```

## Grid Structure

```yaml
apiVersion: smartify.ai/v1
kind: GridSpec

metadata:
  id: my-grid
  name: My Grid

topology:
  nodes:
    - id: controller
      kind: controller
      name: Main Controller
      description: Orchestrate the workflow

    - id: relay_build
      kind: relay
      parent: controller
      name: Build Relay

    - id: sub_impl
      kind: substation
      parent: relay_build
      name: Implementation
```

## Node Types

| Kind | Description |
|------|-------------|
| `controller` | Primary orchestrator (exactly 1 per grid) |
| `relay` | Coordination/delegation node |
| `substation` | Task execution node |
| `foreach` | Fan-out iteration |
| `aggregate` | Fan-in merge |
| `approval` | Human-in-the-loop checkpoint |

## MCP Integration

Connect to external [Model Context Protocol](https://modelcontextprotocol.io) servers for plug-and-play tool access.

```yaml
# In your grid YAML
tools:
  mcpServers:
    - id: filesystem
      transport: stdio
      command: npx
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
      prefix: fs  # Tools become: fs_read_file, fs_write_file, etc.
```

Nodes can then use MCP tools like any builtin:

```yaml
nodes:
  - id: file-worker
    kind: substation
    tools:
      - fs_read_file
      - fs_write_file
```

See [examples/mcp-filesystem.yaml](examples/mcp-filesystem.yaml) for a complete example.

## Agent Providers

Smartify supports multiple LLM providers. Set your API key and the runtime auto-registers the adapter:

```bash
# Anthropic (default)
export ANTHROPIC_API_KEY=your_key

# OpenAI
export OPENAI_API_KEY=your_key
```

Configure per-agent in grid YAML:

```yaml
agents:
  researcher:
    modelPolicy:
      preferred: claude-sonnet-4-20250514
      fallback: [gpt-4o]
```

## Development

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with MCP
pip install -e ".[all]"
pytest

# Type checking
mypy src/

# Linting
ruff check src/
```

## License

MIT. See [LICENSE](LICENSE).