Metadata-Version: 2.4
Name: koyote
Version: 1.1.1
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Rust
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: blake3>=1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: pyjwt[crypto]>=2.8.0
License-File: LICENSE
License-File: NOTICE
Summary: Koyote: autonomous software maintenance for systems that change. Detect contract drift, repair, verify, and deliver PRs.
Keywords: ai-agents,developer-tools,provenance,audit,sandbox,isolation
Home-Page: https://github.com/Devaretanmay/Koyote
License: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/Devaretanmay/Koyote
Project-URL: Issues, https://github.com/Devaretanmay/Koyote/issues
Project-URL: Repository, https://github.com/Devaretanmay/Koyote

<div align="center">

# Koyote

### Your codebase has a second author: the outside world. Koyote reviews its pull requests.

![version](https://img.shields.io/badge/version-1.1.0-blue) ![license](https://img.shields.io/badge/license-Apache--2.0-green) ![python](https://img.shields.io/badge/python-3.10%2B-yellow) ![platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey)

**APIs drift. SDKs break. Koyote detects it, repairs it, and proves it — before your CI goes red.**

```bash
git clone https://github.com/Devaretanmay/Koyote && cd Koyote
pip install .
koyote check /path/to/your-repo   # read-only audit, no AI key needed
```

60 seconds to your first risk register. AI repair is opt-in (`koyote auth`).
PyPI one-liner (`pip install koyote`) lands with the public beta.

[Quickstart](docs/QUICKSTART.md) | [CLI Reference](docs/CLI.md) | [Architecture](docs/ARCHITECTURE.md) | [Validation Guide](docs/VALIDATION_GUIDE.md) | [Join the beta](https://github.com/Devaretanmay/Koyote/issues)

</div>

---

## The Problem

Software changes in two ways:
1. **Internal changes**: Features and fixes written by your team (handled by code review and CI).
2. **External changes**: Upstream API contract drift, major SDK breaking bumps, deprecated endpoints, and security migrations.

Dependabot bumps version strings in lockfiles and leaves CI broken. Human engineers spend 20%+ of engineering cycles reading migration guides, mapping AST callsites, updating wrappers, and fixing broken tests.

**Koyote manages software changes originating outside the repository** — mapping external contracts to internal callsites, synthesizing surgical AST patches, running local formatters, and verifying zero blast radius with sandbox isolation.

---

## The Core Loop
 
```text
Any ChangeSource (Dependency release, vendor changelog, scheduled check, PR webhook)
        ↓
Zero-token AST Scan + Semantic Pattern Memory (.koyote/knowledge/)
        ↓
Shared AI Reasoning Engine (Customer BYOK Provider)
AI reasons; native tools provide evidence and execute/verify
        ↓
┌─────────────────────────────────┬─────────────────────────────────┐
│ Consult (Howl Persona)          │ Work (Hunt Persona)             │
│ Find & explain problems.        │ Find, repair, verify & open PR. │
│ Deep AI impact analysis.        │ Kernel sandbox + real tests.    │
│ Files advisory GitHub Issue.    │ Delivers verified Trust PR.     │
│ Zero files touched.             │ Fails closed on test failure.   │
└─────────────────────────────────┴─────────────────────────────────┘
```

```bash
koyote auth              # Connect BYOK AI provider (Anthropic, OpenAI, Ollama)
koyote doctor            # GitHub / AI / Indexed / Knowledge / Tests / Monitoring
koyote index .           # Zero-token static index
koyote check .           # Read-only drift & impact audit
koyote consult .         # Consult mode: AI assessment as a GitHub Issue, modifies nothing
koyote work .            # Work mode: AI repair, sandbox verification, and PR delivery
```

Two distinct product modes for your team:
- **Consult** (`@howl explain` / `koyote consult`): Deep AI reasoning, architectural impact diagnosis, files a GitHub Issue, modifies zero code.
- **Work** (`@hunt repair` / `koyote work`): Autonomous repair worker, sandbox test verification, delivers a verified PR.
See [GitHub App behavior](docs/GITHUB_APP.md).

## The Core Pipeline

```text
┌─────────────────────────┬─────────────────────────┬─────────────────────────┐
│ 1. Change Detection     │ 2. Dependency Graph     │ 3. Impact Analysis      │
│    Contract drift       │    Source → Callsite    │    ChangeSource-aware   │
├─────────────────────────┼─────────────────────────┼─────────────────────────┤
│ 4. AI-Guided Repair     │ 5. Controlled Execution │ 6. Developer Trust PR   │
│    Reasoned, then applied │    Sandboxed + Evidence │    Verified merge-ready │
└─────────────────────────┴─────────────────────────┴─────────────────────────┘
```

---

## 1. Day-0 Risk Register (`koyote check`)

When you run Koyote on any repository, it immediately answers:
- *What external APIs and SDKs does this codebase depend on?*
- *Which integrations are deprecated, behind, or at risk?*
- *Which breaking changes can Koyote already auto-repair?*

```bash
koyote check .
```

```text
================================================================================
         KOYOTE: EXTERNAL-CHANGE DEPENDENCY AUDIT & RISK REGISTER
================================================================================
Total External Providers Detected: 3
Total AST Callsites Mapped:        14
Auto-Repairable Callsites:         6
--------------------------------------------------------------------------------
[CRITICAL] AT RISK (Action Required):
  * Stripe (stripe@v21.0.0 -> v22.0.0)
    - Status: Breaking parameter mutation detected (amount: number -> string)
    - 4 callsites affected (4 auto-repairable by Koyote)

[WATCHLIST] UPCOMING DEPRECATION:
  * OpenAI (openai@v3.28.0)
    - Status: Deprecated client interface (v4 migration available)
    - 6 callsites affected

[HEALTHY] UP-TO-DATE INTEGRATIONS:
  * Anthropic (@anthropic-ai/sdk@v0.25.0)
    - Status: Up-to-date with active provider contract (4 callsites mapped)
================================================================================
```

Export directly to GitHub Issues or JSON:
```bash
koyote check . --format=github-issue   # Formatted markdown table for GitHub Issues
koyote check . --format=json           # Machine-readable risk register
```

---

## 2. External-Change Dependency Graph (`koyote graph`)

Koyote builds a unified dependency graph linking:
`Provider -> Version -> API Contract -> Manifest Dependency -> Wrapper Client -> AST Callsite -> Migration History`

```bash
koyote graph .
```

```text
================================================================================
                 KOYOTE: EXTERNAL-CHANGE DEPENDENCY GRAPH                     
================================================================================
Repository:              /path/to/my-repo
Providers Ingested:      3
Contracts Modeled:       6
Manifest Dependencies:   4
Wrapper Clients Found:   2
AST Callsites Mapped:    14
Active Graph Edges:      28
================================================================================
  [Wrapper] src/lib/stripe.ts -> wraps stripe
  [Callsite] src/billing.ts:12 -> stripe.charges.create
  [Callsite] src/checkout.ts:45 -> stripe.paymentIntents.create
================================================================================
```

---

## 3. Autonomous Continuous Maintenance (`koyote fix`)

When upstream providers release breaking changes, Koyote detects the drift, synthesizes surgical AST transformations, matches your team's code formatting (`prettier`/`ruff`), validates local tests, and opens a Developer Trust PR:

```bash
# Autonomous migration for a target provider:
koyote fix . --provider stripe

# Custom version bump:
koyote fix . --provider openai --from v3.28.0 --to v4.0.0 --create-pr --repo owner/repo
```

### What `koyote fix` guarantees:
1. **Surgical AST Patching**: Only transforms affected callsites and wrappers.
2. **Local Formatter Bridge**: Formats changed files with your project's `prettier`, `ruff`, or `biome`.
3. **Local Test Verification**: Executes test suites and rejects patches if tests remain red.
4. **Zero Blast Radius**: Verifies that 0 unintended files were modified.
5. **Developer Trust PR**: Generates audit-grade PR markdown containing primary sources, exact callsites, test receipts, and rollback hashes.

---

## Proof, not promises

On a real open-source repo (TalkGPT, OpenAI `v3` → `v4`): verified the green base,
reproduced the breaking bump as a red build, repaired it autonomously, and
returned the suite to green with zero unintended files touched. Refusals are
loud and empty-handed — a repair that can't be proven is a repair not shipped.

Every commit is gated: **527 Rust + 357 Python tests**, lint-clean, with
comment-density and import-hygiene checks. See the [Validation Guide](docs/VALIDATION_GUIDE.md)
for the full protocol.

---

## 4. Controlled Execution & Sandboxed Verification

Koyote provides **controlled, reproducible execution** across local kernel sandboxes (macOS Seatbelt, Linux Landlock), Docker, and CI runners:
- **Zero-Exfiltration Isolation**: Credentials (`~/.ssh`, `~/.aws`, keychains) denied at the kernel boundary.
- **Execution-Evidence Compression**: Native Rust engines distill massive test outputs down to high-signal failure traces and stack traces for PR evidence.
- **2ms Instant Undo**: Pre-execution BLAKE3 hash snapshots enable physical rollback of modified and generated files in 2 milliseconds.

```bash
koyote init                          # Initialize workspace control plane
koyote diff                          # Inspect isolated execution change sets
koyote undo                          # Instant 2ms physical rollback
```

---

## Python SDK

```python
from koyote.graph import build_dependency_graph, audit_dependency_graph
from koyote.maintenance import run_maintenance_cycle

# 1. Audit repository external dependencies
summary = audit_dependency_graph(repo_root=".")
print(f"At Risk: {len(summary['at_risk'])}, Auto-Repairable: {summary['total_auto_repairable']}")

# 2. Run autonomous maintenance cycle
report = run_maintenance_cycle(
    repo_dir=".",
    provider_name="stripe",
    create_pr=False,
)
print(f"Maintenance Outcome: {'GREEN' if report.success else 'REFUSED'}")
print(report.unified_diff)
```

---

## Documentation

[Quickstart Guide](docs/QUICKSTART.md) · [CLI Reference](docs/CLI.md) · [Architecture](docs/ARCHITECTURE.md) · [API Reference](docs/API_REFERENCE.md) · [Validation Guide](docs/VALIDATION_GUIDE.md) · [Agent Governance & Trailers](SPEC.md)

The core abstraction is `ChangeSource` (external API, SDK, OpenAPI, GraphQL, protobuf, webhook,
MCP server, internal service): Koyote keeps software working when the systems around it change.
Vendor SDK migrations are the working wedge; other contract kinds are representable types with no
connectors yet — they fail closed to quarantine instead of guessing.

Under the hood, Koyote is an AI maintenance agent with deterministic tools: a code graph,
repository memory, verified rewrite patterns, sandbox execution, and a fail-closed verifier.
Repeated work reuses verified knowledge instead of re-reasoning, so the system gets faster,
cheaper, and more precise the longer it watches a repository.

## Where Koyote Fits

Conventional AI reviewers start from a human pull request and ask whether the change
is correct. Koyote starts from the other end: a dependency or contract changed out
in the world, and it asks what that breaks in your repository. One AI reasons over
your codebase plus the change itself, backed by maintenance memory — past verified
repairs and quarantined failures. The output is not a review but a repair, proven
against your real test suite before it ever reaches a pull request.

Koyote is not a generic coding agent, a PR reviewer, a Dependabot clone, a
codebase Q&A tool, or vulnerability-management software. It is autonomous
maintenance for systems that change.

The old fable got it backwards: the village stopped believing because the boy
cried wolf over nothing. Most automation still does — vague green checks,
unverified badges, silent passes. Koyote only howls when there's actually
one in the fence: verified repairs, loud refusals, never a faked pass.

## Beta

Koyote is in private beta. The fastest way in: run `koyote check` on your
repo and [open an issue](https://github.com/Devaretanmay/Koyote/issues) with
what it found — misses and false alarms included. That feedback is the roadmap.

## License

Apache-2.0. Copyright 2026 Koyote Authors.


