The Auto-Wiring Engine
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Auto-Wiring Engine is a revolutionary dependency injection system designed for intelligent management of AI agents, services, and configurations. It serves as the core infrastructure of the WIREDUP project, enabling automatic resolution of dependencies, circular dependency detection, and multi-scope lifecycle management. By decoupling component creation from execution, the engine allows developers to build complex agentic workflows with minimal boilerplate.
The engine supports a variety of advanced features, including lazy initialization, type-based service location, and a decorator-based registration API. It integrates directly with the Rust-based NexTerm via a dedicated bridge, allowing terminal commands to be processed through auto-wired AI agents.
Sources: src/core/autowire.py:7-27, README.md:58-61, AGENT.md:15-25
Core Architecture
The architecture of the Auto-Wiring Engine is built around the AutoWire class, which maintains a registry of dependency metadata and manages the instantiation of services. It utilizes a thread-safe registry to store factory functions and instances, ensuring consistent behavior in multi-threaded environments.
Component Relationship
The following diagram illustrates the relationship between the Auto-Wiring Engine, the Service Registry, and the agents it manages.
Dependency Lifecycle and Scopes
The engine manages three distinct lifecycle scopes that determine how and when instances are created and shared across the system.
| Scope | Description |
|---|---|
| SINGLETON | A single instance is created and shared globally for the entire application lifetime. |
| TRANSIENT | A new instance is created every time the dependency is resolved. |
| SCOPED | An instance is shared within a specific ScopedContainer, typically used for request or session lifetimes. |
Sources: src/core/autowire.py:20-25, tests/test_autowire.py:16-43
Dependency Resolution Logic
The resolution process involves analyzing factory signatures, checking for circular references, and recursively instantiating required dependencies.
The engine uses inspect.signature to automatically identify the names of arguments required by a factory and matches them against registered service names.
Sources: src/core/autowire.py:117-150, src/core/autowire.py:215-230
Integration with NexTerm (Rust Bridge)
The engine is accessible from the Rust terminal through the AutoWireBridge. This bridge executes Python scripts that interact with the global AutoWire instance to process commands and list available services.
Interaction Flow
CLI Management
The src/cli.py module provides a command-line interface for interacting with the engine, allowing users to inspect the registry, check status, and verify configurations.
Key CLI Commands
| Command | Functionality | Source |
|---|---|---|
ai-wire init | Sets up configuration directories and default JSON files. | src/cli.py:32-40 |
ai-wire status | Displays registered dependencies and their initialization status. | src/cli.py:126-140 |
ai-wire list-components | Provides a detailed list of components including scopes and tags. | src/cli.py:167-185 |
Sources: src/cli.py:20-190
Usage Examples
Manual Registration and Resolution
Dependencies can be registered using factory functions or class names.
from src.core.autowire import AutoWire, Scope
wire = AutoWire()
wire.register("db", DatabaseClient, scope=Scope.SINGLETON)
wire.register("service", lambda db: DataService(db))
# Resolve the service
service = wire.resolve("service")
Sources: src/core/autowire.py:80-105, tests/test_autowire.py:45-58
Decorator-based Injection
The @inject decorator automatically resolves parameters based on type hints or argument names.
from src.core.autowire import inject
@inject
def process_data(research_agent: BaseAgent):
research_agent.execute("Analyze data")
Sources: src/core/autowire.py:186-205, AGENT.md:144-160
Conclusion
The Auto-Wiring Engine provides a robust, thread-safe foundation for the WIREDUP ecosystem. By managing the complexities of dependency lifecycles and resolution order, it enables the seamless integration of AI agents across both Python and Rust environments, ensuring that services remain decoupled, testable, and highly configurable.
Sources: README.md:58-65, src/core/autowire.py:44-50