quantalogic 0.2.16__tar.gz → 0.2.18__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (76) hide show
  1. {quantalogic-0.2.16 → quantalogic-0.2.18}/PKG-INFO +62 -153
  2. {quantalogic-0.2.16 → quantalogic-0.2.18}/README.md +52 -152
  3. {quantalogic-0.2.16 → quantalogic-0.2.18}/pyproject.toml +24 -1
  4. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/__init__.py +3 -2
  5. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/agent.py +94 -38
  6. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/agent_config.py +62 -14
  7. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/coding_agent.py +17 -2
  8. quantalogic-0.2.16/quantalogic/print_event.py → quantalogic-0.2.18/quantalogic/console_print_events.py +1 -3
  9. quantalogic-0.2.18/quantalogic/console_print_token.py +16 -0
  10. quantalogic-0.2.18/quantalogic/docs_cli.py +50 -0
  11. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/generative_model.py +86 -77
  12. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/main.py +128 -18
  13. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/prompts.py +2 -2
  14. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/search_agent.py +12 -1
  15. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/server/agent_server.py +2 -2
  16. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/tools/llm_tool.py +52 -11
  17. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/tools/llm_vision_tool.py +23 -7
  18. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/xml_parser.py +109 -49
  19. {quantalogic-0.2.16 → quantalogic-0.2.18}/LICENSE +0 -0
  20. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/event_emitter.py +0 -0
  21. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/interactive_text_editor.py +0 -0
  22. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/memory.py +0 -0
  23. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/model_names.py +0 -0
  24. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/server/__init__.py +0 -0
  25. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/server/models.py +0 -0
  26. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/server/routes.py +0 -0
  27. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/server/state.py +0 -0
  28. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/server/static/js/event_visualizer.js +0 -0
  29. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/server/static/js/quantalogic.js +0 -0
  30. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/server/templates/index.html +0 -0
  31. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/tool_manager.py +0 -0
  32. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/tools/__init__.py +0 -0
  33. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/tools/agent_tool.py +0 -0
  34. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/tools/download_http_file_tool.py +0 -0
  35. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/tools/duckduckgo_search_tool.py +0 -0
  36. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/tools/edit_whole_content_tool.py +0 -0
  37. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/tools/elixir_tool.py +0 -0
  38. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/tools/execute_bash_command_tool.py +0 -0
  39. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/tools/input_question_tool.py +0 -0
  40. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/tools/language_handlers/__init__.py +0 -0
  41. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/tools/language_handlers/c_handler.py +0 -0
  42. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/tools/language_handlers/cpp_handler.py +0 -0
  43. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/tools/language_handlers/go_handler.py +0 -0
  44. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/tools/language_handlers/java_handler.py +0 -0
  45. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/tools/language_handlers/javascript_handler.py +0 -0
  46. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/tools/language_handlers/python_handler.py +0 -0
  47. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/tools/language_handlers/rust_handler.py +0 -0
  48. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/tools/language_handlers/scala_handler.py +0 -0
  49. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/tools/language_handlers/typescript_handler.py +0 -0
  50. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/tools/list_directory_tool.py +0 -0
  51. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/tools/markitdown_tool.py +0 -0
  52. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/tools/nodejs_tool.py +0 -0
  53. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/tools/python_tool.py +0 -0
  54. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/tools/read_file_block_tool.py +0 -0
  55. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/tools/read_file_tool.py +0 -0
  56. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/tools/replace_in_file_tool.py +0 -0
  57. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/tools/ripgrep_tool.py +0 -0
  58. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/tools/search_definition_names.py +0 -0
  59. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/tools/serpapi_search_tool.py +0 -0
  60. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/tools/task_complete_tool.py +0 -0
  61. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/tools/tool.py +0 -0
  62. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/tools/unified_diff_tool.py +0 -0
  63. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/tools/wikipedia_search_tool.py +0 -0
  64. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/tools/write_file_tool.py +0 -0
  65. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/utils/__init__.py +0 -0
  66. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/utils/ask_user_validation.py +0 -0
  67. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/utils/check_version.py +0 -0
  68. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/utils/download_http_file.py +0 -0
  69. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/utils/get_coding_environment.py +0 -0
  70. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/utils/get_environment.py +0 -0
  71. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/utils/get_quantalogic_rules_content.py +0 -0
  72. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/utils/git_ls.py +0 -0
  73. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/utils/read_file.py +0 -0
  74. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/utils/read_http_text_content.py +0 -0
  75. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/version.py +0 -0
  76. {quantalogic-0.2.16 → quantalogic-0.2.18}/quantalogic/xml_tool_parser.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.1
2
2
  Name: quantalogic
3
- Version: 0.2.16
3
+ Version: 0.2.18
4
4
  Summary: QuantaLogic ReAct Agents
5
5
  Author: Raphaël MANSUY
6
6
  Author-email: raphael.mansuy@gmail.com
@@ -15,11 +15,20 @@ Requires-Dist: fastapi (>=0.115.6,<0.116.0)
15
15
  Requires-Dist: google-auth (>=2.20.0,<3.0.0)
16
16
  Requires-Dist: google-search-results (>=2.4.2,<3.0.0)
17
17
  Requires-Dist: litellm (>=1.56.4,<2.0.0)
18
+ Requires-Dist: llmlingua (>=0.2.2,<0.3.0)
18
19
  Requires-Dist: loguru (>=0.7.3,<0.8.0)
19
20
  Requires-Dist: markitdown (>=0.0.1a3,<0.0.2)
21
+ Requires-Dist: mkdocs-git-revision-date-localized-plugin (>=1.2.0,<2.0.0)
22
+ Requires-Dist: mkdocs-macros-plugin (>=1.0.4,<2.0.0)
23
+ Requires-Dist: mkdocs-material[imaging] (>=9.5.49,<10.0.0)
24
+ Requires-Dist: mkdocs-mermaid2-plugin (>=1.1.1,<2.0.0)
25
+ Requires-Dist: mkdocs-minify-plugin (>=0.7.1,<0.8.0)
26
+ Requires-Dist: mkdocstrings (>=0.24.0,<0.25.0)
27
+ Requires-Dist: mkdocstrings-python (>=1.7.0,<2.0.0)
20
28
  Requires-Dist: pathspec (>=0.12.1,<0.13.0)
21
29
  Requires-Dist: prompt-toolkit (>=3.0.48,<4.0.0)
22
30
  Requires-Dist: pydantic (>=2.10.4,<3.0.0)
31
+ Requires-Dist: pymdown-extensions (>=10.3.1,<11.0.0)
23
32
  Requires-Dist: rich (>=13.9.4,<14.0.0)
24
33
  Requires-Dist: serpapi (>=0.1.5,<0.2.0)
25
34
  Requires-Dist: tenacity (>=9.0.0,<10.0.0)
@@ -43,7 +52,7 @@ Description-Content-Type: text/markdown
43
52
 
44
53
  [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
45
54
  [![Python](https://img.shields.io/badge/Python-3.12+-blue.svg)](https://www.python.org/downloads/)
46
- [![Documentation](https://img.shields.io/badge/docs-latest-brightgreen.svg)]()
55
+ [![Documentation](https://img.shields.io/badge/docs-latest-brightgreen.svg)](https://quantalogic.github.io/quantalogic/)
47
56
 
48
57
  QuantaLogic is a ReAct (Reasoning & Action) framework for building advanced AI agents.
49
58
 
@@ -51,6 +60,8 @@ It seamlessly integrates large language models (LLMs) with a robust tool system,
51
60
 
52
61
  The `cli` version include coding capabilities comparable to Aider.
53
62
 
63
+ [📖 Documentation](https://quantalogic.github.io/quantalogic/)
64
+
54
65
 
55
66
  ## Why QuantaLogic?
56
67
 
@@ -70,6 +81,8 @@ We created [QuantaLogic](https://www.quantalogic.app) because we saw a significa
70
81
 
71
82
  ## 📋 Table of Contents
72
83
 
84
+ - [Release Notes](#release-notes)
85
+
73
86
  - [Installation](#-installation)
74
87
  - [Quick Start](#-quickstart)
75
88
  - [Key Components](#-key-components)
@@ -80,6 +93,13 @@ We created [QuantaLogic](https://www.quantalogic.app) because we saw a significa
80
93
  - [Development](#-development)
81
94
  - [Contributing](#-contributing)
82
95
  - [License](#-license)
96
+ - [Documentation Development](#-documentation-development)
97
+
98
+ ## Release Notes
99
+
100
+ See our [Release Notes](RELEASE_NOTES.MD) for detailed version history and changes.
101
+
102
+ [TODO List](TODO.md)
83
103
 
84
104
  ## 📦 Installation
85
105
 
@@ -122,20 +142,18 @@ The QuantaLogic CLI provides powerful command-line capabilities:
122
142
 
123
143
  ```bash
124
144
  Usage: quantalogic [OPTIONS] COMMAND [ARGS]...
125
-
126
145
  QuantaLogic AI Assistant - A powerful AI tool for various tasks.
127
146
 
128
147
  Options:
129
148
  --version Show version information.
130
- --model-name TEXT Specify the text model to use (litellm format,
131
- e.g. "openrouter/deepseek-chat").
132
- --vision-model-name TEXT Specify the vision model to use (litellm format,
133
- e.g. "openrouter/A/gpt-4o-mini").
134
- --log [info|debug|warning] Set logging level (info/debug/warning).
149
+ --model-name TEXT Specify the model (litellm format, e.g., "openrouter/deepseek/deepseek-chat").
150
+ --log [info|debug|warning] Set logging level.
135
151
  --verbose Enable verbose output.
152
+ --mode [code|basic|interpreter|full|code-basic|search|search-full] Agent mode.
153
+ --vision-model-name TEXT Specify the vision model (litellm format, e.g., "openrouter/A/gpt-4o-mini").
136
154
  --max-iterations INTEGER Maximum iterations for task solving (default: 30).
137
- --mode [code|basic|interpreter|full|code-basic|search|search-full]
138
- Agent mode (code/search/full).
155
+ --max-tokens-working-memory INTEGER Maximum tokens to keep in working memory (default: 4000).
156
+ --compact-every-n-iteration INTEGER Compact memory every N iterations (default: 5).
139
157
  --help Show this message and exit.
140
158
 
141
159
  Commands:
@@ -145,6 +163,38 @@ Commands:
145
163
  ### Commands
146
164
  task Execute a task with the QuantaLogic AI Assistant
147
165
 
166
+ **Usage:** `quantalogic task [OPTIONS] [TASK]`
167
+ **Description:** Execute a task with the QuantaLogic AI Assistant.
168
+ **Options:**
169
+ - `--file PATH`: Path to task file.
170
+ - `--model-name TEXT`: Specify the model (litellm format, e.g., `openrouter/deepseek/deepseek-chat`).
171
+ - `--verbose`: Enable verbose output.
172
+ - `--mode [code|basic|interpreter|full|code-basic|search|search-full]`: Agent mode.
173
+ - `--log [info|debug|warning]`: Set logging level.
174
+ - `--vision-model-name TEXT`: Specify the vision model (litellm format).
175
+ - `--max-iterations INTEGER`: Maximum iterations for task solving (default: 30).
176
+ - `--max-tokens-working-memory INTEGER`: Maximum tokens to keep in working memory (default: 4000).
177
+ - `--compact-every-n-iteration INTEGER`: Compact memory every N iterations (default: 5).
178
+ - `--no-stream`: Disable streaming output (default: enabled).
179
+ - `--help`: Show this message and exit.
180
+
181
+ **Detailed Parameter Descriptions:**
182
+
183
+ - **--model-name**: Specifies the LLM model to use (e.g., "openrouter/deepseek/deepseek-chat")
184
+ - **--mode**: Selects agent capabilities:
185
+ - *code*: Coding-focused with basic capabilities
186
+ - *basic*: General-purpose without coding tools
187
+ - *interpreter*: Interactive code execution
188
+ - *full*: All capabilities enabled
189
+ - *code-basic*: Coding with basic reasoning
190
+ - *search*: Web search integration
191
+ - **--log**: Controls logging verbosity (info, debug, warning)
192
+ - **--vision-model-name**: Specifies vision model for image processing
193
+ - **--max-iterations**: Limits task-solving attempts (default: 30)
194
+ - **--max-tokens-working-memory**: Controls memory usage (default: None)
195
+ - **--compact-every-n-iteration**: Memory optimization frequency (default: None)
196
+ - **--no-stream**: Disables real-time output streaming
197
+
148
198
 
149
199
 
150
200
  ### Detailed Usage
@@ -251,7 +301,7 @@ from quantalogic.tools import PythonTool, ReadFileTool
251
301
 
252
302
  # Create agent with specific tools
253
303
  agent = Agent(
254
- model_name="openrouter/deepseek-chat",
304
+ model_name="openrouter/deepseek/deepseek-chat",
255
305
  tools=[
256
306
  PythonTool(),
257
307
  ReadFileTool()
@@ -844,148 +894,7 @@ print(results)
844
894
  ```
845
895
  ```
846
896
 
847
- #### Creating Custom Tools
848
-
849
- ```python
850
- from quantalogic.tools import Tool, ToolArgument
851
-
852
- class DatabaseTool(Tool):
853
- name: str = "database_tool"
854
- description: str = "Execute database operations"
855
- need_validation: bool = True
856
-
857
- arguments: list[ToolArgument] = [
858
- ToolArgument(
859
- name="query",
860
- arg_type="string",
861
- description="SQL query to execute",
862
- required=True
863
- )
864
- ]
865
-
866
- def execute(self, query: str) -> str:
867
- # Tool implementation
868
- return "Query results"
869
897
  ```
870
-
871
-
872
- ## 🌐 Web Interface
873
-
874
- Features:
875
- - Real-time event visualization
876
- - Task submission and monitoring
877
- - Interactive validation dialogs
878
- - Model selection
879
- - Event filtering and search
880
-
881
- ### API Endpoints
882
-
883
- | Endpoint | Method | Description |
884
- | ------------------ | ------ | --------------- |
885
- | `/tasks` | POST | Submit tasks |
886
- | `/tasks/{task_id}` | GET | Task status |
887
- | `/events` | GET | SSE endpoint |
888
- | `/validate` | POST | Task validation |
889
-
890
-
891
- ## 📖 Examples
892
-
893
- ### Python Tool Integration Example
894
-
895
- ```python
896
- import os
897
-
898
- from quantalogic import Agent, console_print_events
899
- from quantalogic.tools import (
900
- PythonTool,
901
- )
902
-
903
- # Verify API key is set - required for authentication with DeepSeek's API
904
- # This check ensures the agent won't fail during runtime due to missing credentials
905
- if not os.environ.get("DEEPSEEK_API_KEY"):
906
- raise ValueError("DEEPSEEK_API_KEY environment variable is not set")
907
-
908
- # Initialize agent with DeepSeek model and Python tool
909
- agent = Agent(model_name="deepseek/deepseek-chat", tools=[PythonTool()])
910
-
911
- # Configure comprehensive event monitoring system
912
- # Tracks all agent activities including:
913
- # - Code execution steps
914
- # - Tool interactions
915
- # - Error conditions
916
- # Essential for debugging and performance optimization
917
- agent.event_emitter.on(
918
- "*",
919
- console_print_events,
920
- )
921
-
922
- # Execute a precision mathematics task demonstrating:
923
- # - High-precision calculations
924
- # - PythonTool integration
925
- # - Real-time monitoring capabilities
926
- result = agent.solve_task("1. Calculate PI with 10000 decimal places.")
927
- print(result)
928
- ```
929
-
930
- ### Agent with Event Monitoring
931
-
932
- ```python
933
- import os
934
-
935
- from quantalogic import Agent, console_print_events
936
- from quantalogic.tools import (
937
- LLMTool,
938
- )
939
-
940
- # Verify API key is set - required for authentication with DeepSeek's API
941
- # This check ensures the agent won't fail during runtime due to missing credentials
942
- if not os.environ.get("DEEPSEEK_API_KEY"):
943
- raise ValueError("DEEPSEEK_API_KEY environment variable is not set")
944
-
945
- # Initialize agent with DeepSeek model and LLM tool
946
- # The LLM tool serves dual purpose:
947
- # 1. As a reasoning engine for the agent's cognitive processes
948
- # 2. As a latent space explorer, enabling the agent to:
949
- # - Discover novel solution paths
950
- # - Generate creative combinations of concepts
951
- # - Explore alternative reasoning strategies
952
- # Using the same model ensures consistent behavior across both roles
953
- agent = Agent(model_name="deepseek/deepseek-chat", tools=[LLMTool(model_name="deepseek/deepseek-chat")])
954
-
955
- # Set up event monitoring to track agent's lifecycle
956
- # This helps in debugging and understanding the agent's behavior
957
- agent.event_emitter.on(
958
- [
959
- "task_complete",
960
- "task_think_start",
961
- "task_think_end",
962
- "tool_execution_start",
963
- "tool_execution_end",
964
- "error_max_iterations_reached",
965
- "memory_full",
966
- "memory_compacted",
967
- "memory_summary",
968
- ],
969
- console_print_events,
970
- )
971
-
972
- # Execute a multi-step task showcasing agent's capabilities
973
- # Demonstrates:
974
- # 1. Creative content generation
975
- # 2. Language translation
976
- # 3. Style adaptation
977
- # 4. Multi-step reasoning and execution
978
- result = agent.solve_task(
979
- "1. Write a poem in English about a dog. "
980
- "2. Translate the poem into French. "
981
- "3. Choose 2 French authors"
982
- "4. Rewrite the translated poem with the style of the chosen authors. "
983
- )
984
- print(result)
985
- ```
986
-
987
-
988
-
989
898
  ### Project Documentation
990
899
 
991
900
  ```python
@@ -993,7 +902,7 @@ from quantalogic import Agent
993
902
  from quantalogic.tools import MarkitdownTool, ReadFileTool
994
903
 
995
904
  agent = Agent(
996
- model_name="openrouter/deepseek-chat",
905
+ model_name="openrouter/deepseek/deepseek-chat",
997
906
  tools=[MarkitdownTool(), ReadFileTool()]
998
907
  )
999
908
 
@@ -2,7 +2,7 @@
2
2
 
3
3
  [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
4
4
  [![Python](https://img.shields.io/badge/Python-3.12+-blue.svg)](https://www.python.org/downloads/)
5
- [![Documentation](https://img.shields.io/badge/docs-latest-brightgreen.svg)]()
5
+ [![Documentation](https://img.shields.io/badge/docs-latest-brightgreen.svg)](https://quantalogic.github.io/quantalogic/)
6
6
 
7
7
  QuantaLogic is a ReAct (Reasoning & Action) framework for building advanced AI agents.
8
8
 
@@ -10,6 +10,8 @@ It seamlessly integrates large language models (LLMs) with a robust tool system,
10
10
 
11
11
  The `cli` version include coding capabilities comparable to Aider.
12
12
 
13
+ [📖 Documentation](https://quantalogic.github.io/quantalogic/)
14
+
13
15
 
14
16
  ## Why QuantaLogic?
15
17
 
@@ -29,6 +31,8 @@ We created [QuantaLogic](https://www.quantalogic.app) because we saw a significa
29
31
 
30
32
  ## 📋 Table of Contents
31
33
 
34
+ - [Release Notes](#release-notes)
35
+
32
36
  - [Installation](#-installation)
33
37
  - [Quick Start](#-quickstart)
34
38
  - [Key Components](#-key-components)
@@ -39,6 +43,13 @@ We created [QuantaLogic](https://www.quantalogic.app) because we saw a significa
39
43
  - [Development](#-development)
40
44
  - [Contributing](#-contributing)
41
45
  - [License](#-license)
46
+ - [Documentation Development](#-documentation-development)
47
+
48
+ ## Release Notes
49
+
50
+ See our [Release Notes](RELEASE_NOTES.MD) for detailed version history and changes.
51
+
52
+ [TODO List](TODO.md)
42
53
 
43
54
  ## 📦 Installation
44
55
 
@@ -81,20 +92,18 @@ The QuantaLogic CLI provides powerful command-line capabilities:
81
92
 
82
93
  ```bash
83
94
  Usage: quantalogic [OPTIONS] COMMAND [ARGS]...
84
-
85
95
  QuantaLogic AI Assistant - A powerful AI tool for various tasks.
86
96
 
87
97
  Options:
88
98
  --version Show version information.
89
- --model-name TEXT Specify the text model to use (litellm format,
90
- e.g. "openrouter/deepseek-chat").
91
- --vision-model-name TEXT Specify the vision model to use (litellm format,
92
- e.g. "openrouter/A/gpt-4o-mini").
93
- --log [info|debug|warning] Set logging level (info/debug/warning).
99
+ --model-name TEXT Specify the model (litellm format, e.g., "openrouter/deepseek/deepseek-chat").
100
+ --log [info|debug|warning] Set logging level.
94
101
  --verbose Enable verbose output.
102
+ --mode [code|basic|interpreter|full|code-basic|search|search-full] Agent mode.
103
+ --vision-model-name TEXT Specify the vision model (litellm format, e.g., "openrouter/A/gpt-4o-mini").
95
104
  --max-iterations INTEGER Maximum iterations for task solving (default: 30).
96
- --mode [code|basic|interpreter|full|code-basic|search|search-full]
97
- Agent mode (code/search/full).
105
+ --max-tokens-working-memory INTEGER Maximum tokens to keep in working memory (default: 4000).
106
+ --compact-every-n-iteration INTEGER Compact memory every N iterations (default: 5).
98
107
  --help Show this message and exit.
99
108
 
100
109
  Commands:
@@ -104,6 +113,38 @@ Commands:
104
113
  ### Commands
105
114
  task Execute a task with the QuantaLogic AI Assistant
106
115
 
116
+ **Usage:** `quantalogic task [OPTIONS] [TASK]`
117
+ **Description:** Execute a task with the QuantaLogic AI Assistant.
118
+ **Options:**
119
+ - `--file PATH`: Path to task file.
120
+ - `--model-name TEXT`: Specify the model (litellm format, e.g., `openrouter/deepseek/deepseek-chat`).
121
+ - `--verbose`: Enable verbose output.
122
+ - `--mode [code|basic|interpreter|full|code-basic|search|search-full]`: Agent mode.
123
+ - `--log [info|debug|warning]`: Set logging level.
124
+ - `--vision-model-name TEXT`: Specify the vision model (litellm format).
125
+ - `--max-iterations INTEGER`: Maximum iterations for task solving (default: 30).
126
+ - `--max-tokens-working-memory INTEGER`: Maximum tokens to keep in working memory (default: 4000).
127
+ - `--compact-every-n-iteration INTEGER`: Compact memory every N iterations (default: 5).
128
+ - `--no-stream`: Disable streaming output (default: enabled).
129
+ - `--help`: Show this message and exit.
130
+
131
+ **Detailed Parameter Descriptions:**
132
+
133
+ - **--model-name**: Specifies the LLM model to use (e.g., "openrouter/deepseek/deepseek-chat")
134
+ - **--mode**: Selects agent capabilities:
135
+ - *code*: Coding-focused with basic capabilities
136
+ - *basic*: General-purpose without coding tools
137
+ - *interpreter*: Interactive code execution
138
+ - *full*: All capabilities enabled
139
+ - *code-basic*: Coding with basic reasoning
140
+ - *search*: Web search integration
141
+ - **--log**: Controls logging verbosity (info, debug, warning)
142
+ - **--vision-model-name**: Specifies vision model for image processing
143
+ - **--max-iterations**: Limits task-solving attempts (default: 30)
144
+ - **--max-tokens-working-memory**: Controls memory usage (default: None)
145
+ - **--compact-every-n-iteration**: Memory optimization frequency (default: None)
146
+ - **--no-stream**: Disables real-time output streaming
147
+
107
148
 
108
149
 
109
150
  ### Detailed Usage
@@ -210,7 +251,7 @@ from quantalogic.tools import PythonTool, ReadFileTool
210
251
 
211
252
  # Create agent with specific tools
212
253
  agent = Agent(
213
- model_name="openrouter/deepseek-chat",
254
+ model_name="openrouter/deepseek/deepseek-chat",
214
255
  tools=[
215
256
  PythonTool(),
216
257
  ReadFileTool()
@@ -803,148 +844,7 @@ print(results)
803
844
  ```
804
845
  ```
805
846
 
806
- #### Creating Custom Tools
807
-
808
- ```python
809
- from quantalogic.tools import Tool, ToolArgument
810
-
811
- class DatabaseTool(Tool):
812
- name: str = "database_tool"
813
- description: str = "Execute database operations"
814
- need_validation: bool = True
815
-
816
- arguments: list[ToolArgument] = [
817
- ToolArgument(
818
- name="query",
819
- arg_type="string",
820
- description="SQL query to execute",
821
- required=True
822
- )
823
- ]
824
-
825
- def execute(self, query: str) -> str:
826
- # Tool implementation
827
- return "Query results"
828
847
  ```
829
-
830
-
831
- ## 🌐 Web Interface
832
-
833
- Features:
834
- - Real-time event visualization
835
- - Task submission and monitoring
836
- - Interactive validation dialogs
837
- - Model selection
838
- - Event filtering and search
839
-
840
- ### API Endpoints
841
-
842
- | Endpoint | Method | Description |
843
- | ------------------ | ------ | --------------- |
844
- | `/tasks` | POST | Submit tasks |
845
- | `/tasks/{task_id}` | GET | Task status |
846
- | `/events` | GET | SSE endpoint |
847
- | `/validate` | POST | Task validation |
848
-
849
-
850
- ## 📖 Examples
851
-
852
- ### Python Tool Integration Example
853
-
854
- ```python
855
- import os
856
-
857
- from quantalogic import Agent, console_print_events
858
- from quantalogic.tools import (
859
- PythonTool,
860
- )
861
-
862
- # Verify API key is set - required for authentication with DeepSeek's API
863
- # This check ensures the agent won't fail during runtime due to missing credentials
864
- if not os.environ.get("DEEPSEEK_API_KEY"):
865
- raise ValueError("DEEPSEEK_API_KEY environment variable is not set")
866
-
867
- # Initialize agent with DeepSeek model and Python tool
868
- agent = Agent(model_name="deepseek/deepseek-chat", tools=[PythonTool()])
869
-
870
- # Configure comprehensive event monitoring system
871
- # Tracks all agent activities including:
872
- # - Code execution steps
873
- # - Tool interactions
874
- # - Error conditions
875
- # Essential for debugging and performance optimization
876
- agent.event_emitter.on(
877
- "*",
878
- console_print_events,
879
- )
880
-
881
- # Execute a precision mathematics task demonstrating:
882
- # - High-precision calculations
883
- # - PythonTool integration
884
- # - Real-time monitoring capabilities
885
- result = agent.solve_task("1. Calculate PI with 10000 decimal places.")
886
- print(result)
887
- ```
888
-
889
- ### Agent with Event Monitoring
890
-
891
- ```python
892
- import os
893
-
894
- from quantalogic import Agent, console_print_events
895
- from quantalogic.tools import (
896
- LLMTool,
897
- )
898
-
899
- # Verify API key is set - required for authentication with DeepSeek's API
900
- # This check ensures the agent won't fail during runtime due to missing credentials
901
- if not os.environ.get("DEEPSEEK_API_KEY"):
902
- raise ValueError("DEEPSEEK_API_KEY environment variable is not set")
903
-
904
- # Initialize agent with DeepSeek model and LLM tool
905
- # The LLM tool serves dual purpose:
906
- # 1. As a reasoning engine for the agent's cognitive processes
907
- # 2. As a latent space explorer, enabling the agent to:
908
- # - Discover novel solution paths
909
- # - Generate creative combinations of concepts
910
- # - Explore alternative reasoning strategies
911
- # Using the same model ensures consistent behavior across both roles
912
- agent = Agent(model_name="deepseek/deepseek-chat", tools=[LLMTool(model_name="deepseek/deepseek-chat")])
913
-
914
- # Set up event monitoring to track agent's lifecycle
915
- # This helps in debugging and understanding the agent's behavior
916
- agent.event_emitter.on(
917
- [
918
- "task_complete",
919
- "task_think_start",
920
- "task_think_end",
921
- "tool_execution_start",
922
- "tool_execution_end",
923
- "error_max_iterations_reached",
924
- "memory_full",
925
- "memory_compacted",
926
- "memory_summary",
927
- ],
928
- console_print_events,
929
- )
930
-
931
- # Execute a multi-step task showcasing agent's capabilities
932
- # Demonstrates:
933
- # 1. Creative content generation
934
- # 2. Language translation
935
- # 3. Style adaptation
936
- # 4. Multi-step reasoning and execution
937
- result = agent.solve_task(
938
- "1. Write a poem in English about a dog. "
939
- "2. Translate the poem into French. "
940
- "3. Choose 2 French authors"
941
- "4. Rewrite the translated poem with the style of the chosen authors. "
942
- )
943
- print(result)
944
- ```
945
-
946
-
947
-
948
848
  ### Project Documentation
949
849
 
950
850
  ```python
@@ -952,7 +852,7 @@ from quantalogic import Agent
952
852
  from quantalogic.tools import MarkitdownTool, ReadFileTool
953
853
 
954
854
  agent = Agent(
955
- model_name="openrouter/deepseek-chat",
855
+ model_name="openrouter/deepseek/deepseek-chat",
956
856
  tools=[MarkitdownTool(), ReadFileTool()]
957
857
  )
958
858
 
@@ -1,6 +1,6 @@
1
1
  [tool.poetry]
2
2
  name = "quantalogic"
3
- version = "0.2.16"
3
+ version = "0.2.18"
4
4
  description = "QuantaLogic ReAct Agents"
5
5
  authors = ["Raphaël MANSUY <raphael.mansuy@gmail.com>"]
6
6
  readme = "README.md"
@@ -37,9 +37,21 @@ types-requests = "^2.32.0.20241016"
37
37
  google-search-results = "^2.4.2"
38
38
  serpapi = "^0.1.5"
39
39
  duckduckgo-search = "^7.2.1"
40
+ mkdocs-material = {extras = ["imaging"], version = "^9.5.49"}
41
+ mkdocs-mermaid2-plugin = "^1.1.1"
42
+ mkdocs-minify-plugin = "^0.7.1"
43
+ mkdocs-git-revision-date-localized-plugin = "^1.2.0"
44
+ mkdocs-macros-plugin = "^1.0.4"
45
+ mkdocstrings = "^0.24.0"
46
+ mkdocstrings-python = "^1.7.0"
47
+ pymdown-extensions = "^10.3.1"
48
+ llmlingua = "^0.2.2"
40
49
 
41
50
  [tool.poetry.scripts]
42
51
  quantalogic = "quantalogic.main:cli"
52
+ docs-serve = "quantalogic.docs_cli:serve_docs"
53
+ docs-build = "quantalogic.docs_cli:build_docs"
54
+ docs-deploy = "quantalogic.docs_cli:deploy_docs"
43
55
 
44
56
  [tool.poetry.group.dev.dependencies]
45
57
  ruff = "^0.8.4"
@@ -47,6 +59,17 @@ pytest = "^8.2.0"
47
59
  pytest-mock = "^3.14.0"
48
60
  litellm = "^1.55.9"
49
61
  ollama = "^0.4.4"
62
+ mkdocs = "^1.6.0"
63
+ mkdocs-material = "^9.5.0"
64
+
65
+ [tool.poetry.group.docs.dependencies]
66
+ mkdocs-material = {extras = ["imaging"], version = "^9.5.49"}
67
+ mkdocs-mermaid2-plugin = "^1.1.1"
68
+ mkdocs-git-revision-date-localized-plugin = "^1.2.0"
69
+ mkdocs-macros-plugin = "^1.0.4"
70
+ mkdocstrings = "^0.24.0"
71
+ mkdocstrings-python = "^1.7.0"
72
+ pymdown-extensions = "^10.3.1"
50
73
 
51
74
  [build-system]
52
75
  requires = ["poetry-core"]
@@ -11,10 +11,11 @@ warnings.filterwarnings(
11
11
 
12
12
 
13
13
  from .agent import Agent # noqa: E402
14
+ from .console_print_events import console_print_events # noqa: E402
15
+ from .console_print_token import console_print_token # noqa: E402
14
16
  from .event_emitter import EventEmitter # noqa: E402
15
17
  from .memory import AgentMemory, VariableMemory # noqa: E402
16
- from .print_event import console_print_events # noqa: E402
17
18
 
18
19
  """QuantaLogic package for AI-powered generative models."""
19
20
 
20
- __all__ = ["Agent", "EventEmitter", "AgentMemory", "VariableMemory", "console_print_events"]
21
+ __all__ = ["Agent", "EventEmitter", "AgentMemory", "VariableMemory", "console_print_events","console_print_token"]