Add completion method to Promptic for direct LLM interactions (#38)

- Implement new `completion()` method to provide direct access to LLM responses
- Add warning when using completion with state/memory enabled
- Update README.md with documentation and example for new method
- Add comprehensive test coverage for the new completion method
- Bump version to 5.3.0 to reflect the new feature

Author: knowsuchagency

README.md

@@ -258,14 +258,12 @@ print(greet("John"))
 
 ```
 
-
 ### Observability
 
 Promptic integrates with [Weave](https://wandb.ai) to trace function calls and LLM interactions.
 
 <img width="981" alt="Screenshot 2025-02-07 at 6 02 25 PM" src="https://github.com/user-attachments/assets/3ccf4602-3557-455a-838f-7e4b8c2ec21a" />
 
-
 ```py
 # examples/weave_integration.py
 
@@ -303,8 +301,6 @@ print("".join(write_poem("artificial intelligence")))
 
 ```
 
-
-
 ### Error Handling and Dry Runs
 
 Dry runs allow you to see which tools will be called and their arguments without invoking the decorated tool functions. You can also enable debug mode for more detailed logging.
@@ -614,6 +610,31 @@ Base class for managing conversation memory and state. Can be extended to implem
 - `get_messages(prompt: str = None, limit: int = None) -> List[dict]`: Retrieve conversation history, optionally limited to the most recent messages and filtered by a prompt.
 - `clear()`: Clear all stored messages.
 
+### `Promptic`
+
+The main class for creating LLM-powered functions and managing conversations.
+
+#### Methods
+
+- `message(message: str, **kwargs)`: Send a message directly to the LLM and get a response. Useful for follow-up questions or direct interactions.
+- `completion(messages: list[dict], **kwargs)`: Send a list of messages directly to the LLM and get the raw completion response. Useful for more control over the conversation flow.
+
+  ```python
+  from promptic import Promptic
+
+  p = Promptic(model="gpt-4o-mini")
+  messages = [
+      {"role": "user", "content": "What is the capital of France?"},
+      {"role": "assistant", "content": "The capital of France is Paris."},
+      {"role": "user", "content": "What is its population?"}
+  ]
+  response = p.completion(messages)
+  print(response.choices[0].message.content)
+  ```
+
+- `tool(fn)`: Register a function as a tool that can be called by the LLM.
+- `clear()`: Clear all stored messages from memory. Raises ValueError if memory/state is not enabled.
+
 #### Example
 
 ```py

promptic.py

@@ -3,21 +3,21 @@
 
 warnings.filterwarnings("ignore", message="Valid config keys have changed in V2:*")
 
+import base64
 import inspect
 import json
 import logging
 import re
-import base64
 from functools import wraps
 from textwrap import dedent
-from typing import Callable, Dict, Any, List, Optional, Union
+from typing import Any, Callable, Dict, List, Optional, Union
 
 import litellm
 from jsonschema import validate as validate_json_schema
-from pydantic import BaseModel
 from litellm import completion as litellm_completion
+from pydantic import BaseModel
 
-__version__ = "5.2.1"
+__version__ = "5.3.0"
 
 SystemPrompt = Optional[Union[str, List[str], List[Dict[str, str]]]]
 
@@ -190,6 +190,32 @@ def _completion(self, messages: list[dict], **kwargs):
 
         return completion_messages, completion
 
+    def completion(self, messages: list[dict], **kwargs):
+        """Return the raw completion response from the LLM for a list of messages.
+
+        This method provides direct access to the underlying LLM completion API, allowing
+        more control over the conversation flow. Unlike the message method, it accepts
+        a list of messages and returns the raw completion response.
+
+        Args:
+            messages (list[dict]): A list of message dictionaries, each with 'role' and 'content' keys.
+                Example: [{"role": "user", "content": "Hello"}, {"role": "assistant", "content": "Hi"}]
+            **kwargs: Additional arguments passed to the completion function.
+
+        Returns:
+            The raw completion response from the LLM.
+
+        Warning:
+            If state/memory is enabled, this method will warn that it's being called directly
+            as it may lead to unexpected behavior with conversation history.
+        """
+        if self.state:
+            warnings.warn(
+                "State is enabled, but completion is being called directly. This can cause unexpected behavior.",
+                UserWarning,
+            )
+        return self._completion(messages, **kwargs)[1]
+
     def message(self, message: str, **kwargs):
         messages = [{"content": message, "role": "user"}]
         completion_messages, response = self._completion(messages, **kwargs)

tests/test_promptic.py

@@ -1563,3 +1563,63 @@ def analyze_image_feature(img: ImageBytes, feature: str):
     text_result = analyze_image_feature(image_data, "text or letters")
     assert isinstance(text_result, str)
     assert "ai" in text_result.lower() or "oc" in text_result.lower()
+
+
+@pytest.mark.parametrize("model", CHEAP_MODELS)
+@pytest.mark.parametrize(
+    "create_completion_fn", [openai_completion_fn, litellm_completion]
+)
+def test_completion_method(model, create_completion_fn):
+    """Test the direct completion method of Promptic"""
+    if create_completion_fn == openai_completion_fn and not model.startswith("gpt"):
+        pytest.skip("Non-GPT models are not supported with OpenAI client")
+
+    p = Promptic(
+        model=model,
+        temperature=0,
+        timeout=5,
+        create_completion_fn=create_completion_fn,
+    )
+
+    # Test basic completion with a single message
+    messages = [{"role": "user", "content": "What is the capital of France?"}]
+    response = p.completion(messages)
+    assert "Paris" in response.choices[0].message.content
+
+    # Test completion with multiple messages
+    messages = [
+        {"role": "user", "content": "What is the capital of France?"},
+        {"role": "assistant", "content": "The capital of France is Paris."},
+        {"role": "user", "content": "What is its population?"},
+    ]
+    response = p.completion(messages)
+    assert any(
+        word in response.choices[0].message.content.lower()
+        for word in ["million", "inhabitants", "people"]
+    )
+
+    # Test completion with system message
+    p_with_system = Promptic(
+        model=model,
+        temperature=0,
+        timeout=5,
+        system="You are a geography expert",
+        create_completion_fn=create_completion_fn,
+    )
+    messages = [{"role": "user", "content": "What is the capital of France?"}]
+    response = p_with_system.completion(messages)
+    assert "Paris" in response.choices[0].message.content
+
+    # Test warning when using with state enabled
+    p_with_state = Promptic(
+        model=model,
+        temperature=0,
+        timeout=5,
+        memory=True,
+        create_completion_fn=create_completion_fn,
+    )
+    with pytest.warns(
+        UserWarning, match="State is enabled, but completion is being called directly"
+    ):
+        response = p_with_state.completion(messages)
+        assert "Paris" in response.choices[0].message.content