rosenix 0.1.0__tar.gz

rosenix-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rosenix-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: rosenix
+Version: 0.1.0
+Summary: A modular, explicit, non-magical framework for building AI-powered software systems.
+Author: Rosenix Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/rosenix-project/rosenix
+Project-URL: Repository, https://github.com/rosenix-project/rosenix
+Project-URL: Issues, https://github.com/rosenix-project/rosenix/issues
+Project-URL: Changelog, https://github.com/rosenix-project/rosenix/blob/main/CHANGELOG.md
+Keywords: ai,agents,llm,framework,async,dependency-injection,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.6
+Requires-Dist: typing-extensions>=4.10
+Provides-Extra: openai
+Requires-Dist: openai>=1.30; extra == "openai"
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.24; extra == "otel"
+Requires-Dist: opentelemetry-sdk>=1.24; extra == "otel"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# Rosenix
+
+[![CI](https://github.com/rosenix-project/rosenix/actions/workflows/ci.yml/badge.svg)](https://github.com/rosenix-project/rosenix/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+A modular, explicit, non-magical framework for building AI-powered software
+systems: assistants, agents, multi-agent systems, AI APIs, workflows, and
+more — on one consistent architecture.
+
+## Philosophy
+
+- **Nothing is magical, nothing is hidden.** No implicit prompt templates,
+  no hidden chains. Every behavior is a plain, typed, inspectable object.
+- **Composition over inheritance.** Providers are `typing.Protocol`s, not
+  base classes — any object with the right shape works, no framework
+  coupling required.
+- **Everything is a plugin.** LLMs, embeddings, vector stores, tools, and
+  memory backends all register through the same plugin system, including
+  third-party packages via `entry_points`.
+
+## Architecture (4 layers)
+
+```
+Layer 4  kits/       Agent, Workflow, Tool decorator      (opinionated)
+Layer 3  runtime/     event bus, task executor, tracing    (execution)
+Layer 2  protocols/   LLMProvider, EmbeddingProvider, ...   (contracts)
+Layer 1  kernel/      DI container, plugin registry, config (foundation)
+```
+
+Each layer only depends on the layers below it. Layer 1 has zero
+AI-specific code — it's a generic application kernel, on purpose, so the
+architecture is proven before AI complexity is added.
+
+## Quickstart
+
+```bash
+pip install -e ".[dev,openai]"
+```
+
+```python
+import asyncio
+from rosenix.kernel.container import Container
+from rosenix.providers.openai_provider import OpenAIProvider
+from rosenix.kits.agent import Agent
+
+async def main():
+    container = Container()
+    container.register(OpenAIProvider, lambda: OpenAIProvider(model="gpt-4o-mini"))
+
+    agent = Agent(llm=container.resolve(OpenAIProvider), name="assistant")
+    reply = await agent.run("Say hello in one sentence.")
+    print(reply)
+
+asyncio.run(main())
+```
+
+See `examples/basic_agent.py` for a full runnable example.
+
+## Development
+
+```bash
+pip install -e ".[dev,openai]"
+pytest --cov=rosenix --cov-report=term-missing
+mypy src/rosenix
+ruff check src/ tests/ examples/
+```
+
+See `CONTRIBUTING.md` for local setup details and current test-coverage
+gaps that are good first contributions.
+
+## Project status
+
+Pre-alpha (`0.x`). The architecture is stable; test coverage on
+`kits/` and `providers/` is still being built out — see `ROADMAP.md`.
+Not yet recommended for production use.

rosenix-0.1.0/README.md

@@ -0,0 +1,75 @@
+# Rosenix
+
+[![CI](https://github.com/rosenix-project/rosenix/actions/workflows/ci.yml/badge.svg)](https://github.com/rosenix-project/rosenix/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+A modular, explicit, non-magical framework for building AI-powered software
+systems: assistants, agents, multi-agent systems, AI APIs, workflows, and
+more — on one consistent architecture.
+
+## Philosophy
+
+- **Nothing is magical, nothing is hidden.** No implicit prompt templates,
+  no hidden chains. Every behavior is a plain, typed, inspectable object.
+- **Composition over inheritance.** Providers are `typing.Protocol`s, not
+  base classes — any object with the right shape works, no framework
+  coupling required.
+- **Everything is a plugin.** LLMs, embeddings, vector stores, tools, and
+  memory backends all register through the same plugin system, including
+  third-party packages via `entry_points`.
+
+## Architecture (4 layers)
+
+```
+Layer 4  kits/       Agent, Workflow, Tool decorator      (opinionated)
+Layer 3  runtime/     event bus, task executor, tracing    (execution)
+Layer 2  protocols/   LLMProvider, EmbeddingProvider, ...   (contracts)
+Layer 1  kernel/      DI container, plugin registry, config (foundation)
+```
+
+Each layer only depends on the layers below it. Layer 1 has zero
+AI-specific code — it's a generic application kernel, on purpose, so the
+architecture is proven before AI complexity is added.
+
+## Quickstart
+
+```bash
+pip install -e ".[dev,openai]"
+```
+
+```python
+import asyncio
+from rosenix.kernel.container import Container
+from rosenix.providers.openai_provider import OpenAIProvider
+from rosenix.kits.agent import Agent
+
+async def main():
+    container = Container()
+    container.register(OpenAIProvider, lambda: OpenAIProvider(model="gpt-4o-mini"))
+
+    agent = Agent(llm=container.resolve(OpenAIProvider), name="assistant")
+    reply = await agent.run("Say hello in one sentence.")
+    print(reply)
+
+asyncio.run(main())
+```
+
+See `examples/basic_agent.py` for a full runnable example.
+
+## Development
+
+```bash
+pip install -e ".[dev,openai]"
+pytest --cov=rosenix --cov-report=term-missing
+mypy src/rosenix
+ruff check src/ tests/ examples/
+```
+
+See `CONTRIBUTING.md` for local setup details and current test-coverage
+gaps that are good first contributions.
+
+## Project status
+
+Pre-alpha (`0.x`). The architecture is stable; test coverage on
+`kits/` and `providers/` is still being built out — see `ROADMAP.md`.
+Not yet recommended for production use.

rosenix-0.1.0/pyproject.toml

@@ -0,0 +1,84 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rosenix"
+dynamic = ["version"]
+description = "A modular, explicit, non-magical framework for building AI-powered software systems."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Rosenix Contributors" }]
+keywords = ["ai", "agents", "llm", "framework", "async", "dependency-injection", "workflow"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.6",
+    "typing-extensions>=4.10",
+]
+
+[project.urls]
+Homepage = "https://github.com/rosenix-project/rosenix"
+Repository = "https://github.com/rosenix-project/rosenix"
+Issues = "https://github.com/rosenix-project/rosenix/issues"
+Changelog = "https://github.com/rosenix-project/rosenix/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+openai = ["openai>=1.30"]
+otel = ["opentelemetry-api>=1.24", "opentelemetry-sdk>=1.24"]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-cov>=5.0",
+    "mypy>=1.10",
+    "ruff>=0.4",
+    "build>=1.2",
+    "twine>=5.0",
+]
+
+# Entry-point group third parties use to register providers automatically.
+# e.g. a pip-installed plugin package can declare:
+#   [project.entry-points."rosenix.providers"]
+#   myllm = "myllm_plugin:MyLLMProvider"
+[project.entry-points."rosenix.providers"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+rosenix = ["py.typed"]
+
+[tool.setuptools.dynamic]
+version = { attr = "rosenix.__version__" }
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.11"
+warn_unused_ignores = true
+show_error_codes = true
+
+[tool.ruff]
+target-version = "py311"
+line-length = 110
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "PYI"]
+
+[tool.coverage.run]
+source = ["rosenix"]
+
+[tool.coverage.report]
+show_missing = true

rosenix-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

rosenix-0.1.0/src/rosenix/__init__.py

@@ -0,0 +1,9 @@
+"""rosenix — a modular, explicit framework for building AI-powered systems.
+
+Public surface is intentionally small. Import from submodules
+(`rosenix.kernel`, `rosenix.protocols`, `rosenix.runtime`,
+`rosenix.kits`) rather than relying on re-exports here, so it's always
+obvious which layer a name comes from.
+"""
+
+__version__ = "0.1.0"

rosenix-0.1.0/src/rosenix/kernel/__init__.py

@@ -0,0 +1,13 @@
+"""Layer 1: Kernel.
+
+Generic application foundation with zero AI-specific code: dependency
+injection, plugin registry, lifecycle management, and layered config.
+Everything above this layer is built on top of these four primitives.
+"""
+
+from rosenix.kernel.config import Config
+from rosenix.kernel.container import Container
+from rosenix.kernel.lifecycle import Lifecycle
+from rosenix.kernel.registry import Registry
+
+__all__ = ["Container", "Registry", "Lifecycle", "Config"]

rosenix-0.1.0/src/rosenix/kernel/config.py

@@ -0,0 +1,68 @@
+"""Layered, typed configuration.
+
+Precedence (lowest to highest): defaults -> file -> environment variables
+-> explicit overrides passed in code. Later layers win. Config is a
+plain Pydantic model, so it's fully typed, validated, and serializable —
+no untyped dict-of-dicts passed around the framework.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Generic, Self, TypeVar
+
+from pydantic import BaseModel
+
+ConfigT = TypeVar("ConfigT", bound=BaseModel)
+
+
+class Config(Generic[ConfigT]):
+    """Builds a validated config object from layered sources.
+
+    `Config` is generic over the schema passed to `__init__`, so
+    `build()`'s return type is the *actual* schema type given —
+    `Config(AppConfig).build()` is statically known to return `AppConfig`,
+    not a bare `BaseModel`.
+
+    Example:
+        class AppConfig(BaseModel):
+            model: str = "gpt-4o-mini"
+            temperature: float = 0.7
+            max_retries: int = 3
+
+        config: AppConfig = (
+            Config(AppConfig)
+            .from_file("config.json")        # optional, ignored if missing
+            .from_env(prefix="ROSENIX_")     # ROSENIX_MODEL, etc.
+            .with_overrides(temperature=0.2)  # explicit, wins over all
+            .build()
+        )
+    """
+
+    def __init__(self, schema: type[ConfigT]) -> None:
+        self._schema = schema
+        self._layers: dict[str, Any] = {}
+
+    def from_file(self, path: str | Path) -> Self:
+        p = Path(path)
+        if p.exists():
+            self._layers.update(json.loads(p.read_text()))
+        return self
+
+    def from_env(self, prefix: str = "") -> Self:
+        fields = self._schema.model_fields
+        for name in fields:
+            env_key = f"{prefix}{name}".upper()
+            if env_key in os.environ:
+                self._layers[name] = os.environ[env_key]
+        return self
+
+    def with_overrides(self, **overrides: Any) -> Self:
+        self._layers.update(overrides)
+        return self
+
+    def build(self) -> ConfigT:
+        """Validate accumulated layers against the schema and return it."""
+        return self._schema.model_validate(self._layers)

rosenix-0.1.0/src/rosenix/kernel/container.py

@@ -0,0 +1,203 @@
+"""Dependency injection container.
+
+Resolves dependencies by type, with explicit lifetimes (singleton,
+transient, scoped) and automatic constructor-argument resolution via
+type hints. No decorators required on the classes being resolved —
+registration is done at the container, not on the class itself, which
+keeps the classes framework-agnostic.
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from enum import Enum, auto
+from typing import Any, Self, TypeVar, get_type_hints
+
+T = TypeVar("T")
+
+Factory = Callable[..., T]
+
+
+class Lifetime(Enum):
+    """How long a resolved instance should live."""
+
+    SINGLETON = auto()  # one instance for the container's lifetime
+    TRANSIENT = auto()  # a new instance every resolve()
+    SCOPED = auto()  # one instance per active scope (see Container.scope())
+
+
+class ContainerError(Exception):
+    """Base error for all container-related failures."""
+
+
+class UnregisteredDependencyError(ContainerError):
+    """Raised when resolve() is asked for a type with no registration."""
+
+    def __init__(self, key: type) -> None:
+        super().__init__(
+            f"No registration found for {key!r}. "
+            f"Register it with container.register(...) before resolving."
+        )
+        self.key = key
+
+
+class CircularDependencyError(ContainerError):
+    """Raised when resolving a type would require resolving itself."""
+
+    def __init__(self, chain: list[type]) -> None:
+        path = " -> ".join(t.__name__ for t in chain)
+        super().__init__(f"Circular dependency detected: {path}")
+        self.chain = chain
+
+
+@dataclass
+class _Registration:
+    factory: Factory
+    lifetime: Lifetime
+    instance: Any | None = field(default=None, repr=False)
+
+
+class Container:
+    """A small, explicit dependency-injection container.
+
+    Example:
+        container = Container()
+        container.register(Clock, lambda: SystemClock(), lifetime=Lifetime.SINGLETON)
+        clock = container.resolve(Clock)
+
+    Constructor auto-wiring: if a registered factory is a plain class,
+    the container inspects its ``__init__`` type hints and resolves each
+    parameter from the container itself, recursively.
+    """
+
+    def __init__(self, parent: Container | None = None) -> None:
+        self._registrations: dict[type, _Registration] = {}
+        self._scoped_instances: dict[type, Any] = {}
+        self._resolving: list[type] = []
+        self._parent = parent
+        self._in_scope = False
+
+    # -- registration ----------------------------------------------------
+
+    def register(
+        self,
+        key: type[T],
+        factory: Factory | None = None,
+        *,
+        lifetime: Lifetime = Lifetime.SINGLETON,
+    ) -> Self:
+        """Register a factory (or the class itself) for `key`.
+
+        If `factory` is omitted, `key` is used as its own factory, and its
+        constructor arguments are auto-resolved from the container.
+        """
+        resolved_factory: Factory = factory if factory is not None else key
+        self._registrations[key] = _Registration(factory=resolved_factory, lifetime=lifetime)
+        return self
+
+    def register_instance(self, key: type[T], instance: T) -> Self:
+        """Register an already-constructed instance as a singleton."""
+        self._registrations[key] = _Registration(
+            factory=lambda: instance, lifetime=Lifetime.SINGLETON, instance=instance
+        )
+        return self
+
+    def is_registered(self, key: type) -> bool:
+        if key in self._registrations:
+            return True
+        if self._parent is not None:
+            return self._parent.is_registered(key)
+        return False
+
+    # -- resolution --------------------------------------------------------
+
+    def resolve(self, key: type[T]) -> T:
+        """Resolve an instance of `key`, constructing dependencies as needed."""
+        if key in self._resolving:
+            raise CircularDependencyError(self._resolving + [key])
+
+        registration = self._find_registration(key)
+        if registration is None:
+            raise UnregisteredDependencyError(key)
+
+        if registration.lifetime == Lifetime.SINGLETON and registration.instance is not None:
+            return registration.instance
+
+        if registration.lifetime == Lifetime.SCOPED and self._in_scope and key in self._scoped_instances:
+            return self._scoped_instances[key]
+
+        self._resolving.append(key)
+        try:
+            instance = self._instantiate(registration.factory)
+        finally:
+            self._resolving.pop()
+
+        if registration.lifetime == Lifetime.SINGLETON:
+            registration.instance = instance
+        elif registration.lifetime == Lifetime.SCOPED and self._in_scope:
+            self._scoped_instances[key] = instance
+
+        return instance
+
+    def _find_registration(self, key: type) -> _Registration | None:
+        if key in self._registrations:
+            return self._registrations[key]
+        if self._parent is not None:
+            return self._parent._find_registration(key)
+        return None
+
+    def _instantiate(self, factory: Factory) -> Any:
+        """Call `factory`, auto-resolving any parameters it declares."""
+        if not (inspect.isclass(factory) or inspect.isfunction(factory) or inspect.ismethod(factory)):
+            # e.g. a lambda or already-bound callable with no introspectable
+            # signature worth walking — just call it directly.
+            return factory()
+
+        try:
+            hints = get_type_hints(factory.__init__ if inspect.isclass(factory) else factory)
+        except (TypeError, NameError):
+            hints = {}
+
+        sig = inspect.signature(factory)
+        kwargs: dict[str, Any] = {}
+        for name, param in sig.parameters.items():
+            if name == "self":
+                continue
+            if param.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
+                continue
+            annotation = hints.get(name, param.annotation)
+            if annotation is inspect.Parameter.empty:
+                if param.default is inspect.Parameter.empty:
+                    raise ContainerError(
+                        f"Cannot auto-wire {factory!r}: parameter '{name}' has no "
+                        f"type hint and no default value."
+                    )
+                continue
+            if self.is_registered(annotation):
+                kwargs[name] = self.resolve(annotation)
+            elif param.default is inspect.Parameter.empty:
+                raise UnregisteredDependencyError(annotation)
+
+        return factory(**kwargs)
+
+    # -- scoping -----------------------------------------------------------
+
+    @contextmanager
+    def scope(self) -> Iterator[Container]:
+        """Open a resolution scope for SCOPED-lifetime registrations.
+
+        Example:
+            with container.scope() as scoped:
+                a = scoped.resolve(RequestContext)
+                b = scoped.resolve(RequestContext)  # same instance as `a`
+            # scope ends: scoped instances are discarded
+        """
+        child = Container(parent=self)
+        child._in_scope = True
+        try:
+            yield child
+        finally:
+            child._scoped_instances.clear()

rosenix-0.1.0/src/rosenix/kernel/lifecycle.py

@@ -0,0 +1,77 @@
+"""Application lifecycle: ordered async startup/shutdown hooks.
+
+Providers, connection pools, and background tasks register hooks here
+instead of doing work in `__init__`, so startup is explicit, ordered,
+awaitable, and shutdown always runs (even on error) in reverse order —
+the same pattern as an async context manager stack.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Self
+
+Hook = Callable[[], Awaitable[None]]
+
+
+class Lifecycle:
+    """Registers and runs startup/shutdown hooks in a predictable order.
+
+    Example:
+        lifecycle = Lifecycle()
+        lifecycle.on_startup(db.connect)
+        lifecycle.on_shutdown(db.disconnect)
+
+        async with lifecycle:
+            ...  # app runs; db.connect() already awaited
+        # db.disconnect() awaited on exit, even if an exception occurred
+    """
+
+    def __init__(self) -> None:
+        self._startup_hooks: list[Hook] = []
+        self._shutdown_hooks: list[Hook] = []
+        self._started = False
+
+    def on_startup(self, hook: Hook) -> Hook:
+        """Register a hook to run on startup, in registration order.
+
+        Can be used as a plain call or as a decorator:
+            @lifecycle.on_startup
+            async def connect(): ...
+        """
+        self._startup_hooks.append(hook)
+        return hook
+
+    def on_shutdown(self, hook: Hook) -> Hook:
+        """Register a hook to run on shutdown, in *reverse* registration
+        order (mirrors context-manager unwind semantics).
+        """
+        self._shutdown_hooks.append(hook)
+        return hook
+
+    async def startup(self) -> None:
+        if self._started:
+            return
+        for hook in self._startup_hooks:
+            await hook()
+        self._started = True
+
+    async def shutdown(self) -> None:
+        if not self._started:
+            return
+        errors: list[Exception] = []
+        for hook in reversed(self._shutdown_hooks):
+            try:
+                await hook()
+            except Exception as exc:  # noqa: BLE001 - collect, don't abort unwind
+                errors.append(exc)
+        self._started = False
+        if errors:
+            raise ExceptionGroup("errors during shutdown", errors)
+
+    async def __aenter__(self) -> Self:
+        await self.startup()
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        await self.shutdown()