Update readme (#38)

Author: Katsiarynka

CLAUDE.md

@@ -0,0 +1,34 @@
+# Lamoom Python Project Guide
+
+## Build/Test/Lint Commands
+- Install deps: `poetry install`
+- Run all tests: `poetry run pytest --cache-clear -vv tests`
+- Run specific test: `poetry run pytest tests/path/to/test_file.py::test_function_name -v`
+- Run with coverage: `make test`
+- Format code: `make format` (runs black, isort, flake8, mypy)
+- Individual formatting:
+  - Black: `make make-black`
+  - isort: `make make-isort`
+  - Flake8: `make flake8`
+  - Autopep8: `make autopep8`
+
+## Code Style Guidelines
+- Python 3.9+ compatible code
+- Type hints required for all functions and methods
+- Classes: PascalCase with descriptive names
+- Functions/Variables: snake_case
+- Constants: UPPERCASE_WITH_UNDERSCORES
+- Imports organization with isort:
+  1. Standard library imports
+  2. Third-party imports
+  3. Local application imports
+- Error handling: Use specific exception types
+- Logging: Use the logging module with appropriate levels
+- Use dataclasses for structured data when applicable
+
+## Project Conventions
+- Use poetry for dependency management
+- Add tests for all new functionality
+- Maintain >80% test coverage (current min: 81%)
+- Follow pre-commit hooks guidelines
+- Document public APIs with docstrings

README.md

@@ -4,14 +4,50 @@
 
 Lamoom is a dynamic, all-in-one library designed for managing and optimizing prompts and making tests based on the ideal answer for large language models (LLMs) in production and R&D. It facilitates dynamic data integration, latency and cost metrics visibility, and efficient load distribution across multiple AI models.
 
-
 ## Features
 
 - **CI/CD testing**: Generates tests based on the context and ideal answer (usually written by the human).
 - **Dynamic Prompt Development**: Avoid budget exceptions with dynamic data.
 - **Multi-Model Support**: Seamlessly integrate with various LLMs like OpenAI, Anthropic, and more.
 - **Real-Time Insights**: Monitor interactions, request/response metrics in production.
 - **Prompt Testing and Evolution**: Quickly test and iterate on prompts using historical data.
+- **Smart Prompt Caching**: Efficiently cache prompts for 5 minutes to reduce latency while keeping them updated.
+- **Asynchronous Logging**: Record interactions without blocking the main execution flow.
+
+## Core Functionality
+
+### Prompt Management and Caching
+Lamoom implements an efficient prompt caching system with a 5-minute TTL (Time-To-Live):
+- **Automatic Updates**: When you call a prompt, Lamoom checks if a newer version exists on the server.
+- **Cache Invalidation**: Prompts are automatically refreshed after 5 minutes to ensure up-to-date content.
+- **Local Fallback**: If the server is unavailable, Lamoom falls back to the locally defined prompt.
+- **Version Control**: Track prompt versions between local and server instances.
+
+![Lamoom Call Flow](docs/sequence_diagrams/pngs/lamoom_call.png)
+
+### Test Generation and CI/CD Integration
+Lamoom supports two methods for test creation:
+1. **Inline Test Generation**: Add `test_data` with an ideal answer during normal LLM calls to automatically generate tests.
+2. **Direct Test Creation**: Use the `create_test()` method to explicitly create tests for specific prompts.
+
+Tests automatically compare LLM responses to ideal answers, helping maintain prompt quality as models or prompts evolve.
+
+![Test Creation Flow](docs/sequence_diagrams/pngs/lamoom_test_creation.png)
+
+### Logging and Analytics
+Interaction logging happens asynchronously using a worker pattern:
+- **Performance Metrics**: Automatically track latency, token usage, and cost.
+- **Complete Context**: Store the full prompt, context, and response for analysis.
+- **Non-Blocking**: Logging happens in the background without impacting response times.
+
+![Logging Flow](docs/sequence_diagrams/pngs/lamoom_save_user_interactions.png)
+
+### Feedback Collection
+Improve prompt quality through explicit feedback:
+- **Ideal Answer Addition**: Associate ideal answers with previous responses using `add_ideal_answer()`.
+- **Continuous Improvement**: Use feedback to automatically generate new tests and refine prompts.
+
+![Feedback Flow](docs/sequence_diagrams/pngs/lamoom_add_ideal_answer.png)
 
 ## Installation
 
@@ -68,6 +104,7 @@ Lamoom(api_token='your_api_token')
 
 ## Usage Examples:
 
+### Basic Usage
 ```python
 from lamoom import Lamoom, Prompt
 
@@ -80,17 +117,44 @@ prompt.add("You're {name}. Say Hello and ask what's their name.", role="system")
 
 # Call AI model with Lamoom
 context = {"name": "John Doe"}
-# test_data -  optional parameter used for generating tests
+response = client.call(prompt.id, context, "openai/gpt-4o")
+print(response.content)
+```
+
+### Creating Tests While Using Prompts
+```python
+# Call with test_data to automatically generate tests
 response = client.call(prompt.id, context, "openai/gpt-4o", test_data={
     'ideal_answer': "Hello, I'm John Doe. What's your name?", 
     'behavior_name': "gemini"
-    }
+})
+```
+
+### Creating Tests Explicitly
+```python
+# Create a test directly
+client.create_test(
+    prompt_id="greet_user",
+    test_context={"name": "John Doe"},
+    ideal_answer="Hello, I'm John Doe. What's your name?"
+)
+```
+
+### Adding Feedback to Previous Responses
+```python
+# Add an ideal answer to a previous response for quality assessment
+client.add_ideal_answer(
+    response_id="greet_user#1620000000000",
+    ideal_answer="Hello, I'm John Doe. What's your name?"
 )
-print(response.content)
 ```
-- To review your created tests and score please go to https://cloud.lamoom.com/tests. You can update there Prompt and rerun tests for a published version, or saved version. If you will update and publish version online - library will automatically use the new updated version of the prompt. It's made for updating prompt without redeployment of the code, which is costly operation to do if it's required to update just prompt.
 
-- To review logs please proceed to https://cloud.lamoom.com/logs, there you can see metrics like latency, cost, tokens;
+### Monitoring and Management
+- **Test Dashboard**: Review created tests and scores at https://cloud.lamoom.com/tests
+- **Prompt Management**: Update prompts and rerun tests for published or saved versions
+- **Analytics**: View logs with metrics (latency, cost, tokens) at https://cloud.lamoom.com/logs
+
+The system is designed to allow prompt updates without code redeployment—simply publish a new prompt version online, and the library will automatically fetch and use it.
 
 ## Best Security Practices
 For production environments, it is recommended to store secrets securely and not directly in your codebase. Consider using a secret management service or encrypted environment variables.

examples/evaluate_prompts_quality/evaluate_prompt_quality.py renamed to docs/evaluate_prompts_quality/evaluate_prompt_quality.py

@@ -0,0 +1,24 @@
+@startuml
+
+  title Lamoom Feedback Flow: Adding ideal answers to existing responses
+
+  note over Client,LamoomService: Process of providing feedback on previous responses
+
+    Client->>Lamoom: add_ideal_answer(response_id, ideal_answer)
+    activate Lamoom
+
+    Lamoom->>LamoomService: update_response_ideal_answer(api_token, log_id, ideal_answer)
+    activate LamoomService
+
+    LamoomService->>LamoomService: Prepare feedback data
+
+    LamoomService->>LamoomService: PUT /lib/logs
+    note right of LamoomService: Server updates existing log with:\n- Ideal answer for comparison\n- Used for quality assessment\n- Creating training data\n- Generating automated tests
+
+    LamoomService-->>Lamoom: Return feedback submission result
+    deactivate LamoomService
+
+    Lamoom-->>Client: Return feedback submission result
+    deactivate Lamoom
+
+  @enduml