# jxnl/instructor · RepoSense Release & Migration Intelligence

> Cached responses use new keys and isolated per-client name. Upgrade immediately to patch advisory. Migration: Low.

## Metadata
- **Repository URL**: https://github.com/jxnl/instructor
- **Primary Package**: `@instructor-ai/instructor` (NPM)
- **Categories**: `AI-SDK`, `AI-FRAMEWORK`, `BACKEND`
- **Latest Version**: `v1.17.0`
- **Semantic Status**: `SECURITY_PATCH`
- **Bundle Size Impact (unavailable)**: `Size Unavailable`
- **Atom Ingestion Feed**: https://github.com/jxnl/instructor/releases.atom

## The Human Context (Plain-English Pitch)
@instructor-ai/instructor is an open-source library and developer tool in the jxnl/instructor ecosystem. It saves developers from writing repetitive low-level boilerplate from scratch by providing a battle-tested, open-source implementation ready for production.

## Stage 1 Executive Summary ([Core Change] + [Required Action] + [Migration Effort])
Cached responses use new keys and isolated per-client name. Upgrade immediately to patch advisory. Migration: Low.

## Breaking Changes & Required Actions
- Cached responses use new keys and isolated per-client namespaces. Existing cache entries will miss. Set the same explicit `cache_namespace` only when clients are intended to sha...
- Response models with Instructor async-validator decorators are rejected before provider calls or cache lookup, including nested models. Use Pydantic validators or explicitly awa...
- Remote media URLs must resolve to public addresses and cannot contain credentials. Redirects and connected peers are checked, and downloads have size limits.
- Route Anthropic PDF downloads through the bounded public-network fetcher and pin each media connection to a validated IP before sending HTTP.

## Migration Snippet
```ts
npm install @instructor-ai/instructor@1.17.0
```

## Ecosystem Compatibility Matrix & Graph Warnings
- **TypeScript 5.x** [`COMPATIBLE`]: Ships standard TypeScript declaration files without type regressions.

## Zero-Noise Release Timeline
- **v1.17.0** (2026-09-09) [SECURITY_PATCH]: Cached responses use new keys and isolated per-client name. Upgrade immediately to patch advisory. Migration: Low.

## Upgrade & Migration Q&A (GEO Direct Answers)
### Is jxnl/instructor v1.17.0 safe to upgrade in production?
jxnl/instructor v1.17.0 is classified as SECURITY_PATCH (MINOR release). Cached responses use new keys and isolated per-client name. Upgrade immediately to patch advisory. Migration: Low.

### What breaking changes or compatibility risks exist in jxnl/instructor v1.17.0?
No breaking API changes or peer dependency conflicts are recorded for jxnl/instructor v1.17.0 in the RepoSense compatibility graph.

### What is the bundle size impact of @instructor-ai/instructor v1.17.0?
Measured bundle size telemetry is currently unavailable for @instructor-ai/instructor v1.17.0; verify build output locally before deploying.

### How do I upgrade @instructor-ai/instructor to v1.17.0?
Upgrade @instructor-ai/instructor to v1.17.0 by running "npm install @instructor-ai/instructor@1.17.0" and applying the migration steps: npm install @instructor-ai/instructor@1.17.0