cordis

Product Introduction

1. Definition: Cordis is a plugin-based meta-framework specifically designed for building Agent (intelligent agent) applications. Technically, it falls into the category of a service-oriented, event-driven orchestration framework for complex AI systems.
2. Core Value Proposition: Cordis exists to solve the critical challenges of module orchestration and lifecycle management in complex AI applications. It provides a unified architectural pattern through service dependency injection and typed event communication, allowing developers to focus on business logic rather than underlying coordination.

Main Features

1. Plugin System: Cordis's core is its plugin architecture. A plugin can be a function with inject and apply(ctx) fields or a Service subclass. Its lifecycle is managed by the Cordis context, enabling modular and composable application development.
2. Service Dependency Injection: Services (like tools, models, sessions) are registered under stable keys (e.g., ctx.tools, ctx.llm) within a Context container. Plugins declare their dependencies via inject, and Cordis automatically resolves the dependency graph, ensuring services start in the correct order without manual sequencing.
3. Typed Event Communication: Services communicate via a strictly typed event system. Events are registered with TypeScript declaration merging and can be dispatched in four distinct modes: emit (observation), waterfall (middleware pipeline with return values), parallel (parallel fan-out), and serial (sequential execution). This ensures predictable and type-safe inter-module communication.
4. Reversible Side Effects: All registrations (event listeners, tool schemas, adapters) are managed as reversible side effects using methods like ctx.effect() or ctx.on(). During plugin reload or teardown, these effects are automatically cleaned up, preventing memory leaks and state corruption.
5. Context and Scope Management: The framework provides a clear hierarchy of contexts and scopes (core, runtime), maintaining runtime invariants. This is crucial for managing resources like sessions, persistence, and user-specific data in a multi-tenant or complex agent environment.

Problems Solved

1. Pain Point: The complexity of orchestrating disparate AI components (LLMs, tools, memory, agents) leads to tightly coupled, hard-to-maintain, and unscalable codebases. Manual lifecycle management is error-prone.
2. Target Audience: Senior developers and engineering teams building sophisticated, production-grade Agent systems that require high extensibility, maintainability, and clear separation of concerns. It is suited for those integrating multiple AI models, tools, and custom logic.
3. Use Cases: Building a complex customer support agent with dynamic tool routing; creating a research assistant that chains multiple LLM calls and data retrieval tools; developing a platform for hosting multiple, distinct AI agents with shared underlying services but isolated sessions.

Unique Advantages

1. Differentiation: Unlike simple Agent libraries that focus on single-turn interactions, Cordis provides a full-stack, application-level framework. Compared to DIY architectures, it enforces a consistent, declarative pattern for dependency and event management, reducing boilerplate and architectural drift.
2. Key Innovation: The combination of a type-safe, multi-mode event system (emit/waterfall/parallel/serial) with a service container powered by dependency injection specifically for AI agent domains. The "reversible side effect" model for resource management is also a critical innovation for robust plugin hot-reloading and teardown.

Frequently Asked Questions (FAQ)

1. What is the Cordis framework used for? Cordis is used for building scalable and maintainable intelligent Agent (AI agent) applications by providing a plugin-based architecture with service dependency injection and typed event communication to manage complex module orchestration.
2. How does Cordis handle communication between different plugins or services? Cordis uses a strictly typed event system with four dispatch modes: emit for fire-and-forget notifications, waterfall for middleware pipelines, parallel for concurrent processing, and serial for ordered execution, ensuring predictable and decoupled communication.
3. What is the benefit of Cordis's service dependency injection? It automatically resolves and orders the startup and shutdown sequences of services (like LLM adapters, toolkits, session managers) based on declared dependencies, eliminating manual orchestration bugs and enabling modular, testable code.
4. Can Cordis plugins be hot-reloaded? Yes, through its "reversible side effects" model. Registrations made via ctx.effect() or similar methods are automatically disposed of when a plugin is reloaded or unloaded, allowing for safer dynamic updates in development or production.
5. Is Cordis only for DeepSeek Harness? While it is the underlying vendor framework for DeepSeek Harness, Cordis is a general-purpose Agent framework. Its design is agnostic to specific AI models or platforms, making it suitable for building a wide variety of typed, plugin-based AI agent systems.