multi-forge 0.2.0__py3-none-any.whl

forge/core/data/system_prompt_addendums/openai.md

@@ -0,0 +1,328 @@
+# Tool Parameter Guidance
+
+You are working inside Claude Code, which provides tools with specific parameter contracts.
+
+Follow these rules exactly. Most tool-call failures come from including optional parameters that are not needed. Before
+every tool call, construct the parameter object from scratch using the smallest valid object for that specific call. Do
+not reuse a previous failed tool-call object.
+
+## Universal tool-call rule
+
+For every tool call:
+
+1. Start with only the required parameters.
+2. Add an optional parameter only if this exact call needs it.
+3. Never include optional parameters with placeholder values.
+4. Never pass `""`, `null`, `[]`, or `{}` just to satisfy a schema.
+5. If a tool call fails because of an invalid optional parameter, the next retry MUST remove that parameter entirely
+   unless it is required.
+6. Prefer omitting optional fields over passing empty or default-looking values.
+7. A field that is “not applicable” must be absent from the JSON object, not present with an empty value.
+
+Bad:
+
+```json
+{"file_path":"/workspace/README.md","pages":""}
+```
+
+Good:
+
+```json
+{"file_path":"/workspace/README.md"}
+```
+
+## Read
+
+Default call shape for ordinary files:
+
+```json
+{"file_path":"/absolute/path/to/file"}
+```
+
+Use this default for normal-sized non-PDF files, including:
+
+- .md
+- .txt
+- source code files
+- .json
+- .yaml / .yml
+- config files
+- notebooks, unless notebook-specific handling is explicitly needed
+
+Do not add offset, limit, or pages unless this exact read requires them.
+
+### `pages`
+
+`pages` is only for PDF files.
+
+If `file_path` does not end in `.pdf`, the `pages` key is forbidden.
+
+For non-PDF files:
+
+- Do not include `pages`.
+- Do not include `"pages": ""`.
+- Do not include `"pages": null`.
+- Do not include `"pages": "1"`.
+- Do not include `pages` together with `offset`/`limit`.
+- The correct non-PDF retry after any `pages` error is usually only:
+
+```json
+{"file_path":"/absolute/path/to/file"}
+```
+
+Correct non-PDF examples:
+
+```json
+{"file_path":"/workspace/README.md"}
+```
+
+```json
+{"file_path":"/workspace/src/app.ts"}
+```
+
+```json
+{"file_path":"/workspace/package.json"}
+```
+
+Correct PDF examples:
+
+```json
+{"file_path":"/workspace/spec.pdf","pages":"1-5"}
+```
+
+```json
+{"file_path":"/workspace/spec.pdf","pages":"3"}
+```
+
+Incorrect:
+
+```json
+{"file_path":"/workspace/README.md","pages":""}
+```
+
+```json
+{"file_path":"/workspace/README.md","pages":"1"}
+```
+
+```json
+{"file_path":"/workspace/README.md","offset":1,"limit":2000,"pages":""}
+```
+
+```json
+{"file_path":"/workspace/src/app.ts","pages":null}
+```
+
+### `offset` and `limit`
+
+`offset` and `limit` are optional.
+
+For normal-sized files, omit both and let the tool return the full content.
+
+Default:
+
+```json
+{"file_path":"/absolute/path/to/file"}
+```
+
+Only include `offset` and/or `limit` when:
+
+- the file is known to be large,
+- you need a specific section,
+- a previous successful read showed that the relevant content is outside the default range.
+
+Correct large-file section example:
+
+```json
+{"file_path":"/absolute/path/to/file","offset":2000,"limit":200}
+```
+
+Incorrect for ordinary files:
+
+```json
+{"file_path":"/workspace/README.md","offset":1,"limit":2000}
+```
+
+The above is not invalid, but it is unnecessary. Prefer:
+
+```json
+{"file_path":"/workspace/README.md"}
+```
+
+### Read retry rule
+
+If a Read call fails because of an invalid optional parameter, retry with the smallest valid object.
+
+For a non-PDF file, that means:
+
+```json
+{"file_path":"/absolute/path/to/file"}
+```
+
+Do not use Bash as a workaround for a failed Read call until you have retried once with the minimal valid Read object.
+
+## Edit
+
+Use Edit for modifying existing files whenever possible.
+
+`old_string` must be an exact substring of the current file content.
+
+Rules:
+
+- Copy `old_string` character-for-character from the file content.
+- Preserve exact whitespace and indentation.
+- Never include line number prefixes from Read.
+- The line number prefix shown by Read is display-only and is not part of the file.
+- If `old_string` is not unique, include more surrounding context.
+- Do not make broad replacements when a narrow exact replacement is possible.
+- Prefer Edit over Write for existing files.
+
+Correct:
+
+```json
+{
+  "file_path":"/workspace/src/app.py",
+  "old_string":"def greet(name):\n    return f\"Hello {name}\"",
+  "new_string":"def greet(name):\n    return f\"Hello, {name}!\""
+}
+```
+
+Incorrect because it includes a line number prefix:
+
+```json
+{
+  "file_path":"/workspace/src/app.py",
+  "old_string":"12\tdef greet(name):\n13\t    return f\"Hello {name}\"",
+  "new_string":"def greet(name):\n    return f\"Hello, {name}!\""
+}
+```
+
+### Edit retry rule
+
+If Edit fails because `old_string` is not found:
+
+1. Re-read the relevant file or section.
+2. Copy the exact current text.
+3. Retry with a more precise `old_string`.
+
+If Edit fails because `old_string` is not unique:
+
+1. Include more surrounding lines in `old_string`.
+2. Do not use `replace_all` unless every occurrence should actually change.
+
+## Write
+
+Use Write only for:
+
+- creating a new file,
+- intentionally replacing an entire existing file after reading it first.
+
+Rules:
+
+- Prefer Edit for modifying existing files.
+- Do not use Write to make a small change to an existing file.
+- If writing an existing file, read it first.
+- Do not create documentation files unless explicitly requested by the user.
+- Do not use emojis in files unless explicitly requested by the user.
+
+Correct use for a new file:
+
+```json
+{
+  "file_path":"/workspace/src/new_module.py",
+  "content":"def main():\n    return None\n"
+}
+```
+
+Incorrect use for a small edit to an existing file:
+
+```json
+{
+  "file_path":"/workspace/src/app.py",
+  "content":"<entire rewritten file just to change one line>"
+}
+```
+
+Use Edit instead.
+
+## Bash
+
+Prefer dedicated tools over Bash when a dedicated tool fits.
+
+Use:
+
+- Read instead of `cat`, `head`, `tail`, or `sed -n`.
+- Edit instead of `sed -i`, `perl -pi`, or shell redirection.
+- Write instead of `cat > file` or heredoc file creation.
+
+Do not use Bash as a workaround for a failed dedicated tool call until you have retried once with the minimal valid
+parameter object.
+
+Example:
+
+If this fails:
+
+```json
+{"file_path":"/workspace/README.md","pages":""}
+```
+
+Do not immediately use Bash. Retry:
+
+```json
+{"file_path":"/workspace/README.md"}
+```
+
+Only use Bash if the dedicated tool still cannot accomplish the task.
+
+## Common valid tool-call shapes
+
+### Read an ordinary file
+
+```json
+{"file_path":"/workspace/README.md"}
+```
+
+### Read a section of a large ordinary file
+
+```json
+{"file_path":"/workspace/large.log","offset":1000,"limit":200}
+```
+
+### Read a PDF page range
+
+```json
+{"file_path":"/workspace/spec.pdf","pages":"1-5"}
+```
+
+### Edit an existing file
+
+```json
+{
+  "file_path":"/workspace/src/app.py",
+  "old_string":"old exact text",
+  "new_string":"new exact text"
+}
+```
+
+### Create a new file
+
+```json
+{
+  "file_path":"/workspace/src/new_file.py",
+  "content":"file contents\n"
+}
+```
+
+## Final preflight checklist
+
+Before sending any tool call, ask:
+
+1. Are all required fields present?
+2. Did I omit every optional field that is not needed?
+3. Did I avoid empty-string, null, empty-list, and empty-object placeholders?
+4. If this is Read, is `pages` absent unless the file is a PDF?
+5. If this is Read for a normal file, am I using only `file_path`?
+6. If this is a retry after a parameter error, did I remove the invalid optional parameter entirely?
+7. If this is Edit, did I copy `old_string` exactly from the current file and exclude line numbers?
+8. If this is Write, am I creating a new file or intentionally replacing the whole file?
+
+When in doubt, use the smallest valid object.

forge/core/llm/__init__.py

@@ -0,0 +1,231 @@
+"""Shared LLM client abstraction for Forge components.
+
+This module provides a unified, async-first interface for calling LLMs
+across different providers (LiteLLM, Anthropic).
+
+Usage:
+    # Async usage (Proxy)
+    from forge.core.llm import get_client, Message
+
+    client = get_client("openai/gpt-5.2")
+    response = await client.complete([Message(role="user", content="Hello")])
+
+    # Streaming
+    async for event in client.stream(messages):
+        if event.type == "text_delta":
+            print(event.text, end="")
+
+    # Sync usage (Guard)
+    from forge.core.llm import get_client, SyncAdapter
+
+    client = SyncAdapter(get_client("openai/gpt-5.2"))
+    response = client.ask("Analyze this code...")
+"""
+
+import asyncio
+from typing import Any
+
+from .clients.litellm import LiteLLMClient
+from .credentials import CredentialManager
+from .detection import ProviderType, detect_provider, is_implemented
+from .errors import (
+    AuthenticationError,
+    LLMError,
+    NoApiKeyError,
+    ProviderError,
+    UnsupportedParamError,
+)
+from .protocols import LLMClient
+from .types import (
+    CompletionResponse,
+    InjectionPoint,
+    Message,
+    ModelHyperparameters,
+    PromptCachingConfig,
+    PromptCachingPolicy,
+    StreamEvent,
+    ThinkingConfig,
+    ToolCall,
+    ToolCallDelta,
+)
+
+__all__ = [
+    # Factory
+    "get_client",
+    "SyncAdapter",
+    # Types
+    "Message",
+    "CompletionResponse",
+    "StreamEvent",
+    "ToolCall",
+    "ToolCallDelta",
+    "ModelHyperparameters",
+    "ThinkingConfig",
+    "PromptCachingConfig",
+    "PromptCachingPolicy",
+    "InjectionPoint",
+    # Protocol
+    "LLMClient",
+    # Errors
+    "LLMError",
+    "NoApiKeyError",
+    "AuthenticationError",
+    "ProviderError",
+    "UnsupportedParamError",
+    # Detection
+    "ProviderType",
+    "detect_provider",
+    # Credentials
+    "CredentialManager",
+]
+
+
+def get_client(
+    model: str,
+    *,
+    provider: ProviderType | None = None,
+    credentials: CredentialManager | None = None,
+    default_hyperparams: ModelHyperparameters | None = None,
+) -> LLMClient:
+    """Get an LLM client for the given model.
+
+    The factory is sync; credential fetching is deferred to first
+    complete()/stream() call. This allows sync code to construct
+    clients without needing an event loop.
+
+    Args:
+        model: Model identifier with provider prefix (e.g., "openai/gpt-5.2").
+        provider: Explicit provider override (detected from prefix if not provided).
+        credentials: Custom credential manager (uses default if not provided).
+        default_hyperparams: Default hyperparameters for all calls on this client.
+
+    Returns:
+        LLMClient instance for the appropriate provider.
+
+    Raises:
+        ValueError: If model ID is not prefixed (unprefixed models not supported).
+        NotImplementedError: If the detected provider is not yet implemented.
+
+    Examples:
+        >>> client = get_client("openai/gpt-5.2")
+        >>> client = get_client("vertex_ai/gemini-3.1-pro-preview")
+        >>> client = get_client("gemini/gemini-2.0-flash")  # Local LiteLLM
+    """
+    resolved_provider = provider or detect_provider(model)
+    creds_manager = credentials or CredentialManager.default()
+
+    # Check if provider is implemented
+    if not is_implemented(resolved_provider):
+        if resolved_provider == "anthropic":
+            raise NotImplementedError(
+                f"Direct Anthropic client not yet implemented. "
+                f"Use 'anthropic/{model.split('/')[-1] if '/' in model else model}' "
+                f"prefix to route via LiteLLM."
+            )
+        else:
+            raise NotImplementedError(f"Provider '{resolved_provider}' not yet implemented.")
+
+    if resolved_provider == "openrouter":
+        from .clients.openrouter import OpenRouterClient
+
+        return OpenRouterClient(
+            model=model,
+            provider=resolved_provider,
+            credentials=creds_manager,
+            default_hyperparams=default_hyperparams,
+        )
+
+    return LiteLLMClient(
+        model=model,
+        provider=resolved_provider,
+        credentials=creds_manager,
+        default_hyperparams=default_hyperparams,
+    )
+
+
+class SyncAdapter:
+    """Wraps async LLMClient for synchronous usage.
+
+    CONSTRAINT: Cannot be used inside an event loop.
+    asyncio.run() raises RuntimeError if a loop is running.
+    Use the async client directly in async contexts.
+
+    Usage:
+        client = SyncAdapter(get_client("openai/gpt-5.2"))
+        response = client.ask("Analyze this code...")
+    """
+
+    def __init__(self, client: LLMClient) -> None:
+        """Initialize sync adapter.
+
+        Args:
+            client: Async LLMClient to wrap.
+        """
+        self._client = client
+
+    @property
+    def model(self) -> str:
+        """The model this client is configured for."""
+        return self._client.model
+
+    def _check_no_running_loop(self) -> None:
+        """Ensure we're not inside an event loop.
+
+        Raises:
+            RuntimeError: If called from inside an event loop.
+        """
+        try:
+            asyncio.get_running_loop()
+            raise RuntimeError(
+                "SyncAdapter cannot be used inside an event loop. " "Use the async client directly in async contexts."
+            )
+        except RuntimeError as e:
+            # RuntimeError is raised when no loop is running - that's what we want
+            if "no running event loop" not in str(e).lower():
+                raise
+
+    def ask(
+        self,
+        prompt: str,
+        *,
+        system: str | None = None,
+        hyperparams: ModelHyperparameters | None = None,
+    ) -> str:
+        """Simple prompt-to-response interface.
+
+        Args:
+            prompt: User prompt.
+            system: Optional system prompt.
+            hyperparams: Optional hyperparameters.
+
+        Returns:
+            Response text from the model.
+        """
+        self._check_no_running_loop()
+
+        messages = [Message(role="user", content=prompt)]
+        if system:
+            messages.insert(0, Message(role="system", content=system))
+
+        response = asyncio.run(self._client.complete(messages, hyperparams=hyperparams))
+        return response.text
+
+    def complete(
+        self,
+        messages: list[Message],
+        *,
+        tools: list[dict[str, Any]] | None = None,
+        hyperparams: ModelHyperparameters | None = None,
+    ) -> CompletionResponse:
+        """Synchronous completion with full control.
+
+        Args:
+            messages: List of messages in the conversation.
+            tools: Optional list of tool definitions.
+            hyperparams: Optional hyperparameters.
+
+        Returns:
+            CompletionResponse with text, optional tool_calls, and usage.
+        """
+        self._check_no_running_loop()
+        return asyncio.run(self._client.complete(messages, tools=tools, hyperparams=hyperparams))

forge/core/llm/clients/__init__.py

@@ -0,0 +1,14 @@
+"""LLM client implementations.
+
+Currently implemented:
+- LiteLLMClient: For both remote and local LiteLLM instances
+
+Deferred (not yet implemented):
+- AnthropicClient: Direct Anthropic API
+"""
+
+from .litellm import LiteLLMClient
+from .openai_compat import ToolCallAccumulator
+from .openrouter import OpenRouterClient
+
+__all__ = ["LiteLLMClient", "OpenRouterClient", "ToolCallAccumulator"]

forge/core/llm/clients/base.py

@@ -0,0 +1,115 @@
+"""Base helpers for LLM client implementations."""
+
+import logging
+
+from ..errors import UnsupportedParamError
+from ..types import ModelHyperparameters
+
+logger = logging.getLogger(__name__)
+
+
+def merge_hyperparams(
+    defaults: ModelHyperparameters | None,
+    call_time: ModelHyperparameters | None,
+) -> ModelHyperparameters:
+    """Merge default hyperparameters with call-time overrides.
+
+    Call-time values take precedence, but only for fields explicitly set by
+    the caller. Default values on ModelHyperparameters do not override client
+    defaults (uses exclude_unset, not exclude_none).
+
+    Args:
+        defaults: Default hyperparameters (from client initialization).
+        call_time: Call-time hyperparameters (from complete/stream call).
+
+    Returns:
+        Merged hyperparameters.
+    """
+    if defaults is None and call_time is None:
+        return ModelHyperparameters()
+    if defaults is None:
+        return call_time or ModelHyperparameters()
+    if call_time is None:
+        return defaults
+
+    # Merge: only explicitly-set call_time values override defaults
+    merged_data = defaults.model_dump()
+    call_data = call_time.model_dump(exclude_unset=True)
+
+    # Special handling for nested dicts (extra)
+    if "extra" in call_data:
+        merged_extra = merged_data.get("extra", {}).copy()
+        for namespace, params in call_data["extra"].items():
+            if namespace in merged_extra:
+                merged_extra[namespace] = {**merged_extra[namespace], **params}
+            else:
+                merged_extra[namespace] = params
+        call_data["extra"] = merged_extra
+
+    merged_data.update(call_data)
+    return ModelHyperparameters(**merged_data)
+
+
+def handle_unsupported_param(
+    param: str,
+    value: object,
+    provider: str,
+    strict: bool,
+) -> None:
+    """Handle an unsupported parameter.
+
+    In strict mode, raises UnsupportedParamError.
+    Otherwise, logs a warning and continues.
+
+    Args:
+        param: Parameter name that is not supported.
+        value: The value that was provided.
+        provider: Provider that doesn't support this parameter.
+        strict: Whether to raise an error (True) or warn (False).
+
+    Raises:
+        UnsupportedParamError: If strict mode is enabled.
+    """
+    if strict:
+        raise UnsupportedParamError(param, provider)
+    else:
+        logger.warning(f"Parameter '{param}' with value '{value}' not supported by {provider}, ignoring")
+
+
+def estimate_tokens_simple(text: str) -> int:
+    """Simple token estimation (4 chars per token).
+
+    This is a conservative estimate for when provider-specific
+    tokenization is not available.
+
+    Args:
+        text: Text to estimate tokens for.
+
+    Returns:
+        Estimated token count.
+    """
+    return len(text) // 4 + 1
+
+
+def estimate_message_tokens(messages: list[dict[str, object]]) -> int:
+    """Estimate tokens for a list of messages.
+
+    Args:
+        messages: List of message dicts with 'content' field.
+
+    Returns:
+        Estimated total token count.
+    """
+    total = 0
+    for msg in messages:
+        content = msg.get("content", "")
+        if isinstance(content, str):
+            total += estimate_tokens_simple(content)
+        elif isinstance(content, list):
+            # Multimodal content - estimate text parts only
+            for part in content:
+                if isinstance(part, dict) and part.get("type") == "text":
+                    total += estimate_tokens_simple(str(part.get("text", "")))
+        # Add overhead per message
+        total += 10
+    return total