inquirycraft 0.6.0__py3-none-any.whl

inquirycraft/__init__.py

@@ -0,0 +1,76 @@
+"""InquiryCraft's lightweight, domain-independent agent runtime.
+
+Every public symbol is resolved lazily. Importing the package does not initialize
+the runtime, CLI, or provider adapters.
+"""
+
+from importlib import import_module
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any
+
+try:
+    __version__ = version("inquirycraft")
+except PackageNotFoundError:  # source checkout without an installed distribution
+    __version__ = "0+unknown"
+
+_EXPORTS = {
+    "AgentHooks": ("inquirycraft.runtime", "AgentHooks"),
+    "AgentRuntime": ("inquirycraft.runtime", "AgentRuntime"),
+    "BaseTool": ("inquirycraft.tools", "BaseTool"),
+    "CompletionRequest": ("inquirycraft.llm", "CompletionRequest"),
+    "CompletionResult": ("inquirycraft.llm", "CompletionResult"),
+    "CompositeEventSink": ("inquirycraft.events", "CompositeEventSink"),
+    "Conversation": ("inquirycraft.memory", "Conversation"),
+    "EventSink": ("inquirycraft.events", "EventSink"),
+    "JsonlEventSink": ("inquirycraft.events", "JsonlEventSink"),
+    "LLMClient": ("inquirycraft.llm", "LLMClient"),
+    "Message": ("inquirycraft.memory", "Message"),
+    "RecordingLLMClient": ("inquirycraft.events", "RecordingLLMClient"),
+    "ReplayLLMClient": ("inquirycraft.events", "ReplayLLMClient"),
+    "ResumeState": ("inquirycraft.runtime", "ResumeState"),
+    "RuntimeContext": ("inquirycraft.runtime", "RuntimeContext"),
+    "RuntimeEvent": ("inquirycraft.events", "RuntimeEvent"),
+    "RuntimeOptions": ("inquirycraft.runtime", "RuntimeOptions"),
+    "ToolCollection": ("inquirycraft.tools", "ToolCollection"),
+    "ToolContext": ("inquirycraft.tools", "ToolContext"),
+    "ToolResult": ("inquirycraft.tools", "ToolResult"),
+    "Usage": ("inquirycraft.llm", "Usage"),
+}
+
+__all__ = [
+    "__version__",
+    "AgentHooks",
+    "AgentRuntime",
+    "BaseTool",
+    "CompletionRequest",
+    "CompletionResult",
+    "CompositeEventSink",
+    "Conversation",
+    "EventSink",
+    "JsonlEventSink",
+    "LLMClient",
+    "Message",
+    "RecordingLLMClient",
+    "ReplayLLMClient",
+    "ResumeState",
+    "RuntimeContext",
+    "RuntimeEvent",
+    "RuntimeOptions",
+    "ToolCollection",
+    "ToolContext",
+    "ToolResult",
+    "Usage",
+]
+
+
+def __getattr__(name: str) -> Any:
+    if name not in _EXPORTS:
+        raise AttributeError(name)
+    module_name, attribute = _EXPORTS[name]
+    value = getattr(import_module(module_name), attribute)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(__all__))

inquirycraft/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

inquirycraft/adapters.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Mapping
+from typing import Any
+
+from inquirycraft.llm import CompletionRequest, CompletionResult, StreamChunk, Usage
+from inquirycraft.memory import Message
+from inquirycraft.tools import BaseTool, ToolContext, ToolResult
+
+
+def legacy_message_to_message(value: Any) -> Message:
+    """Convert a legacy Message or OpenAI-style dict without importing its package."""
+    if isinstance(value, Mapping):
+        row = dict(value)
+    elif hasattr(value, "to_dict"):
+        row = value.to_dict()
+    elif hasattr(value, "model_dump"):
+        row = value.model_dump(exclude_none=True)
+    else:
+        raise TypeError(f"Unsupported legacy message: {type(value)!r}")
+    return Message.from_dict(row)
+
+
+class LegacyAskLLMAdapter:
+    """Expose an existing ask()/ask_tool()-compatible client as ``LLMClient``.
+
+    This adapter lets hosts adopt the runtime contract while retaining an existing
+    provider implementation, retry policy, and request parameters.
+    """
+
+    def __init__(self, legacy_llm: Any) -> None:
+        self.legacy_llm = legacy_llm
+
+    @staticmethod
+    def _usage(legacy_llm: Any) -> Usage:
+        return Usage(
+            input_tokens=int(getattr(legacy_llm, "_last_call_input_tokens", 0) or 0),
+            output_tokens=int(getattr(legacy_llm, "_last_call_output_tokens", 0) or 0),
+            cached_input_tokens=int(getattr(legacy_llm, "_last_call_input_cached_tokens", 0) or 0),
+        )
+
+    async def complete(self, request: CompletionRequest) -> CompletionResult:
+        messages = [dict(message) for message in request.messages]
+        if request.tools:
+            response = await self.legacy_llm.ask_tool(
+                messages=messages,
+                system_msgs=None,
+                timeout=int(request.timeout or 300),
+                tools=[dict(tool) for tool in request.tools],
+                tool_choice=request.tool_choice,
+                temperature=request.temperature,
+            )
+            raw_calls = getattr(response, "tool_calls", None) or ()
+            tool_calls = tuple(
+                call.model_dump(exclude_none=True) if hasattr(call, "model_dump") else dict(call)
+                for call in raw_calls
+            )
+            return CompletionResult(
+                content=str(getattr(response, "content", "") or ""),
+                reasoning_content=str(getattr(response, "reasoning_content", "") or ""),
+                tool_calls=tool_calls,
+                finish_reason=str(getattr(self.legacy_llm, "_last_finish_reason", "unknown")),
+                usage=self._usage(self.legacy_llm),
+                raw=response,
+            )
+
+        content = await self.legacy_llm.ask(
+            messages=messages,
+            system_msgs=None,
+            stream=False,
+            temperature=request.temperature,
+            timeout=request.timeout,
+        )
+        return CompletionResult(
+            content=str(content or ""),
+            finish_reason=str(getattr(self.legacy_llm, "_last_finish_reason", "unknown")),
+            usage=self._usage(self.legacy_llm),
+            raw=content,
+        )
+
+    async def stream(self, request: CompletionRequest) -> AsyncIterator[StreamChunk]:
+        result = await self.complete(request)
+        yield StreamChunk(
+            content=result.content,
+            reasoning_content=result.reasoning_content,
+            finish_reason=result.finish_reason,
+            usage=result.usage,
+        )
+
+    async def aclose(self) -> None:
+        instances = getattr(self.legacy_llm, "_instances", None)
+        targets = instances if isinstance(instances, list) else [self.legacy_llm]
+        for target in targets:
+            client = getattr(target, "client", None)
+            close = getattr(client, "close", None)
+            if close is not None:
+                result = close()
+                if hasattr(result, "__await__"):
+                    await result
+
+
+class LegacyToolAdapter(BaseTool):
+    """Expose a legacy BaseTool through the context-aware contract."""
+
+    def __init__(self, legacy_tool: Any) -> None:
+        self.legacy_tool = legacy_tool
+        self.name = str(legacy_tool.name)
+        self.description = str(legacy_tool.description)
+        self.input_schema = dict(getattr(legacy_tool, "parameters", None) or {})
+
+    async def execute(self, arguments: Mapping[str, Any], context: ToolContext) -> ToolResult:
+        context.cancellation.raise_if_cancelled()
+        raw = await self.legacy_tool.execute(**dict(arguments))
+        if hasattr(raw, "output") or hasattr(raw, "error"):
+            output = getattr(raw, "output", "")
+            error = getattr(raw, "error", None)
+            system = getattr(raw, "system", None)
+            metadata = {"legacy_system": system} if system is not None else {}
+            return ToolResult(
+                output=str(output or ""),
+                error=str(error) if error else None,
+                metadata=metadata,
+            )
+        return ToolResult(output=str(raw or ""))
+
+
+__all__ = ["LegacyAskLLMAdapter", "LegacyToolAdapter", "legacy_message_to_message"]

inquirycraft/agent/__init__.py

@@ -0,0 +1,5 @@
+"""Canonical agent model exports."""
+
+from .base import BaseAgent, MemoryRetrievalCompatibilityMixin
+
+__all__ = ["BaseAgent", "MemoryRetrievalCompatibilityMixin"]

inquirycraft/agent/base.py

@@ -0,0 +1,194 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from abc import ABC
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from inquirycraft.memory import Memory
+from inquirycraft.memory.message import ROLE_TYPE, Message, Role
+from inquirycraft.runtime import AgentState
+from inquirycraft.tools import (
+    TOOL_CHOICE_TYPE,
+    ToolCall,
+    ToolChoice,
+    ToolCollection,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class MemoryRetrievalCompatibilityMixin(ABC):
+    """Stable fields for the removed vector-memory integration."""
+
+    vector_db_path: str = Field(default="./vector_db", description="Vector database path")
+    model_name: str = Field(
+        default="./intfloat/multilingual-e5-large-instruct",
+        description="Encoding model path",
+    )
+    use_memory_retrieval: bool = Field(default=False)
+    retrieval_top_k: int = Field(default=3)
+    min_common_length: int = Field(default=100)
+    save_to_vector_db: bool = Field(default=False)
+    fusion_retrieval: bool = Field(default=False)
+    collection_name: str = Field(default="conversations")
+
+    def _initialize_retrieval_components(self) -> None:
+        if self.use_memory_retrieval or self.save_to_vector_db:
+            raise RuntimeError("InquiryCraft vector memory retrieval has been removed")
+
+    async def _retrieve_similar_memories(
+        self,
+        query: str,
+        retrieval_filter: dict[str, Any] | None = None,
+    ) -> list[dict[str, Any]]:
+        _ = query, retrieval_filter
+        self._initialize_retrieval_components()
+        return []
+
+    async def _save_to_vector_db(
+        self,
+        text: str,
+        metadata: dict[str, Any],
+        doc_id: str | None = None,
+    ) -> None:
+        _ = text, metadata, doc_id
+        self._initialize_retrieval_components()
+
+    def get_vector_db_stats(self) -> dict[str, Any]:
+        return {"enabled": False, "removed": True}
+
+
+class BaseAgent(BaseModel, MemoryRetrievalCompatibilityMixin, ABC):
+    """Compatibility model for hosts adopting :class:`AgentRuntime` incrementally.
+
+    It preserves the established Pydantic fields and one-step behavior. New agents
+    should use :class:`inquirycraft.runtime.AgentRuntime` directly.
+    """
+
+    name: str | None = Field(None, description="Unique name of the agent")
+    description: str | None = Field(None, description="Optional agent description")
+    systemPrompt: str | list[dict] | None = Field(
+        None,
+        description="System-level instruction prompt",
+    )
+    llm: Any | None = Field(None, description="Language model instance")
+    memory: Memory = Field(default_factory=Memory, description="Agent's memory store")
+    state: AgentState = Field(default=AgentState.IDLE, description="Current agent state")
+    availableTools: ToolCollection | None = Field(None, description="List of available tools")
+    toolChoices: TOOL_CHOICE_TYPE | None = Field(
+        ToolChoice.AUTO,
+        description="Tool choice strategy",
+    )
+    toolCalls: list[ToolCall] | None = Field(None, description="List of tool calls")
+    ToolConfig: dict | None = Field(None, description="Other tool configuration")
+    exec_mode: str | None = Field(None, description="execution mode:single turn or multiturn")
+
+    model_config = ConfigDict(arbitrary_types_allowed=True, extra="allow")
+
+    @model_validator(mode="after")
+    def initializeAgent(self) -> "BaseAgent":
+        if self.llm is None:
+            raise ValueError("llm is none!")
+        if not isinstance(self.memory, Memory):
+            self.memory = Memory()
+        return self
+
+    async def run(self, request: str | list[dict] | None = None) -> str:
+        if self.state != AgentState.IDLE:
+            raise RuntimeError(f"Cannot run agent from state: {self.state}")
+        if request:
+            self.updateMemory(Role.USER, request)
+        result = await self.step()
+        if self.llm:
+            self.llm.chunk_queue = asyncio.Queue()
+        return result
+
+    async def step(self) -> str:
+        response = await self.llm.ask(
+            messages=self.memory.messages,
+            system_msgs=[Message.system_message(self.systemPrompt)],
+        )
+        self.updateMemory(Role.ASSISTANT, response)
+        return response
+
+    def updateMemory(
+        self,
+        role: ROLE_TYPE,
+        content: str | Message,
+        extra_info: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        if isinstance(content, Message):
+            message = content
+        else:
+            factories = {
+                Role.USER: Message.user_message,
+                Role.SYSTEM: Message.system_message,
+                Role.ASSISTANT: Message.assistant_message,
+                Role.TOOL: lambda value, **kw: Message.tool_message(value, **kw),
+            }
+            if role not in factories:
+                raise ValueError(f"Unsupported message role: {role}")
+            factory = factories[role]
+            message = factory(content, **kwargs) if role == Role.TOOL else factory(content)
+        if extra_info:
+            self.memory.add_message(message, extra_info=extra_info)
+        else:
+            self.memory.add_message(message)
+
+    async def executeTool(self, command: ToolCall) -> str:
+        if not command or not command.function or not command.function.name:
+            return "Error: Invalid command format"
+        name = command.function.name
+        if self.availableTools is None or name not in self.availableTools.tool_map:
+            return f"Error: Unknown tool '{name}'"
+        try:
+            arguments = json.loads(command.function.arguments or "{}")
+            arguments["config"] = self.ToolConfig
+            logger.info("Activating tool: %r", name)
+            result = await self.availableTools.execute(name=name, tool_input=arguments)
+            observation = (
+                f"Observed output of cmd `{name}` executed:\n{result}"
+                if result
+                else f"Cmd `{name}` completed with no output"
+            )
+            await self._handleSpecialTool(name=name, result=result)
+            return observation
+        except json.JSONDecodeError:
+            logger.error("Invalid JSON arguments for %r: %s", name, command.function.arguments)
+            return f"Error: Error parsing arguments for {name}: Invalid JSON format"
+        except Exception as exc:
+            error = f"Tool '{name}' encountered a problem: {exc}"
+            logger.error(error)
+            return f"Error: {error}"
+
+    async def _handleSpecialTool(self, name: str, result: Any, **kwargs: Any) -> None:
+        if self._isSpecialTool(name) and self._shouldFinishExecution(
+            name=name,
+            result=result,
+            **kwargs,
+        ):
+            self.state = AgentState.FINISHED
+
+    @staticmethod
+    def _shouldFinishExecution(**kwargs: Any) -> bool:
+        return True
+
+    def _isSpecialTool(self, name: str) -> bool:
+        names = getattr(self, "special_tool_names", ())
+        return name.lower() in [value.lower() for value in names]
+
+    @property
+    def messages(self) -> list[Message]:
+        return self.memory.messages
+
+    @messages.setter
+    def messages(self, value: list[Message]) -> None:
+        self.memory.messages = value
+
+
+__all__ = ["BaseAgent", "MemoryRetrievalCompatibilityMixin"]

inquirycraft/cli/__init__.py

@@ -0,0 +1,13 @@
+from .app import create_cli, main
+from .contracts import CliExtension, CommandContext, CommandRegistry, RuntimeFactory
+from .factory import DefaultRuntimeFactory
+
+__all__ = [
+    "CliExtension",
+    "CommandContext",
+    "CommandRegistry",
+    "DefaultRuntimeFactory",
+    "RuntimeFactory",
+    "create_cli",
+    "main",
+]

inquirycraft/cli/app.py

@@ -0,0 +1,231 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from collections.abc import Callable, Iterable, Sequence
+from pathlib import Path
+from typing import Any
+
+import click
+
+from inquirycraft.events import JsonlEventSink, NullEventSink, load_events
+from inquirycraft.runtime import RuntimeOptions
+from inquirycraft.tools import default_tools
+
+from .contracts import CliExtension, CommandRegistry, RuntimeFactory
+from .factory import DefaultRuntimeFactory
+
+RuntimeOptionsDecorator = Callable[[Callable[..., Any]], Callable[..., Any]]
+
+
+def _runtime_options(
+    *,
+    model_envvar: str | Sequence[str],
+    base_url_envvar: str | Sequence[str],
+    api_key_env_default: str,
+) -> RuntimeOptionsDecorator:
+    def decorate(function):
+        options = [
+            click.option("--model", envvar=model_envvar, required=True, help="Model name."),
+            click.option("--base-url", envvar=base_url_envvar, default=None),
+            click.option(
+                "--api-key-env",
+                default=api_key_env_default,
+                show_default=True,
+                help="Environment variable containing the API key.",
+            ),
+            click.option(
+                "--workspace",
+                type=click.Path(path_type=Path, file_okay=False),
+                default=Path("."),
+                show_default=True,
+            ),
+            click.option("--system-prompt", default="You are a helpful agent.", show_default=True),
+            click.option("--max-turns", type=click.IntRange(1), default=20, show_default=True),
+            click.option("--max-tokens", type=click.IntRange(1), default=None),
+            click.option(
+                "--timeout",
+                type=click.FloatRange(min=0.1),
+                default=300.0,
+                show_default=True,
+            ),
+            click.option(
+                "--event-log",
+                type=click.Path(path_type=Path, dir_okay=False),
+                default=None,
+            ),
+            click.option(
+                "--session-log",
+                type=click.Path(path_type=Path, dir_okay=False),
+                default=None,
+                help="Append conversation records to JSONL; existing records are resumed.",
+            ),
+        ]
+        for option in reversed(options):
+            function = option(function)
+        return function
+
+    return decorate
+
+
+def _build_runtime(
+    factory: RuntimeFactory,
+    *,
+    model: str,
+    base_url: str | None,
+    api_key_env: str,
+    workspace: Path,
+    system_prompt: str,
+    max_turns: int,
+    max_tokens: int | None,
+    timeout: float,
+    event_log: Path | None,
+    session_log: Path | None,
+):
+    api_key = os.environ.get(api_key_env, "").strip()
+    if not api_key:
+        raise click.ClickException(f"API key environment variable {api_key_env!r} is empty")
+    sink = JsonlEventSink(event_log) if event_log else NullEventSink()
+    options = RuntimeOptions(
+        model=model,
+        workspace=workspace,
+        system_prompt=system_prompt,
+        max_turns=max_turns,
+        max_tokens=max_tokens,
+        timeout=timeout,
+        session_log=session_log,
+    )
+    return factory.create_runtime(
+        options,
+        api_key=api_key,
+        base_url=base_url,
+        event_sink=sink,
+    )
+
+
+def _register_run_command(
+    app: click.Group,
+    factory: RuntimeFactory,
+    options: RuntimeOptionsDecorator,
+) -> None:
+    @app.command("run")
+    @click.argument("task")
+    @options
+    def run_command(task: str, **kwargs) -> None:
+        """Run one generic agent task."""
+        runtime = _build_runtime(factory, **kwargs)
+
+        async def execute() -> None:
+            try:
+                result = await runtime.run(task)
+                click.echo(result)
+            finally:
+                await runtime.aclose()
+
+        asyncio.run(execute())
+
+
+def _register_repl_command(
+    app: click.Group,
+    factory: RuntimeFactory,
+    options: RuntimeOptionsDecorator,
+) -> None:
+    @app.command("repl")
+    @options
+    def repl_command(**kwargs) -> None:
+        """Start a generic persistent agent session."""
+        runtime = _build_runtime(factory, **kwargs)
+
+        async def execute() -> None:
+            try:
+                while True:
+                    line = (await asyncio.to_thread(input, "inquirycraft> ")).strip()
+                    if line.lower() in {"exit", "quit", "q"}:
+                        break
+                    if line:
+                        click.echo(await runtime.run(line))
+            except (EOFError, KeyboardInterrupt):
+                pass
+            finally:
+                await runtime.aclose()
+
+        asyncio.run(execute())
+
+
+def _register_tool_commands(app: click.Group) -> None:
+    @app.group("tools")
+    def tools_group() -> None:
+        """Inspect built-in tools without initializing an LLM."""
+
+    @tools_group.command("list")
+    @click.option("--json-output", "json_output", is_flag=True)
+    def tools_list(json_output: bool) -> None:
+        tools = default_tools()
+        if json_output:
+            click.echo(json.dumps({"schema_version": "1.0", "tools": tools.names()}, indent=2))
+        else:
+            for tool_name in tools.names():
+                click.echo(tool_name)
+
+    @tools_group.command("schema")
+    @click.argument("name", required=False)
+    def tools_schema(name: str | None) -> None:
+        tools = default_tools()
+        schemas = tools.schemas()
+        if name:
+            schemas = tuple(row for row in schemas if row["function"]["name"] == name)
+            if not schemas:
+                raise click.ClickException(f"Unknown tool: {name}")
+        click.echo(json.dumps({"schema_version": "1.0", "tools": schemas}, indent=2))
+
+
+def _register_event_commands(app: click.Group) -> None:
+    @app.group("events")
+    def events_group() -> None:
+        """Inspect InquiryCraft runtime event JSONL."""
+
+    @events_group.command("show")
+    @click.argument("path", type=click.Path(path_type=Path, exists=True, dir_okay=False))
+    @click.option("--type", "event_type", default=None)
+    @click.option("--limit", type=click.IntRange(1), default=None)
+    def events_show(path: Path, event_type: str | None, limit: int | None) -> None:
+        events = load_events(path, event_type=event_type)
+        if limit is not None:
+            events = events[-limit:]
+        for event in events:
+            click.echo(json.dumps(event.to_dict(), ensure_ascii=False, sort_keys=True))
+
+
+def create_cli(
+    *,
+    name: str = "inquirycraft",
+    runtime_factory: RuntimeFactory | None = None,
+    extensions: Iterable[CliExtension] = (),
+    model_envvar: str | Sequence[str] = "INQUIRYCRAFT_MODEL",
+    base_url_envvar: str | Sequence[str] = "INQUIRYCRAFT_BASE_URL",
+    api_key_env_default: str = "INQUIRYCRAFT_API_KEY",
+) -> click.Group:
+    factory = runtime_factory or DefaultRuntimeFactory()
+
+    @click.group(name=name)
+    def app() -> None:
+        """Run and inspect lightweight InquiryCraft agents."""
+
+    options = _runtime_options(
+        model_envvar=model_envvar,
+        base_url_envvar=base_url_envvar,
+        api_key_env_default=api_key_env_default,
+    )
+    _register_run_command(app, factory, options)
+    _register_repl_command(app, factory, options)
+    _register_tool_commands(app)
+    _register_event_commands(app)
+
+    registry = CommandRegistry(app)
+    for extension in extensions:
+        extension.register(registry)
+    return app
+
+
+main = create_cli()