opendataframework 0.1.0__tar.gz → 0.3.0__tar.gz

{opendataframework-0.1.0 → opendataframework-0.3.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: opendataframework
-Version: 0.1.0
-Summary: Lightweight, config-driven dependency-injection framework for data applications.
+Version: 0.3.0
+Summary: Lightweight dependency-injection framework for data applications.
 License-Expression: MIT
 License-File: LICENSE
 Author: mykytapavlov
@@ -25,8 +25,8 @@ Lightweight dependency-injection framework for data applications.
 
 This package provides structural abstractions —
 `Entity`, `Repository`, `Component`, `Service`, `Task`, `Pipeline`,
-`Layer`, `Namespace`, `Context`, `Project`, `Config`, `Logger`, `View`
-— with zero third-party dependencies. No UI, no CLI, no MCP server.
+`Agent`, `Function`, `Layer`, `Namespace`, `Context`, `Project`, `Config`,
+`Logger`, `View` — with zero third-party dependencies. No UI, no CLI, no MCP server.
 
 > Need the CLI, UI, or MCP server? That's the
 > [`odf`](https://opendataframework.github.io/odf/) package, which
@@ -81,10 +81,8 @@ class User:
 @Component
 class SQLite:
     def __init__(self, config: Config):
-        self.conn = sqlite3.connect(config.sqlite.path)
-        self.conn.execute(
-            "CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)"
-        )
+        self.conn = sqlite3.connect(config.component.sqlite.path)
+        self.conn.execute("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)")
 
 
 @Repository(User)
@@ -104,7 +102,7 @@ class Users:
 Config file (`config.toml`):
 
 ```toml
-[sqlite]
+[component.sqlite]
 path = "app.db"
 ```
 
@@ -161,7 +159,10 @@ class Users:
 
 An optional, single declaration a `Repository` attaches to itself: which
 representation (table, map, image, video, ...) and field(s) best fit its
-data. Metadata only — this package renders nothing itself. See
+data. Metadata only — this package renders nothing itself. A repository
+whose view points at content (an image, a clip, a document) may also
+implement `content_metadata()` to declare each record's file name and
+MIME type. See
 [View](https://opendataframework.github.io/opendataframework/view/).
 
 ```python
@@ -222,6 +223,51 @@ class DailyAnalytics:
     def execute(self): ...
 ```
 
+## Agent
+
+A finite executable whose steps are decided at run time, typically by a
+language model — handed its goal as arguments to `invoke()`. What it may act
+on is declared through its constructor. The framework ships no model client;
+`invoke()` is where a library of your choice goes.
+
+```python
+@Agent
+class Librarian:
+    def __init__(self, books: Books, model: Model): ...
+
+    def invoke(self, question: str) -> str: ...
+
+
+project.context.call("agent.librarian", question="Anything by Herbert?")
+```
+
+## Function
+
+A plain function made framework-aware — for adopting existing code without
+a class refactor first. Returned unchanged; called through the `Context`,
+its managed dependencies are injected and the rest are arguments.
+
+```python
+@Function
+def load_data(path: str, db: Postgres) -> int: ...
+
+
+project.context.call("function.load-data", path="data.csv")  # db injected
+```
+
+A class asks for a function through its constructor, and gets it with its
+dependencies already filled in:
+
+```python
+@Task
+class Refresh:
+    def __init__(self, load: Annotated[Callable[..., int], load_data]):
+        self.load = load
+
+    def execute(self):
+        return self.load("data.csv")
+```
+
 ## Layer
 
 An organisational grouping — which subsystem a component belongs to
@@ -237,8 +283,8 @@ class Postgres: ...
 ## Namespace
 
 The base class underlying every framework decorator — `Entity`,
-`Component`, `Service`, `Task`, `Pipeline`, `Repository`, and `Layer` are
-all `Namespace` subclasses, each with its own independent name → class
+`Component`, `Service`, `Task`, `Pipeline`, `Agent`, `Function`,
+`Repository`, and `Layer` are all `Namespace` subclasses, each with its own independent name → class
 mapping. A framework extension point, not something end users subclass
 directly. See
 [Namespace](https://opendataframework.github.io/opendataframework/namespace/).
@@ -281,7 +327,7 @@ No circular dependencies — restructure with a shared third collaborator
 instead.
 
 ```python
-component = project.context.get(UsersApi)   # typed, by class
+component = project.context.get(UsersApi)  # typed, by class
 ```
 
 ## Project
@@ -321,6 +367,7 @@ Components provide capabilities.
 Services run for extended periods.
 Tasks execute bounded work.
 Pipelines coordinate tasks (and other pipelines).
+Agents pursue a goal handed to them.
 
 Layers organize components.
 Context manages components and repositories.
@@ -334,7 +381,7 @@ Project owns everything.
 See [`examples/`](examples/README.md) — small, focused projects each
 isolating one core abstraction.
 
-> For the CLI, UI, MCP server, and chat surface 
+> For the CLI, UI, MCP server, and chat surface
 > built on top of this package, see `odf`.
 
 ---

{opendataframework-0.1.0 → opendataframework-0.3.0}/README.md

@@ -9,8 +9,8 @@ Lightweight dependency-injection framework for data applications.
 
 This package provides structural abstractions —
 `Entity`, `Repository`, `Component`, `Service`, `Task`, `Pipeline`,
-`Layer`, `Namespace`, `Context`, `Project`, `Config`, `Logger`, `View`
-— with zero third-party dependencies. No UI, no CLI, no MCP server.
+`Agent`, `Function`, `Layer`, `Namespace`, `Context`, `Project`, `Config`,
+`Logger`, `View` — with zero third-party dependencies. No UI, no CLI, no MCP server.
 
 > Need the CLI, UI, or MCP server? That's the
 > [`odf`](https://opendataframework.github.io/odf/) package, which
@@ -65,10 +65,8 @@ class User:
 @Component
 class SQLite:
     def __init__(self, config: Config):
-        self.conn = sqlite3.connect(config.sqlite.path)
-        self.conn.execute(
-            "CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)"
-        )
+        self.conn = sqlite3.connect(config.component.sqlite.path)
+        self.conn.execute("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)")
 
 
 @Repository(User)
@@ -88,7 +86,7 @@ class Users:
 Config file (`config.toml`):
 
 ```toml
-[sqlite]
+[component.sqlite]
 path = "app.db"
 ```
 
@@ -145,7 +143,10 @@ class Users:
 
 An optional, single declaration a `Repository` attaches to itself: which
 representation (table, map, image, video, ...) and field(s) best fit its
-data. Metadata only — this package renders nothing itself. See
+data. Metadata only — this package renders nothing itself. A repository
+whose view points at content (an image, a clip, a document) may also
+implement `content_metadata()` to declare each record's file name and
+MIME type. See
 [View](https://opendataframework.github.io/opendataframework/view/).
 
 ```python
@@ -206,6 +207,51 @@ class DailyAnalytics:
     def execute(self): ...
 ```
 
+## Agent
+
+A finite executable whose steps are decided at run time, typically by a
+language model — handed its goal as arguments to `invoke()`. What it may act
+on is declared through its constructor. The framework ships no model client;
+`invoke()` is where a library of your choice goes.
+
+```python
+@Agent
+class Librarian:
+    def __init__(self, books: Books, model: Model): ...
+
+    def invoke(self, question: str) -> str: ...
+
+
+project.context.call("agent.librarian", question="Anything by Herbert?")
+```
+
+## Function
+
+A plain function made framework-aware — for adopting existing code without
+a class refactor first. Returned unchanged; called through the `Context`,
+its managed dependencies are injected and the rest are arguments.
+
+```python
+@Function
+def load_data(path: str, db: Postgres) -> int: ...
+
+
+project.context.call("function.load-data", path="data.csv")  # db injected
+```
+
+A class asks for a function through its constructor, and gets it with its
+dependencies already filled in:
+
+```python
+@Task
+class Refresh:
+    def __init__(self, load: Annotated[Callable[..., int], load_data]):
+        self.load = load
+
+    def execute(self):
+        return self.load("data.csv")
+```
+
 ## Layer
 
 An organisational grouping — which subsystem a component belongs to
@@ -221,8 +267,8 @@ class Postgres: ...
 ## Namespace
 
 The base class underlying every framework decorator — `Entity`,
-`Component`, `Service`, `Task`, `Pipeline`, `Repository`, and `Layer` are
-all `Namespace` subclasses, each with its own independent name → class
+`Component`, `Service`, `Task`, `Pipeline`, `Agent`, `Function`,
+`Repository`, and `Layer` are all `Namespace` subclasses, each with its own independent name → class
 mapping. A framework extension point, not something end users subclass
 directly. See
 [Namespace](https://opendataframework.github.io/opendataframework/namespace/).
@@ -265,7 +311,7 @@ No circular dependencies — restructure with a shared third collaborator
 instead.
 
 ```python
-component = project.context.get(UsersApi)   # typed, by class
+component = project.context.get(UsersApi)  # typed, by class
 ```
 
 ## Project
@@ -305,6 +351,7 @@ Components provide capabilities.
 Services run for extended periods.
 Tasks execute bounded work.
 Pipelines coordinate tasks (and other pipelines).
+Agents pursue a goal handed to them.
 
 Layers organize components.
 Context manages components and repositories.
@@ -318,7 +365,7 @@ Project owns everything.
 See [`examples/`](examples/README.md) — small, focused projects each
 isolating one core abstraction.
 
-> For the CLI, UI, MCP server, and chat surface 
+> For the CLI, UI, MCP server, and chat surface
 > built on top of this package, see `odf`.
 
 ---

{opendataframework-0.1.0 → opendataframework-0.3.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "opendataframework"
-version = "0.1.0"
-description = "Lightweight, config-driven dependency-injection framework for data applications."
+version = "0.3.0"
+description = "Lightweight dependency-injection framework for data applications."
 authors = [
     {name = "mykytapavlov",email = "mykytapavlov@users.noreply.github.com"}
 ]

{opendataframework-0.1.0 → opendataframework-0.3.0}/src/opendataframework/__init__.py

@@ -1,9 +1,11 @@
 """Open Data Framework (ODF) package."""
 
+from opendataframework.agent import Agent, AgentProtocol
 from opendataframework.component import Component
 from opendataframework.config import Config
 from opendataframework.context import Context, Lifecycle, Resolver
 from opendataframework.entity import Entity
+from opendataframework.function import Function
 from opendataframework.layer import Analytics, Api, Layer, Messaging, Monitoring, Security, Storage
 from opendataframework.logger import Logger
 from opendataframework.namespace import Namespace
@@ -19,6 +21,8 @@ from opendataframework.service import Service, ServiceProtocol
 from opendataframework.task import Task, TaskProtocol
 from opendataframework.view import (
     AudioView,
+    ContentMetadata,
+    ContentMetadataProtocol,
     DataView,
     DataViewProtocol,
     DocumentView,
@@ -33,16 +37,21 @@ from opendataframework.view import (
 )
 
 __all__ = [
+    "Agent",
+    "AgentProtocol",
     "Analytics",
     "Api",
     "AudioView",
     "Component",
     "Config",
+    "ContentMetadata",
+    "ContentMetadataProtocol",
     "Context",
     "DataView",
     "DataViewProtocol",
     "DocumentView",
     "Entity",
+    "Function",
     "ImageView",
     "Layer",
     "Lifecycle",

opendataframework-0.3.0/src/opendataframework/agent.py

@@ -0,0 +1,101 @@
+"""The ``@Agent`` decorator — the framework's marker for agentic work.
+
+An agent is a class that pursues a goal it is handed at call time, usually
+by driving a model in a loop. The framework owns none of that loop: it
+registers the class, injects what the agent may act on through its
+constructor, and gives the ``Context`` one method — ``invoke()`` — to call
+and log.
+"""
+
+from typing import Protocol, runtime_checkable
+
+from opendataframework.namespace import ExecutionType
+
+
+@runtime_checkable
+class AgentProtocol(Protocol):
+    """Expected interface for classes registered with ``@Agent``.
+
+    An agent implements a single method that pursues a goal and returns a
+    result. Unlike ``TaskProtocol.execute()``, ``invoke()`` takes arguments —
+    whatever the agent's author declares. Being ``@runtime_checkable``, an
+    ``isinstance`` check confirms only that ``invoke`` is present, not its
+    signature.
+    """
+
+    def invoke(self, *args, **kwargs):
+        """Pursue the goal described by the arguments and return a result, or ``None``."""
+        ...
+
+
+class Agent(ExecutionType):
+    """Decorator that registers an agentic class with the Context.
+
+    ``@Agent`` marks a class as a managed agent — a finite, explicitly
+    invoked unit of work whose steps are decided at run time rather than
+    written down in advance. The ``Context`` creates it and injects its
+    dependencies like any other class, and calls its ``invoke()`` method by
+    name through ``Context.call()``.
+
+    The decorated class is returned unchanged. No base class is added and no
+    methods are injected.
+
+    Basic usage — ``invoke()`` takes whatever arguments the agent needs::
+
+        @Agent
+        class Librarian:
+
+            def invoke(self, question: str) -> str:
+                ...
+
+    With an explicit name::
+
+        @Agent(name="librarian")
+        class CatalogueAssistant:
+            ...
+
+    Dependency injection — the constructor declares everything the agent may
+    act on, so its reach is visible in the dependency graph::
+
+        @Agent
+        class Librarian:
+
+            def __init__(self, books: Books, model: Model):
+                self.books = books
+                self.model = model
+
+            def invoke(self, question: str) -> str:
+                ...
+
+        project.context.call("librarian", question="Anything by Herbert?")
+        project.context.get(Librarian).invoke("Anything by Herbert?")
+
+    The framework ships no model client and no loop. ``invoke()`` is where an
+    agentic library, a provider SDK, or hand-written logic goes; the model
+    itself is usually another injected component.
+
+    Looking up registered agents::
+
+        Agent.get("Librarian")   # → Librarian class
+        Agent.get("librarian")   # → Librarian class
+        dict(Agent.items())      # → all registered agents
+
+    Raises:
+        TypeError: If the decorated object is not a class, or is a class that
+            does not define ``invoke()``.
+    """
+
+    @classmethod
+    def _register(cls, key: str, wrapped) -> None:
+        """Store ``wrapped`` under ``key``, requiring it to define ``invoke()``.
+
+        Raises:
+            TypeError: If ``wrapped`` has no callable ``invoke``.
+            ValueError: If ``key`` is already registered in this namespace.
+        """
+        if not callable(getattr(wrapped, "invoke", None)):
+            raise TypeError(
+                f"{cls.__name__} can only decorate a class that defines invoke(), "
+                f"got {wrapped.__name__!r}"
+            )
+        super()._register(key, wrapped)

{opendataframework-0.1.0 → opendataframework-0.3.0}/src/opendataframework/component.py

@@ -6,9 +6,12 @@ injected by the ``Context`` with no execution contract of its own. The
 implement to opt into lifecycle callbacks or inspection tooling.
 """
 
+import inspect
+from collections.abc import Callable
+from dataclasses import dataclass
 from typing import Protocol, runtime_checkable
 
-from opendataframework.namespace import Namespace
+from opendataframework.namespace import ExecutionType
 
 
 @runtime_checkable
@@ -87,7 +90,117 @@ class ChartProtocol(Protocol):
         ...
 
 
-class Component(Namespace):
+@dataclass
+class McpTool:
+    """One MCP tool a Component exposes, returned from ``mcp_tools()``.
+
+    Attributes:
+        name: The tool's local name — namespaced by whatever builds the
+            tool surface (today, the sibling ``odf`` package's
+            ``McpServer`` prefixes it with the component's
+            ``<namespace>.<name>`` key) to avoid collisions with the fixed
+            built-in tools and with other components' tools.
+        description: Human-readable description shown to the MCP client.
+            Must not be empty.
+        handler: The bound method implementing the tool call. Whoever
+            calls the tool — typically a model — sees only its signature,
+            so it must be fully typed: every parameter annotated, no
+            ``*args``/``**kwargs``, a return annotation, and no annotation
+            left as a string.
+        structured_output: Whether the handler's return value should be
+            reported as structured (JSON) output. ``None`` defers to
+            the MCP server's own default behavior, mirroring how this
+            field is expected to be forwarded verbatim by whatever
+            registers the tool.
+
+    Raises:
+        ValueError: If ``description`` is empty.
+        TypeError: If ``handler`` is not callable, has no readable
+            signature, or is not fully typed.
+    """
+
+    name: str
+    description: str
+    handler: Callable[..., object]
+    structured_output: bool | None = None
+
+    def __post_init__(self) -> None:
+        _require_tool(self)
+
+
+def _require_tool(tool: McpTool) -> None:
+    """Raise unless ``tool`` has a description and a fully typed handler.
+
+    A tool is offered to a caller that sees nothing but its description
+    and the handler's signature, so both are checked where the tool is
+    created rather than left to surface as a poor schema.
+
+    Raises:
+        ValueError: If the description is empty.
+        TypeError: If the handler is not callable, has no readable
+            signature, or is not fully typed — naming every problem found.
+    """
+    if not tool.description.strip():
+        raise ValueError(f"MCP tool {tool.name!r} has an empty description")
+    if not callable(tool.handler):
+        raise TypeError(f"MCP tool {tool.name!r}: handler {tool.handler!r} is not callable")
+    try:
+        signature = inspect.signature(tool.handler)
+    except (TypeError, ValueError) as exc:
+        raise TypeError(
+            f"MCP tool {tool.name!r}: the handler's signature cannot be read ({exc}) — "
+            "wrap it in a function with annotated parameters"
+        ) from exc
+    problems: list[str] = []
+    strings = False
+    for parameter in signature.parameters.values():
+        if parameter.kind is inspect.Parameter.VAR_POSITIONAL:
+            problems.append(f"*{parameter.name} is not allowed")
+        elif parameter.kind is inspect.Parameter.VAR_KEYWORD:
+            problems.append(f"**{parameter.name} is not allowed")
+        elif parameter.annotation is inspect.Parameter.empty:
+            problems.append(f"parameter {parameter.name!r} is not annotated")
+        elif isinstance(parameter.annotation, str):
+            problems.append(f"parameter {parameter.name!r} has a string annotation")
+            strings = True
+    if signature.return_annotation is inspect.Signature.empty:
+        problems.append("the return value is not annotated")
+    elif isinstance(signature.return_annotation, str):
+        problems.append("the return value has a string annotation")
+        strings = True
+    if not problems:
+        return
+    hint = (
+        " — remove `from __future__ import annotations` from the module, or the quotes "
+        "around the annotation"
+        if strings
+        else ""
+    )
+    raise TypeError(
+        f"MCP tool {tool.name!r}: the handler must be fully typed, but {'; '.join(problems)}{hint}"
+    )
+
+
+@runtime_checkable
+class McpToolsProtocol(Protocol):
+    """Capability interface for a Component's optional custom MCP tools.
+
+    Independent of ``DetailsProtocol``/``ChartProtocol``/
+    ``OnStartProtocol``/``OnStopProtocol``. Never invoked by ``Context``
+    — detected structurally via ``isinstance(instance, McpToolsProtocol)``
+    and consumed on demand by whatever builds an MCP tool surface. (Today,
+    that's the sibling ``odf`` package's ``McpServer``, which registers
+    each returned ``McpTool`` under
+    ``<kebab(cls.__name__)>.<tool.name>``, alongside its six fixed
+    built-in tools.)
+    """
+
+    def mcp_tools(self) -> list[McpTool]:
+        """Return the component's custom MCP tools, in addition to the fixed built-in surface."""
+        ...
+
+
+class Component(ExecutionType):
     """Decorator that registers a class with the Context for dependency injection.
 
     ``@Component`` marks a class as a managed component — the ``Context``

{opendataframework-0.1.0 → opendataframework-0.3.0}/src/opendataframework/config.py

@@ -7,6 +7,7 @@ components declare it like any other constructor dependency.
 """
 
 import tomllib
+from copy import deepcopy
 from pathlib import Path
 
 from opendataframework.utils import normalize
@@ -30,15 +31,29 @@ class Config:
         >>> cfg["database-url"]
         'postgres://localhost/db'
 
-        Nested access::
+        Nested access — ``[service.postgres]`` in TOML::
 
-            cfg = Config({"storage": {"postgres": {"port": 5432}}})
-            cfg.storage.postgres.port  # → 5432
+            cfg = Config({"service": {"postgres": {"port": 5432}}})
+            cfg.service.postgres.port  # → 5432
     """
 
     def __init__(self, data: dict) -> None:
-        """Wrap ``data``, a (possibly nested) configuration dict."""
-        self._data = data
+        """Wrap a deep copy of ``data``, a (possibly nested) configuration dict.
+
+        ``data`` is copied rather than stored by reference, so mutating the
+        original dict after construction (e.g. one the caller keeps a
+        reference to and mutates after passing to ``Project.from_dict()``)
+        does not leak through this ``Config``.
+
+        Keys are normalised to kebab-case (recursively, through nested
+        dicts), the same way lookup names are, so a key written as
+        ``exclude_years`` in the file is found by any name form.
+
+        Raises:
+            ValueError: If two keys at the same level normalise to the same
+                name (e.g. both ``exclude_years`` and ``exclude-years``).
+        """
+        self._data = _normalize_keys(deepcopy(data))
 
     def __getattr__(self, name: str) -> Config | object:
         """Return value by snake_case attribute name, normalised to kebab-case.
@@ -60,10 +75,10 @@ class Config:
         return Config(value) if isinstance(value, dict) else value
 
     def __getitem__(self, key: str) -> Config | object:
-        """Return value by key (any name form accepted).
+        """Return value by key, normalised to kebab-case (any name form accepted).
 
         Args:
-            key: Config key in any supported form.
+            key: Config key (snake_case, kebab-case, or PascalCase).
 
         Returns:
             A ``Config`` wrapping the value if it is a dict, otherwise the
@@ -73,25 +88,25 @@ class Config:
             KeyError: If the key is not present.
         """
         try:
-            value = self._data[key]
+            value = self._data[normalize(key)]
         except KeyError as err:
             raise KeyError(key) from err
         return Config(value) if isinstance(value, dict) else value
 
     def get(self, key: str, default: object = None) -> Config | object | None:
-        """Return value by key, or ``default`` if absent.
+        """Return value by key (any name form accepted), or ``default`` if absent.
 
         If ``default`` is not given and the key is absent, an empty
         ``Config`` is returned instead of ``None``, so callers can safely
         scope into a section and chain further ``.get()``/attribute access
         without guarding against it being missing:
 
-            cfg = config.get("postgres")
+            cfg = config.get("service").get("postgres")
             url = cfg.database_url          # AttributeError if missing
             port = cfg.get("port", 5432)    # safe fallback
 
         Args:
-            key: Config key.
+            key: Config key (snake_case, kebab-case, or PascalCase).
             default: Fallback value when the key is not present.
 
         Returns:
@@ -100,12 +115,26 @@ class Config:
             or an empty ``Config`` if the key is absent and no default was
             given.
         """
-        value = self._data.get(key)
+        value = self._data.get(normalize(key))
         if value is None:
             return default if default is not None else Config({})
         return Config(value) if isinstance(value, dict) else value
 
 
+def _normalize_keys(data: dict) -> dict:
+    """Return ``data`` with every key normalised to kebab-case, recursively."""
+    result: dict = {}
+    for key, value in data.items():
+        name = normalize(key)
+        if name in result:
+            raise ValueError(
+                f"Config keys conflict after normalisation: {key!r} and another "
+                f"key both map to {name!r}"
+            )
+        result[name] = _normalize_keys(value) if isinstance(value, dict) else value
+    return result
+
+
 def load(path: str) -> dict:
     """Load configuration from a TOML file or directory of TOML files.
 
@@ -125,7 +154,7 @@ def load(path: str) -> dict:
 
     Example:
         >>> config = load("config.toml")
-        >>> config["postgres"]["database-url"]
+        >>> config["service"]["postgres"]["database-url"]
         'postgresql://localhost/mydb'
     """
     p = Path(path)