asterinis 0.0.1__py3-none-any.whl

asterinis/__init__.py

@@ -0,0 +1,33 @@
+from .config import AsterinisConfig
+from .connectors import Connector, EchoConnector
+from .context import NexusContext
+from .exceptions import (
+    AsterinisError,
+    ConnectorError,
+    PipelineError,
+    RoutingError,
+)
+from .hooks import HookManager
+from .nexus import Nexus
+from .pipeline import Pipeline
+from .result import NexusResult
+from .router import Router
+
+
+__version__ = "0.0.1"
+
+__all__ = [
+    "AsterinisConfig",
+    "AsterinisError",
+    "Connector",
+    "ConnectorError",
+    "EchoConnector",
+    "HookManager",
+    "Nexus",
+    "NexusContext",
+    "NexusResult",
+    "Pipeline",
+    "PipelineError",
+    "Router",
+    "RoutingError",
+]

asterinis/config.py

@@ -0,0 +1,10 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class AsterinisConfig:
+    default_route: str = "llm"
+    enable_rag: bool = True
+    enable_nlp: bool = True
+    enable_agents: bool = True
+    debug: bool = False

asterinis/connectors.py

@@ -0,0 +1,27 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class Connector(ABC):
+    """
+    Base connector interface.
+
+    Connectors allow Asterinis to communicate with
+    external NLP, RAG, agent, or LLM systems.
+    """
+
+    name: str = "connector"
+
+    @abstractmethod
+    def execute(self, payload: Any) -> Any:
+        raise NotImplementedError
+
+
+class EchoConnector(Connector):
+    name = "echo"
+
+    def execute(self, payload: Any) -> Any:
+        return {
+            "connector": self.name,
+            "payload": payload,
+        }

asterinis/context.py

@@ -0,0 +1,15 @@
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class NexusContext:
+    input_text: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+    state: dict[str, Any] = field(default_factory=dict)
+
+    def set(self, key: str, value: Any) -> None:
+        self.state[key] = value
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self.state.get(key, default)

asterinis/exceptions.py

@@ -0,0 +1,14 @@
+class AsterinisError(Exception):
+    """Base exception for Asterinis."""
+
+
+class RoutingError(AsterinisError):
+    """Raised when routing cannot be completed."""
+
+
+class ConnectorError(AsterinisError):
+    """Raised when a connector fails."""
+
+
+class PipelineError(AsterinisError):
+    """Raised when a pipeline step fails."""

asterinis/hooks.py

@@ -0,0 +1,18 @@
+from collections import defaultdict
+from collections.abc import Callable
+from typing import Any
+
+
+Hook = Callable[..., Any]
+
+
+class HookManager:
+    def __init__(self):
+        self._hooks: dict[str, list[Hook]] = defaultdict(list)
+
+    def register(self, event: str, callback: Hook) -> None:
+        self._hooks[event].append(callback)
+
+    def emit(self, event: str, **kwargs: Any) -> None:
+        for callback in self._hooks.get(event, []):
+            callback(**kwargs)

asterinis/integrations/__init__.py

@@ -0,0 +1,3 @@
+from .flair import FlairConnector
+
+__all__ = ["FlairConnector"]

asterinis/integrations/flair.py

@@ -0,0 +1,49 @@
+# src/asterinis/integrations/flair.py
+
+from typing import Any
+
+from asterinis.connectors import Connector
+
+
+class FlairConnector(Connector):
+    name = "flair"
+
+    def __init__(self, model_name: str = "ner"):
+        try:
+            from flair.nn import Classifier
+        except ImportError as exc:
+            raise ImportError(
+                "Flair is not installed. "
+                'Install it with: pip install "asterinis[flair]"'
+            ) from exc
+
+        self.model_name = model_name
+        self.model = Classifier.load(model_name)
+
+    def execute(self, payload: Any) -> Any:
+        from flair.data import Sentence
+
+        text = payload["text"]
+
+        sentence = Sentence(text)
+        self.model.predict(sentence)
+
+        entities = []
+
+        for entity in sentence.get_spans("ner"):
+            label = entity.get_label("ner")
+
+            entities.append(
+                {
+                    "text": entity.text,
+                    "label": label.value,
+                    "confidence": label.score,
+                }
+            )
+
+        return {
+            "provider": "flair",
+            "model": self.model_name,
+            "text": text,
+            "entities": entities,
+        }

asterinis/middleware.py

@@ -0,0 +1,23 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class Middleware(ABC):
+
+    def before(self, context: Any) -> Any:
+        return context
+
+    def after(self, result: Any) -> Any:
+        return result
+
+
+class TimingMiddleware(Middleware):
+
+    def before(self, context):
+        import time
+
+        context.set("_start_time", time.perf_counter())
+        return context
+
+    def after(self, result):
+        return result

asterinis/nexus.py

@@ -0,0 +1,76 @@
+from collections.abc import Callable
+
+
+RouteRule = Callable[[str], bool]
+
+
+class Router:
+    def __init__(self, default_route: str = "llm"):
+        self.default_route = default_route
+        self._rules: list[tuple[str, RouteRule]] = []
+
+        self._register_default_rules()
+
+    def _register_default_rules(self) -> None:
+        self.add_route(
+            "rag",
+            lambda text: any(
+                word in text.lower()
+                for word in (
+                    "document",
+                    "source",
+                    "retrieve",
+                    "search",
+                )
+            ),
+        )
+
+        self.add_route(
+            "nlp",
+            lambda text: any(
+                word in text.lower()
+                for word in (
+                    "entity",
+                    "ner",
+                    "language",
+                    "nlp",
+                )
+            ),
+        )
+
+        self.add_route(
+            "agent",
+            lambda text: any(
+                word in text.lower()
+                for word in (
+                    "agent",
+                    "tool",
+                    "workflow",
+                )
+            ),
+        )
+
+    def add_route(
+        self,
+        name: str,
+        rule: RouteRule,
+        *,
+        first: bool = False,
+    ) -> None:
+        route = (name, rule)
+
+        if first:
+            self._rules.insert(0, route)
+        else:
+            self._rules.append(route)
+
+    def route(self, text: str) -> str:
+        for name, rule in self._rules:
+            if rule(text):
+                return name
+
+        return self.default_route
+
+    @property
+    def routes(self) -> list[str]:
+        return [name for name, _ in self._rules]

asterinis/pipeline.py

@@ -0,0 +1,33 @@
+from collections.abc import Callable
+from typing import Any
+
+from .context import NexusContext
+from .exceptions import PipelineError
+
+
+PipelineStep = Callable[[NexusContext], NexusContext]
+
+
+class Pipeline:
+    def __init__(self, name: str):
+        self.name = name
+        self._steps: list[PipelineStep] = []
+
+    def add(self, step: PipelineStep) -> "Pipeline":
+        self._steps.append(step)
+        return self
+
+    def run(self, context: NexusContext) -> NexusContext:
+        try:
+            for step in self._steps:
+                context = step(context)
+
+            return context
+
+        except Exception as exc:
+            raise PipelineError(
+                f"Pipeline '{self.name}' failed."
+            ) from exc
+
+    def __len__(self) -> int:
+        return len(self._steps)

asterinis/registry.py

@@ -0,0 +1,31 @@
+from typing import Dict
+
+from .connectors import Connector
+
+
+class ConnectorRegistry:
+    def __init__(self):
+        self._connectors: Dict[str, Connector] = {}
+
+    def register(self, name: str, connector: Connector) -> None:
+        if not name:
+            raise ValueError("Connector name cannot be empty.")
+
+        self._connectors[name] = connector
+
+    def get(self, name: str) -> Connector:
+        if name not in self._connectors:
+            raise KeyError(
+                f"Connector '{name}' is not registered."
+            )
+
+        return self._connectors[name]
+
+    def remove(self, name: str) -> None:
+        self._connectors.pop(name, None)
+
+    def exists(self, name: str) -> bool:
+        return name in self._connectors
+
+    def list(self) -> list[str]:
+        return list(self._connectors.keys())

asterinis/result.py

@@ -0,0 +1,9 @@
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class NexusResult:
+    route: str
+    payload: Any
+    confidence: float = 1.0

asterinis/router.py

@@ -0,0 +1,76 @@
+from collections.abc import Callable
+
+
+RouteRule = Callable[[str], bool]
+
+
+class Router:
+    def __init__(self, default_route: str = "llm"):
+        self.default_route = default_route
+        self._rules: list[tuple[str, RouteRule]] = []
+
+        self._register_default_rules()
+
+    def _register_default_rules(self) -> None:
+        self.add_route(
+            "rag",
+            lambda text: any(
+                word in text.lower()
+                for word in (
+                    "document",
+                    "source",
+                    "retrieve",
+                    "search",
+                )
+            ),
+        )
+
+        self.add_route(
+            "nlp",
+            lambda text: any(
+                word in text.lower()
+                for word in (
+                    "entity",
+                    "ner",
+                    "language",
+                    "nlp",
+                )
+            ),
+        )
+
+        self.add_route(
+            "agent",
+            lambda text: any(
+                word in text.lower()
+                for word in (
+                    "agent",
+                    "tool",
+                    "workflow",
+                )
+            ),
+        )
+
+    def add_route(
+        self,
+        name: str,
+        rule: RouteRule,
+        *,
+        first: bool = False,
+    ) -> None:
+        route = (name, rule)
+
+        if first:
+            self._rules.insert(0, route)
+        else:
+            self._rules.append(route)
+
+    def route(self, text: str) -> str:
+        for name, rule in self._rules:
+            if rule(text):
+                return name
+
+        return self.default_route
+
+    @property
+    def routes(self) -> list[str]:
+        return [name for name, _ in self._rules]

asterinis-0.0.1.dist-info/METADATA

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: asterinis
+Version: 0.0.1
+Summary: Python framework for AI orchestration, RAG, NLP integration, agent routing, and explainable AI.
+Author: Irena Popova
+License: MIT
+Project-URL: Homepage, https://github.com/irenapopova/asterinis
+Project-URL: Repository, https://github.com/irenapopova/asterinis
+Project-URL: Issues, https://github.com/irenapopova/asterinis/issues
+Keywords: ai,rag,nlp,agents,llm,orchestration,flair,machine-learning,python
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: flair
+Requires-Dist: flair>=0.15; extra == "flair"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# asterinis
+# Asterinis
+
+**Asterinis** is an early-stage Python framework for connecting NLP, retrieval-augmented generation (RAG), AI agents, routing logic, explainability, and LLM services through a unified backend nexus.
+
+The project is designed as a lightweight orchestration layer that can connect different AI and NLP components without locking an application to a single model provider or framework.
+
+## Current Status
+
+Asterinis is currently in an early development stage.
+
+The first public release focuses on the core framework structure, including:
+
+* Nexus orchestration
+* Rule-based routing
+* Connector interfaces
+* Processing context
+* Pipelines
+* Hooks
+* Result objects
+* Optional NLP integrations
+
+More advanced RAG, agent orchestration, adaptive routing, evaluation, and explainability features are planned for future releases.
+
+## Installation
+
+The package will be installable from PyPI:
+
+```bash
+pip install asterinis
+```
+
+For optional Flair NLP support:
+
+```bash
+pip install "asterinis[flair]"
+```
+
+## Basic Usage
+
+```python
+from asterinis import Nexus
+
+nexus = Nexus()
+
+result = nexus.process(
+    "Search documents about multilingual NLP."
+)
+
+print(result.route)
+print(result.payload)
+```
+
+Asterinis can route requests toward different processing paths such as:
+
+```text
+rag
+nlp
+agent
+llm
+```
+
+## Flair Integration
+
+Asterinis supports Flair as an optional NLP connector.
+
+```python
+from asterinis import Nexus
+from asterinis.integrations import FlairConnector
+
+nexus = Nexus()
+
+nexus.register_connector(
+    "nlp",
+    FlairConnector("ner")
+)
+
+result = nexus.process(
+    "Deutsche Bank is based in Frankfurt."
+)
+
+print(result.to_dict())
+```
+
+Flair is an independent open-source NLP framework and is not part of Asterinis. Asterinis provides an integration layer that allows Flair models to participate in a broader orchestration pipeline.
+
+## Architecture
+
+```text
+Application
+    ↓
+Asterinis Nexus
+    ↓
+Router
+    ↓
+┌──────────┬──────────┬──────────┬──────────┐
+│   NLP    │   RAG    │  Agents  │   LLM    │
+└──────────┴──────────┴──────────┴──────────┘
+    ↓
+Connectors / Integrations
+```
+
+The goal is to allow developers to plug different AI systems into a consistent interface.
+
+## Project Structure
+
+```text
+src/
+└── asterinis/
+    ├── __init__.py
+    ├── nexus.py
+    ├── router.py
+    ├── connectors.py
+    ├── context.py
+    ├── pipeline.py
+    ├── hooks.py
+    ├── result.py
+    ├── config.py
+    ├── exceptions.py
+    └── integrations/
+        ├── __init__.py
+        └── flair.py
+```
+
+## Roadmap
+
+Future development may include:
+
+* advanced RAG routing
+* retrieval quality evaluation
+* agent orchestration
+* adaptive routing policies
+* explainability
+* confidence-aware decision logic
+* additional NLP integrations
+* LLM provider connectors
+* evaluation tools
+* persistent context and memory
+* asynchronous pipelines
+
+## Version
+
+Current development version:
+
+```text
+0.0.1
+```
+
+## License
+
+Asterinis is released under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+## Author
+
+Created and maintained by **Irena Popova**, Full-Stack Developer and AI/NLP, RAG, and adaptive systems researcher.

asterinis-0.0.1.dist-info/RECORD

@@ -0,0 +1,19 @@
+asterinis/__init__.py,sha256=hMJeKRJK7bPM0otmtxyiogzLZ0EKn1yCAYr8XLLspVE,655
+asterinis/config.py,sha256=OLY86vKoxOI6ai2vc7vliLnrBiLcHvXBzJKRxugBXng,211
+asterinis/connectors.py,sha256=AsgISf0Fi8wRvtQu8yhysVLnJclNunzvK4gHLQKX6u0,546
+asterinis/context.py,sha256=Y1XsRFMpWxLWh2Wbcggo5GtgNEj3moz9il8TgXfSpTI,415
+asterinis/exceptions.py,sha256=VMLZ7htmz7iYqzXh0rPlLfPFF9Ye8zZMVx3mk3cvFqc,326
+asterinis/hooks.py,sha256=9YpxamjY4IOh2GidswpKE2C74TWA4Z_zr1e3lnXIBN0,475
+asterinis/middleware.py,sha256=frOkSuPzkjSiPECDjIX2uHslvDnErCeHpzfFVKnKwoU,436
+asterinis/nexus.py,sha256=FnpJOxnrAY1-WBaBeciJTpNBoMMCspUhuVJYnoNdC80,1749
+asterinis/pipeline.py,sha256=j4mJt6MTo1WD3tyddNdxZDZBfQToOAoLnSeYzTZX9mY,798
+asterinis/registry.py,sha256=netKS2mqzheM7oPfG9Y2GkXKAP0Mhc-i2Dii0u6zG9o,823
+asterinis/result.py,sha256=veAt85irgORqy569koSJfBAEBe6HDmfWmY1m_9RgEX0,148
+asterinis/router.py,sha256=FnpJOxnrAY1-WBaBeciJTpNBoMMCspUhuVJYnoNdC80,1749
+asterinis/integrations/__init__.py,sha256=OZuBTN7moQFY-nsw8dYi479nloKkCsVJaBaegSbhSrI,63
+asterinis/integrations/flair.py,sha256=7nD77Hy9EneNzpC0jctGFkMYRPadGj9clOY2pR00d48,1226
+asterinis-0.0.1.dist-info/licenses/LICENSE,sha256=G5hhhkfBQ-iZDlxWVKruoyUFZe_htD-Yg2Cgypy4Jh4,1068
+asterinis-0.0.1.dist-info/METADATA,sha256=9N6Ize0IoiWvQy-hRsLoAzm6Ind9l7IMy_pvnlJhv4c,4795
+asterinis-0.0.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+asterinis-0.0.1.dist-info/top_level.txt,sha256=qHE8M453PvQJanXy0EkcUnlUnxB56DT8jsH0oIhWFZY,10
+asterinis-0.0.1.dist-info/RECORD,,

asterinis-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

asterinis-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Irena Popova
+
+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.

asterinis-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+asterinis