weaveflow 1.1.0__py3-none-any.whl

weave/__init__.py

@@ -0,0 +1,63 @@
+"""Weave — composable AI agent framework.
+
+A standard anatomy for AI agents: typed input/output ports, a swappable LLM brain,
+optional memory, guardrails, and an auto-transforming connection protocol so any
+compliant agent can plug into any other. Build an agent once, connect it everywhere.
+
+Quick start
+-----------
+    from weave import agent, DataType, Pipeline
+
+    @agent(name="summarizer", input=DataType.TEXT, output=DataType.TEXT,
+           tags=["summarization"], llm="anthropic:claude-opus-4-8")
+    async def summarize(ctx):
+        return await ctx.complete(f"Summarize:\\n{ctx.input.value}")
+
+    result = await Pipeline([summarize]).run("a long document ...")
+"""
+
+from weave.agent import AgentContext, BaseAgent, agent
+from weave.connection import ConnectionProtocol, Router, register_transform
+from weave.errors import WeaveError
+from weave.guardrails import Guardrails
+from weave.interop import from_callable, from_crewai, from_langchain
+from weave.llm import LLMAdapter, create_adapter, register_provider, supported_providers
+from weave.logger import Logger, logger
+from weave.memory import LongTermMemory, Memory, ShortTermMemory
+from weave.runtime import LocalRunner, Parallel, Pipeline
+from weave.schema import PortSchema, SchemaRegistry, validate
+from weave.types import DataType, Payload
+
+__version__ = "1.1.0"
+
+__all__ = [
+    "agent",
+    "BaseAgent",
+    "AgentContext",
+    "DataType",
+    "Payload",
+    "PortSchema",
+    "SchemaRegistry",
+    "validate",
+    "Pipeline",
+    "Parallel",
+    "LocalRunner",
+    "ConnectionProtocol",
+    "Router",
+    "register_transform",
+    "Guardrails",
+    "from_callable",
+    "from_langchain",
+    "from_crewai",
+    "Memory",
+    "ShortTermMemory",
+    "LongTermMemory",
+    "LLMAdapter",
+    "create_adapter",
+    "register_provider",
+    "supported_providers",
+    "Logger",
+    "logger",
+    "WeaveError",
+    "__version__",
+]

weave/agent/__init__.py

@@ -0,0 +1,7 @@
+"""Agent layer — base class, context, and decorator."""
+
+from weave.agent.base import BaseAgent
+from weave.agent.context import AgentContext
+from weave.agent.decorators import agent
+
+__all__ = ["BaseAgent", "AgentContext", "agent"]

weave/agent/base.py

@@ -0,0 +1,90 @@
+"""BaseAgent — the standard agent anatomy and execution lifecycle (PRD §5.1, §5.3).
+
+An agent's public interface is its ports + capability tags; its internals (brain,
+memory, guardrails) are private. ``run`` orchestrates the nervous system: validate
+input -> pre-guardrails -> handle -> coerce -> validate output -> post-guardrails,
+with on-error hooks and typed error wrapping (fail fast, never swallow).
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from weave.agent.context import AgentContext
+from weave.errors import AgentExecutionError, WeaveError
+from weave.guardrails.hooks import Guardrails
+from weave.llm.base import LLMAdapter
+from weave.logger import logger
+from weave.memory.base import Memory
+from weave.schema.port import PortSchema
+from weave.schema.validator import validate
+from weave.types.payload import Payload
+
+
+class BaseAgent(ABC):
+    """Self-contained capability unit with typed input/output ports."""
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        input_schema: PortSchema,
+        output_schema: PortSchema,
+        capability_tags: tuple[str, ...] = (),
+        brain: LLMAdapter | None = None,
+        memory: Memory | None = None,
+        guardrails: Guardrails | None = None,
+    ) -> None:
+        self.name = name
+        self.input_schema = input_schema
+        self.output_schema = output_schema
+        self.capability_tags = capability_tags
+        self._brain = brain
+        self._memory = memory
+        self._guardrails = guardrails or Guardrails()
+
+    @abstractmethod
+    async def handle(self, ctx: AgentContext) -> Payload | Any:
+        """The agent's private logic. Return a Payload or a raw value to wrap."""
+
+    async def run(self, payload: Payload | Any) -> Payload:
+        """Execute the full lifecycle and return a schema-valid output payload.
+
+        Accepts a raw value or a Payload; a raw value is wrapped to the input port type.
+        """
+        if not isinstance(payload, Payload):
+            payload = Payload(type=self.input_schema.type, value=payload)
+        try:
+            validate(payload, self.input_schema)
+            guarded_input = self._guardrails.run_pre(payload)
+            ctx = AgentContext(input=guarded_input, brain=self._brain, memory=self._memory)
+            raw = await self.handle(ctx)
+            output = self._coerce(raw)
+            validate(output, self.output_schema)
+            return self._guardrails.run_post(output)
+        except WeaveError as exc:
+            self._guardrails.run_on_error(exc)
+            logger.error("Agent failed", agent=self.name, code=exc.code)
+            raise
+        except Exception as exc:
+            self._guardrails.run_on_error(exc)
+            logger.error("Agent raised", agent=self.name, error=str(exc))
+            raise AgentExecutionError(
+                f"Agent '{self.name}' raised during execution",
+                detail=str(exc),
+            ) from exc
+
+    def _coerce(self, raw: Payload | Any) -> Payload:
+        if isinstance(raw, Payload):
+            return raw
+        return Payload(type=self.output_schema.type, value=raw)
+
+    def manifest(self) -> dict[str, Any]:
+        """Portable schema manifest carried by a packaged agent (FR-010)."""
+        return {
+            "name": self.name,
+            "input_schema": self.input_schema.manifest(),
+            "output_schema": self.output_schema.manifest(),
+            "capability_tags": list(self.capability_tags),
+        }

weave/agent/context.py

@@ -0,0 +1,43 @@
+"""Execution context handed to every agent's handler.
+
+Bundles the input payload plus the injected Brain, Memory, and Logger so handlers
+never reach for globals (Dependency Injection). Exposes a thin ``complete`` helper
+so the common "ask the LLM" case is one line.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from typing import Any
+
+from weave.errors import AdapterError
+from weave.llm.base import LLMAdapter
+from weave.logger import Logger
+from weave.logger import logger as default_logger
+from weave.memory.base import Memory
+from weave.types.payload import Payload
+
+
+@dataclass(slots=True)
+class AgentContext:
+    """Everything a handler needs to do its job, injected at run time."""
+
+    input: Payload
+    brain: LLMAdapter | None = None
+    memory: Memory | None = None
+    logger: Logger = default_logger
+
+    def require_brain(self) -> LLMAdapter:
+        if self.brain is None:
+            raise AdapterError(
+                "Agent requires an LLM but none was configured",
+                detail="pass llm='provider:model' when defining the agent",
+            )
+        return self.brain
+
+    async def complete(self, prompt: str, *, system: str | None = None, **opts: Any) -> str:
+        return await self.require_brain().complete(prompt, system=system, **opts)
+
+    def stream(self, prompt: str, *, system: str | None = None, **opts: Any) -> AsyncIterator[str]:
+        return self.require_brain().stream(prompt, system=system, **opts)

weave/agent/decorators.py

@@ -0,0 +1,69 @@
+"""The ``@agent`` decorator — the one-liner way to define an agent.
+
+Wraps an ``async def handler(ctx)`` into a fully-formed ``BaseAgent`` with typed
+ports, capability tags, and an optional LLM brain. This is the ergonomic surface
+(CrewAI/LangChain-style) over the explicit ``BaseAgent`` subclassing API.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Iterable
+from typing import Any
+
+from weave.agent.base import BaseAgent
+from weave.agent.context import AgentContext
+from weave.guardrails.hooks import Guardrails
+from weave.llm.base import LLMAdapter
+from weave.llm.factory import create_adapter
+from weave.memory.base import Memory
+from weave.schema.port import PortSchema
+from weave.types.payload import Payload
+from weave.types.primitives import DataType
+
+Handler = Callable[[AgentContext], Awaitable[Payload | Any]]
+PortLike = DataType | PortSchema
+
+
+class _FunctionAgent(BaseAgent):
+    """Adapts a plain async function to the BaseAgent contract."""
+
+    def __init__(self, handler: Handler, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self._handler = handler
+
+    async def handle(self, ctx: AgentContext) -> Payload | Any:
+        return await self._handler(ctx)
+
+
+def _as_schema(port: PortLike) -> PortSchema:
+    if isinstance(port, PortSchema):
+        return port
+    return PortSchema.of(port)
+
+
+def agent(
+    *,
+    name: str,
+    input: PortLike,
+    output: PortLike,
+    tags: Iterable[str] = (),
+    llm: str | LLMAdapter | None = None,
+    memory: Memory | None = None,
+    guardrails: Guardrails | None = None,
+) -> Callable[[Handler], BaseAgent]:
+    """Decorate an ``async def handler(ctx)`` to produce a ready-to-run agent."""
+
+    def decorator(handler: Handler) -> BaseAgent:
+        brain = create_adapter(llm) if llm is not None else None
+        return _FunctionAgent(
+            handler,
+            name=name,
+            input_schema=_as_schema(input),
+            output_schema=_as_schema(output),
+            capability_tags=tuple(tags),
+            brain=brain,
+            memory=memory,
+            guardrails=guardrails,
+        )
+
+    return decorator

weave/cli/__init__.py

@@ -0,0 +1,5 @@
+"""Weave command-line interface."""
+
+from weave.cli.main import main
+
+__all__ = ["main"]

weave/cli/commands.py

@@ -0,0 +1,72 @@
+"""CLI command implementations: scaffold, validate, package (FR-010).
+
+Each command is a small pure-ish function returning an exit code. The loader imports
+a target module by file path and discovers ``BaseAgent`` instances inside it.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import re
+import zipfile
+from collections.abc import Iterable
+from pathlib import Path
+
+from weave.agent.base import BaseAgent
+from weave.cli.templates import AGENT_TEMPLATE
+from weave.errors import WeaveError
+
+_IDENT_PATTERN = re.compile(r"\W+")
+
+
+def _to_ident(name: str) -> str:
+    cleaned = _IDENT_PATTERN.sub("_", name).strip("_")
+    return cleaned or "agent"
+
+
+def _load_agents(path: Path) -> tuple[BaseAgent, ...]:
+    spec = importlib.util.spec_from_file_location(path.stem, path)
+    if spec is None or spec.loader is None:
+        raise WeaveError("Could not load module", detail=str(path))
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    found = (value for value in vars(module).values() if isinstance(value, BaseAgent))
+    agents = tuple(found)
+    if not agents:
+        raise WeaveError("No Weave agents found in module", detail=str(path))
+    return agents
+
+
+def scaffold(name: str, *, directory: str = ".") -> int:
+    ident = _to_ident(name)
+    target = Path(directory) / f"{ident}.py"
+    if target.exists():
+        raise WeaveError("File already exists", detail=str(target))
+    target.write_text(AGENT_TEMPLATE.format(name=name, ident=ident), encoding="utf-8")
+    print(f"Scaffolded agent -> {target}")
+    return 0
+
+
+def validate(path: str) -> int:
+    agents = _load_agents(Path(path))
+    for agent in agents:
+        print(f"valid: {agent.name} {json.dumps(agent.manifest())}")
+    print(f"{len(agents)} agent(s) validated")
+    return 0
+
+
+def package(path: str, *, output: str | None = None) -> int:
+    source = Path(path)
+    agents = _load_agents(source)
+    archive = Path(output) if output else source.with_suffix(".weave.zip")
+    manifest = {"version": "1.0", "agents": [a.manifest() for a in agents]}
+    with zipfile.ZipFile(archive, "w", zipfile.ZIP_DEFLATED) as bundle:
+        bundle.write(source, arcname=source.name)
+        bundle.writestr("manifest.json", json.dumps(manifest, indent=2))
+    print(f"Packaged {len(agents)} agent(s) -> {archive}")
+    return 0
+
+
+def manifest_lines(agents: Iterable[BaseAgent]) -> list[str]:
+    return [json.dumps(agent.manifest()) for agent in agents]

weave/cli/main.py

@@ -0,0 +1,55 @@
+"""CLI entry point.
+
+Subcommands are dispatched through a lookup map (no if/elif chain). Each handler
+maps parsed args to a command function and returns a process exit code.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Callable, Sequence
+
+from weave import __version__
+from weave.cli import commands
+from weave.errors import WeaveError
+
+Handler = Callable[[argparse.Namespace], int]
+
+_HANDLERS: dict[str, Handler] = {
+    "scaffold": lambda a: commands.scaffold(a.name, directory=a.directory),
+    "validate": lambda a: commands.validate(a.path),
+    "package": lambda a: commands.package(a.path, output=a.output),
+}
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="weave", description="composable AI agent framework CLI")
+    parser.add_argument("--version", action="version", version=f"weave {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    scaffold = sub.add_parser("scaffold", help="Create a starter agent file")
+    scaffold.add_argument("name")
+    scaffold.add_argument("-d", "--directory", default=".")
+
+    validate = sub.add_parser("validate", help="Validate agents in a module")
+    validate.add_argument("path")
+
+    package = sub.add_parser("package", help="Package agents into a portable archive")
+    package.add_argument("path")
+    package.add_argument("-o", "--output", default=None)
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+    handler = _HANDLERS[args.command]
+    try:
+        return handler(args)
+    except WeaveError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

weave/cli/templates.py

@@ -0,0 +1,21 @@
+"""Scaffold templates for the CLI."""
+
+from __future__ import annotations
+
+AGENT_TEMPLATE = '''"""Weave agent: {name}."""
+
+from weave import DataType, agent
+
+
+@agent(
+    name="{name}",
+    input=DataType.TEXT,
+    output=DataType.TEXT,
+    tags=["{name}"],
+    # Swap the brain freely: "openai:gpt-4o", "google:gemini-1.5-pro", "ollama:llama3"
+    llm="anthropic:claude-opus-4-8",
+)
+async def {ident}(ctx):
+    """Describe what this agent does."""
+    return await ctx.complete(f"Process this input:\\n{{ctx.input.value}}")
+'''

weave/connection/__init__.py

@@ -0,0 +1,13 @@
+"""Connection layer — protocol engine, router, and transforms."""
+
+from weave.connection.matcher import Match, Router
+from weave.connection.protocol import ConnectionProtocol
+from weave.connection.transform import get_transform, register_transform
+
+__all__ = [
+    "ConnectionProtocol",
+    "Router",
+    "Match",
+    "register_transform",
+    "get_transform",
+]

weave/connection/matcher.py

@@ -0,0 +1,51 @@
+"""Router / Matcher (PRD §8).
+
+Given a source agent's output port, returns the candidate agents whose input port is
+compatible, ranked by capability-tag affinity. Tag affinity uses Jaccard overlap as a
+dependency-free stand-in for the optional embedding similarity pre-check (§5.4.3);
+swap in an embedding scorer via ``score_fn`` without touching this logic.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Sequence
+from dataclasses import dataclass
+
+from weave.agent.base import BaseAgent
+from weave.types.primitives import DataType, is_compatible
+
+TagScorer = Callable[[Sequence[str], Sequence[str]], float]
+
+
+@dataclass(frozen=True, slots=True)
+class Match:
+    agent: BaseAgent
+    score: float
+
+
+def _jaccard(source_tags: Sequence[str], target_tags: Sequence[str]) -> float:
+    source, target = set(source_tags), set(target_tags)
+    if not source or not target:
+        return 0.0
+    union = source | target
+    return len(source & target) / len(union)
+
+
+class Router:
+    """Matches an output port to compatible, ranked input ports."""
+
+    def __init__(self, score_fn: TagScorer = _jaccard) -> None:
+        self._score = score_fn
+
+    def match(
+        self,
+        source: BaseAgent,
+        candidates: Iterable[BaseAgent],
+    ) -> tuple[Match, ...]:
+        out_type: DataType = source.output_schema.type
+        compatible = (
+            Match(candidate, self._score(source.capability_tags, candidate.capability_tags))
+            for candidate in candidates
+            if is_compatible(out_type, candidate.input_schema.type)
+        )
+        return tuple(sorted(compatible, key=lambda m: m.score, reverse=True))

weave/connection/protocol.py

@@ -0,0 +1,61 @@
+"""Connection Protocol Engine (PRD §5.4).
+
+Runs the four-step handshake when one agent's output feeds another's input:
+1. Schema type match (identical or declared-compatible).
+2. Shape validation (delegated to the schema validator for structured_json).
+3. Capability pre-check (delegated to the Router; optional, non-blocking here).
+4. Transform injection (compatible-but-not-identical types get an auto transform).
+"""
+
+from __future__ import annotations
+
+from weave.connection.transform import get_transform
+from weave.errors import ConnectionIncompatibleError
+from weave.llm.base import LLMAdapter
+from weave.schema.port import PortSchema
+from weave.schema.validator import validate
+from weave.types.payload import Payload
+from weave.types.primitives import is_compatible, needs_transform
+
+
+class ConnectionProtocol:
+    """Validates and executes a single agent-to-agent handoff."""
+
+    def check(self, source: PortSchema, target: PortSchema) -> None:
+        """Step 1: fail fast if the source output cannot reach the target input."""
+        if is_compatible(source.type, target.type):
+            return
+        raise ConnectionIncompatibleError(
+            "Output port is not compatible with the target input port",
+            detail=f"'{source.type.value}' cannot connect to '{target.type.value}'",
+        )
+
+    async def handoff(
+        self,
+        payload: Payload,
+        source: PortSchema,
+        target: PortSchema,
+        *,
+        brain: LLMAdapter | None = None,
+    ) -> Payload:
+        """Run the full handshake and return a payload valid for the target port."""
+        self.check(source, target)
+        converted = await self._maybe_transform(payload, source, target, brain)
+        return validate(converted, target)
+
+    async def _maybe_transform(
+        self,
+        payload: Payload,
+        source: PortSchema,
+        target: PortSchema,
+        brain: LLMAdapter | None,
+    ) -> Payload:
+        if not needs_transform(source.type, target.type):
+            return payload
+        transform = get_transform(source.type, target.type)
+        if transform is None:
+            raise ConnectionIncompatibleError(
+                "No transform registered for compatible types",
+                detail=f"missing '{source.type.value}' -> '{target.type.value}'",
+            )
+        return await transform(payload, brain)

weave/connection/transform.py

@@ -0,0 +1,108 @@
+"""Transform registry — auto-injected type converters (PRD §5.4.4).
+
+When two ports are compatible but not identical, the protocol injects a transform to
+convert the payload. Transforms live in a lookup map keyed by ``(from, to)`` so a new
+conversion is one registration — never an edit to branching logic (Open/Closed).
+
+Deterministic conversions need no LLM; semantic ones (e.g. text -> structured_json)
+require a brain and fail fast with an actionable error when none is supplied.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from weave.errors import ConnectionIncompatibleError
+from weave.llm.base import LLMAdapter
+from weave.types.payload import Payload
+from weave.types.primitives import DataType
+
+Transform = Callable[[Payload, LLMAdapter | None], Awaitable[Payload]]
+
+_EXTRACTION_PROMPT = (
+    "Convert the following content into a single valid JSON object. "
+    "Respond with JSON only, no prose:\n\n{content}"
+)
+
+# Strips ```json … ``` / ``` … ``` fences that models often wrap JSON in.
+_FENCE_PATTERN = re.compile(r"```(?:json)?\s*|\s*```", re.IGNORECASE)
+
+
+async def _code_to_text(payload: Payload, _: LLMAdapter | None) -> Payload:
+    return Payload(type=DataType.TEXT, value=payload.value, metadata=payload.metadata)
+
+
+async def _json_to_text(payload: Payload, _: LLMAdapter | None) -> Payload:
+    return Payload(type=DataType.TEXT, value=json.dumps(payload.value), metadata=payload.metadata)
+
+
+async def _passthrough_to_text(payload: Payload, _: LLMAdapter | None) -> Payload:
+    return Payload(type=DataType.TEXT, value=str(payload.value), metadata=payload.metadata)
+
+
+async def _stream_to_text(payload: Payload, _: LLMAdapter | None) -> Payload:
+    chunks = [chunk async for chunk in payload.value]
+    return Payload(type=DataType.TEXT, value="".join(chunks), metadata=payload.metadata)
+
+
+async def _text_to_code(payload: Payload, _: LLMAdapter | None) -> Payload:
+    return Payload(type=DataType.CODE, value=payload.value, metadata=payload.metadata)
+
+
+def _parse_json_object(raw: str) -> dict[str, Any]:
+    """Parse a JSON object from an LLM reply, tolerating code fences and prose.
+
+    Models often wrap JSON in ```json fences or add a sentence around it. We strip
+    fences, fall back to the outermost {...} span, and raise a typed error (never a
+    bare ValueError) when nothing parses.
+    """
+    cleaned = _FENCE_PATTERN.sub("", raw).strip()
+    candidates = [cleaned]
+    start, end = cleaned.find("{"), cleaned.rfind("}")
+    if 0 <= start < end:
+        candidates.append(cleaned[start : end + 1])
+    for candidate in candidates:
+        try:
+            parsed = json.loads(candidate)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(parsed, dict):
+            return parsed
+    raise ConnectionIncompatibleError(
+        "text -> structured_json transform could not parse a JSON object",
+        detail=f"model returned: {raw[:200]}",
+    )
+
+
+async def _text_to_json(payload: Payload, brain: LLMAdapter | None) -> Payload:
+    if brain is None:
+        raise ConnectionIncompatibleError(
+            "text -> structured_json transform needs an LLM brain",
+            detail="pass an llm to the pipeline/runner to enable semantic transforms",
+        )
+    raw = await brain.complete(_EXTRACTION_PROMPT.format(content=payload.value))
+    return Payload(
+        type=DataType.STRUCTURED_JSON, value=_parse_json_object(raw), metadata=payload.metadata
+    )
+
+
+_TRANSFORMS: dict[tuple[DataType, DataType], Transform] = {
+    (DataType.CODE, DataType.TEXT): _code_to_text,
+    (DataType.STRUCTURED_JSON, DataType.TEXT): _json_to_text,
+    (DataType.DOCUMENT, DataType.TEXT): _passthrough_to_text,
+    (DataType.STREAM, DataType.TEXT): _stream_to_text,
+    (DataType.TEXT, DataType.CODE): _text_to_code,
+    (DataType.TEXT, DataType.STRUCTURED_JSON): _text_to_json,
+}
+
+
+def register_transform(source: DataType, target: DataType, transform: Transform) -> None:
+    """Register a custom transform (extension point)."""
+    _TRANSFORMS[(source, target)] = transform
+
+
+def get_transform(source: DataType, target: DataType) -> Transform | None:
+    return _TRANSFORMS.get((source, target))