Metadata-Version: 2.5
Name: sage-run
Version: 1.0.5
Summary: SAGE Run — workflow-oriented Claude Code runtime
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: jsonschema>=4.23.0
Requires-Dist: pydantic>=2.9.0
Requires-Dist: pyjwt[crypto]>=2.9.0
Requires-Dist: pyrage>=1.1.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: ruamel-yaml>=0.18
Provides-Extra: connectors
Requires-Dist: google-cloud-pubsub>=2.23.0; extra == 'connectors'
Requires-Dist: google-cloud-storage>=2.18.0; extra == 'connectors'
Provides-Extra: dev
Requires-Dist: docker>=7.1.0; extra == 'dev'
Requires-Dist: mypy>=1.11.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Requires-Dist: zstandard==0.25.0; extra == 'dev'
Provides-Extra: knowledge-indexer
Requires-Dist: zstandard==0.25.0; extra == 'knowledge-indexer'
Provides-Extra: kubernetes
Requires-Dist: kubernetes>=30.0.0; extra == 'kubernetes'
Provides-Extra: server
Requires-Dist: apscheduler>=3.10.0; extra == 'server'
Requires-Dist: asyncpg>=0.29.0; extra == 'server'
Requires-Dist: beautifulsoup4>=4.12.3; extra == 'server'
Requires-Dist: boto3>=1.35.0; extra == 'server'
Requires-Dist: claude-agent-sdk==0.2.110; extra == 'server'
Requires-Dist: fastapi>=0.115.0; extra == 'server'
Requires-Dist: fastmcp>=3.0.0; extra == 'server'
Requires-Dist: graphifyy==0.9.56; extra == 'server'
Requires-Dist: minio>=7.2.0; extra == 'server'
Requires-Dist: pgvector>=0.4.0; extra == 'server'
Requires-Dist: psycopg[binary]>=3.2.0; extra == 'server'
Requires-Dist: pydantic-settings>=2.5.0; extra == 'server'
Requires-Dist: python-multipart>=0.0.9; extra == 'server'
Requires-Dist: regex>=2024.11.6; extra == 'server'
Requires-Dist: sqlalchemy[asyncio]>=2.0.30; extra == 'server'
Requires-Dist: uvicorn[standard]>=0.30.0; extra == 'server'
Requires-Dist: websockets>=15.0; extra == 'server'
Description-Content-Type: text/markdown

# SAGE Run

**The governed agent platform for enterprise IT operations.**

SAGE Run (**S**ecure **A**gent **G**overnance & **E**xecution) is a workflow runtime and
control plane for AI agents that perform asynchronous IT operations work: it
queues incoming work, launches an isolated Claude Code agent per task with the
tools and memory that workflow needs, brokers human
approvals/clarifications, and gives you a web UI over all of it. Workflow
implementations (prompts, skills, connector instances, integration policy)
live in your own workflow repository; this repo is the platform they run on.

## Capabilities

- **Workflow packages and bundle assembly** — a workflow is `agent.yaml` +
  `settings.json` + `.mcp.json` + skills/hooks/agents, merged with shared
  platform/team assets into a versioned, checksummed bundle.
- **Claude Code runtime harness** — ephemeral per-task containers with
  subagents, human-in-the-loop approvals, a built-in clarification
  (`AskUserQuestion`) flow, and a sandboxed-credential deny-list so secrets
  never reach the model's shell.
- **MCP server framework** — a public catalog of core (message, memory,
  platform self-service) and integration (Salesforce, Jira, Splunk,
  CloudWatch) servers, plus a pattern for adding your own.
- **Source connectors and task queue** — pluggable ingestion adapters (Pub/Sub,
  ServiceNow polling, ...) that turn external events into queued tasks, with
  alert coalescing.
- **Two-way messaging and human oversight** — agents and operators can
  exchange threaded messages, start work from configured keywords, request
  clarifications, and approve or reject sensitive actions. Mattermost and Slack
  are supported through real-time provider integrations and a pluggable
  messaging interface.
- **Hindsight memory integration** — long-term recall and pattern reflection
  across past incidents, plus per-agent memory volumes backed up to object
  storage.
- **Knowledge Sources** — workflow-scoped access to immutable, commit-pinned
  source repositories, indexed into searchable code and symbol graphs.
- **Web control plane** — tasks, session replay, schedules, approvals,
  analytics, and platform catalogs (MCPs, connectors, memory, workflow-repo
  sync/versioning).
- **Kubernetes instances** from a workflow checkout: published, digest-pinned
  platform images in production and local source builds for development.
  Provider-neutral object storage supports `s3` and `gcs`.

## Architecture

See [docs/architecture.md](docs/architecture.md) for the full component
breakdown and a diagram of the request/task flow (connector or webhook →
task queue → session-manager → runtime container → MCP servers/message
bus/approvals → completion → memory sync → control-plane UI).

## Quick start

Start with your own configured workflow checkout, not a platform clone on the
production server. The [starter](examples/workflow-repo/) is a copy-and-fill
template; configure model access, encrypted credentials and the environment key
before running it.

```sh
cd /path/to/my-workflows
# Local: Rancher Desktop Kubernetes/Moby, kubectl, Helm, configured dev key.
uvx --from 'sage-run==1.0.4' sage-run up .
# Production: prepared k3s host and host-only production key.
uvx --from 'sage-run==1.0.4' sage-run deploy . \
  --host my-agent --env prod --ref main
```

See [Deployment and operations](docs/deployment.md) for first-time keys,
server preparation, local platform development, updates and recovery.
Production deploy targets single-node k3s over SSH. Version 1.0.2 adds UI
Deploy now, deployment Jobs and 7-nightly/3-deployment backup rotation. See
[deployment Jobs](docs/deployment.md#deployment-jobs-and-backups) for
their scope and safety limits. Released versions do not provide general
in-place configuration reload; source-only selective reload and deployment
optimizations are described under
[unreleased deployment changes](docs/deployment.md#unreleased-source-selective-reload-and-deployment-diffs).
They have not changed production. Ordered database migrations remain
unfinished. Serving is Kubernetes-only. Docker
launch/memory helpers and the isolated Postgres fixture exist only under
`tests/` for runtime scenarios, not as an alternative serving stack.

The qualified local CLI path is Rancher Desktop Kubernetes/Moby with a
working-tree hostPath and optional Docker source builds. The chart's standard
Kubernetes resources do **not** establish end-to-end support for k3d, kind,
GKE (including Sandbox/Autopilot), or OpenShift. Those targets need storage,
UID/security policy, RuntimeClass and network adaptation plus actual task
qualification; see the [compatibility matrix](docs/deployment.md#kubernetes-compatibility).

## Documentation

| Doc | Covers |
| --- | --- |
| [docs/architecture.md](docs/architecture.md) | Components and the request/task flow. |
| [docs/configuration.md](docs/configuration.md) | Base/prod overlays, named connections, encrypted secrets, deployment settings and service env reference. |
| [docs/connectors.md](docs/connectors.md) | Connector model, available connectors, and how to add one. |
| [docs/mcps.md](docs/mcps.md) | Core vs. integration MCP servers and their config. |
| [docs/memory.md](docs/memory.md) | Long-term memory (Hindsight), per-agent project memory, hooks, and weekly reflection. |
| [docs/deployment.md](docs/deployment.md) | First install, host prerequisites, local development, CLI/UI update limits, portability, backups and releases. |
| [docs/security.md](docs/security.md) | Permissions, sandbox/credential controls, bundle integrity, approvals, encrypted secrets. |
| [docs/workflow-authoring.md](docs/workflow-authoring.md) | How to build a workflow package (agent.yaml, skills, hooks) and its bundle. |

## Public and private boundary

This repository intentionally ships no company-specific workflows, Salesforce
policies, private connectors, customer memory-bank maps, or private
deployment overrides — those belong in a workflow repository. See
[CONTRIBUTING.md](CONTRIBUTING.md).

## Development

```sh
python -m pytest -q tests/unit          # unit suite, no infra required
python -m ruff check .                  # lint
python -m ruff format --check .         # format check
cd control-plane-ui && npm ci && npm run build   # control-plane UI
```

`make tests` runs the full unit + service (real Postgres) + runtime (real
Docker) suite; see the Makefile (`make help`) for every target.

## Roadmap and contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for how to contribute.

## License

Copyright 2026 Vishal Goel and SAGE Run contributors. SAGE Run's original code
and documentation are licensed under Apache License 2.0, unless otherwise
indicated. See [LICENSE](LICENSE) for the complete terms.

Third-party dependencies, bundled software, container base images, and service
images retain their own licenses and applicable terms. This includes the Claude
Agent SDK and Claude Code CLI; SAGE Run's Apache-2.0 license does not relicense
these components or waive their requirements.
