PraisonAI 2.3.87__tar.gz → 2.4.2__tar.gz

{praisonai-2.3.87 → praisonai-2.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PraisonAI
-Version: 2.3.87
+Version: 2.4.2
 Summary: PraisonAI is an AI Agents Framework with Self Reflection. PraisonAI application combines PraisonAI Agents, AutoGen, and CrewAI into a low-code solution for building and managing multi-agent LLM systems, focusing on simplicity, customisation, and efficient human-agent collaboration.
 Author: Mervin Praison
 License: MIT
@@ -11,7 +11,7 @@ Description-Content-Type: text/markdown
 Requires-Dist: rich>=13.7
 Requires-Dist: markdown>=3.5
 Requires-Dist: pyparsing>=3.0.0
-Requires-Dist: praisonaiagents>=0.1.27
+Requires-Dist: praisonaiagents>=0.2.1
 Requires-Dist: python-dotenv>=0.19.0
 Requires-Dist: instructor>=1.3.3
 Requires-Dist: PyYAML>=6.0
@@ -358,6 +358,12 @@ npm install praisonai
 | ↳ 100+ LLM Support | [Example](examples/python/providers/openai/openai_gpt4_example.py) | [📖](https://docs.praison.ai/models) |
 | ↳ Callback Agents | [Example](examples/python/general/advanced-callback-systems.py) | [📖](https://docs.praison.ai/features/callbacks) |
 | ↳ Hooks | [Example](#9-hooks) | [📖](https://docs.praison.ai/features/hooks) |
+| ↳ Shadow Git Checkpoints | [Example](#10-shadow-git-checkpoints) | [📖](https://docs.praison.ai/features/checkpoints) |
+| ↳ Background Tasks | [Example](examples/background/basic_background.py) | [📖](https://docs.praison.ai/features/background-tasks) |
+| ↳ Policy Engine | [Example](examples/policy/basic_policy.py) | [📖](https://docs.praison.ai/features/policy-engine) |
+| ↳ Thinking Budgets | [Example](examples/thinking/basic_thinking.py) | [📖](https://docs.praison.ai/features/thinking-budgets) |
+| ↳ Output Styles | [Example](examples/output/basic_output.py) | [📖](https://docs.praison.ai/features/output-styles) |
+| ↳ Context Compaction | [Example](examples/compaction/basic_compaction.py) | [📖](https://docs.praison.ai/features/context-compaction) |
 | **📊 Monitoring & Management** | | |
 | ↳ Sessions Management | [Example](examples/python/sessions/comprehensive-session-management.py) | [📖](https://docs.praison.ai/features/sessions) |
 | ↳ Auto-Save Sessions | [Example](#session-management-python) | [📖](https://docs.praison.ai/docs/cli/session) |
@@ -960,21 +966,258 @@ callbacks:
 
 ### 9. Hooks
 
-Configure in `.praison/hooks.json`:
+Intercept and modify agent behavior at various lifecycle points:
 
 ```python
-from praisonaiagents.memory import HooksManager
+from praisonaiagents.hooks import (
+    HookRegistry, HookRunner, HookEvent, HookResult,
+    BeforeToolInput
+)
+
+# Create a hook registry
+registry = HookRegistry()
 
-hooks = HooksManager()
+# Log all tool calls
+@registry.on(HookEvent.BEFORE_TOOL)
+def log_tools(event_data: BeforeToolInput) -> HookResult:
+    print(f"Tool: {event_data.tool_name}")
+    return HookResult.allow()
 
-# Register Python hooks
-hooks.register("pre_write_code", lambda ctx: print(f"Writing {ctx['file']}"))
+# Block dangerous operations
+@registry.on(HookEvent.BEFORE_TOOL)
+def security_check(event_data: BeforeToolInput) -> HookResult:
+    if "delete" in event_data.tool_name.lower():
+        return HookResult.deny("Delete operations blocked")
+    return HookResult.allow()
 
 # Execute hooks
-result = hooks.execute("pre_write_code", {"file": "main.py"})
+runner = HookRunner(registry)
+```
+
+**CLI Commands:**
+```bash
+praisonai hooks list                    # List registered hooks
+praisonai hooks test before_tool        # Test hooks for an event
+praisonai hooks run "echo test"         # Run a command hook
+praisonai hooks validate hooks.json     # Validate configuration
+```
+
+
+### 10. Shadow Git Checkpoints
+
+File-level undo/restore using shadow git:
+
+```python
+from praisonaiagents.checkpoints import CheckpointService
+
+service = CheckpointService(workspace_dir="./my_project")
+await service.initialize()
+
+# Save checkpoint before changes
+result = await service.save("Before refactoring")
+
+# Make changes...
+
+# Restore if needed
+await service.restore(result.checkpoint.id)
+
+# View diff
+diff = await service.diff()
+```
+
+**CLI Commands:**
+```bash
+praisonai checkpoint save "Before changes"  # Save checkpoint
+praisonai checkpoint list                   # List checkpoints
+praisonai checkpoint diff                   # Show changes
+praisonai checkpoint restore abc123         # Restore to checkpoint
+```
+
+**Links:**
+- [📖 Coding Docs](https://docs.praison.ai/features/checkpoints)
+- [📖 CLI Docs](https://docs.praison.ai/docs/cli/checkpoint)
+- [💻 Example](examples/checkpoints/basic_checkpoints.py)
+
+---
+
+### 11. Background Tasks
+
+Run agent tasks asynchronously without blocking:
+
+```python
+import asyncio
+from praisonaiagents.background import BackgroundRunner, BackgroundConfig
+
+async def main():
+    config = BackgroundConfig(max_concurrent_tasks=3)
+    runner = BackgroundRunner(config=config)
+    
+    async def my_task(name: str) -> str:
+        await asyncio.sleep(2)
+        return f"Task {name} completed"
+    
+    task = await runner.submit(my_task, args=("example",), name="my_task")
+    await task.wait(timeout=10.0)
+    print(task.result)
+
+asyncio.run(main())
+```
+
+**CLI Commands:**
+```bash
+praisonai background list          # List running tasks
+praisonai background status <id>   # Check task status
+praisonai background cancel <id>   # Cancel a task
+praisonai background clear         # Clear completed tasks
+```
+
+**Links:**
+- [📖 Coding Docs](https://docs.praison.ai/features/background-tasks)
+- [📖 CLI Docs](https://docs.praison.ai/docs/cli/background)
+- [💻 Example](examples/background/basic_background.py)
+
+---
+
+### 12. Policy Engine
+
+Control what agents can and cannot do with policy-based execution:
+
+```python
+from praisonaiagents.policy import (
+    PolicyEngine, Policy, PolicyRule, PolicyAction
+)
+
+engine = PolicyEngine()
+
+policy = Policy(
+    name="no_delete",
+    rules=[
+        PolicyRule(
+            action=PolicyAction.DENY,
+            resource="tool:delete_*",
+            reason="Delete operations blocked"
+        )
+    ]
+)
+engine.add_policy(policy)
+
+result = engine.check("tool:delete_file", {})
+print(f"Allowed: {result.allowed}")
+```
+
+**CLI Commands:**
+```bash
+praisonai policy list                  # List policies
+praisonai policy check "tool:name"     # Check if allowed
+praisonai policy init                  # Create template
+```
+
+**Links:**
+- [📖 Coding Docs](https://docs.praison.ai/features/policy-engine)
+- [📖 CLI Docs](https://docs.praison.ai/docs/cli/policy)
+- [💻 Example](examples/policy/basic_policy.py)
+
+---
+
+### 13. Thinking Budgets
+
+Configure token budgets for extended thinking:
+
+```python
+from praisonaiagents.thinking import ThinkingBudget, ThinkingTracker
+
+# Use predefined levels
+budget = ThinkingBudget.high()  # 16,000 tokens
+
+# Track usage
+tracker = ThinkingTracker()
+session = tracker.start_session(budget_tokens=16000)
+tracker.end_session(session, tokens_used=12000)
+
+summary = tracker.get_summary()
+print(f"Utilization: {summary['average_utilization']:.1%}")
+```
+
+**CLI Commands:**
+```bash
+praisonai thinking status      # Show current budget
+praisonai thinking set high    # Set budget level
+praisonai thinking stats       # Show usage statistics
 ```
 
-### 10. Field Names Reference (A-I-G-S)
+**Links:**
+- [📖 Coding Docs](https://docs.praison.ai/features/thinking-budgets)
+- [📖 CLI Docs](https://docs.praison.ai/docs/cli/thinking)
+- [💻 Example](examples/thinking/basic_thinking.py)
+
+---
+
+### 14. Output Styles
+
+Configure how agents format their responses:
+
+```python
+from praisonaiagents.output import OutputStyle, OutputFormatter
+
+# Use preset styles
+style = OutputStyle.concise()
+formatter = OutputFormatter(style)
+
+# Format output
+text = "# Hello\n\nThis is **bold** text."
+plain = formatter.format(text)
+print(plain)
+```
+
+**CLI Commands:**
+```bash
+praisonai output status        # Show current style
+praisonai output set concise   # Set output style
+```
+
+**Links:**
+- [📖 Coding Docs](https://docs.praison.ai/features/output-styles)
+- [📖 CLI Docs](https://docs.praison.ai/docs/cli/output-style)
+- [💻 Example](examples/output/basic_output.py)
+
+---
+
+### 15. Context Compaction
+
+Automatically manage context window size:
+
+```python
+from praisonaiagents.compaction import (
+    ContextCompactor, CompactionStrategy
+)
+
+compactor = ContextCompactor(
+    max_tokens=4000,
+    strategy=CompactionStrategy.SLIDING,
+    preserve_recent=3
+)
+
+messages = [...]  # Your conversation history
+compacted, result = compactor.compact(messages)
+
+print(f"Compression: {result.compression_ratio:.1%}")
+```
+
+**CLI Commands:**
+```bash
+praisonai compaction status        # Show settings
+praisonai compaction set sliding   # Set strategy
+praisonai compaction stats         # Show statistics
+```
+
+**Links:**
+- [📖 Coding Docs](https://docs.praison.ai/features/context-compaction)
+- [📖 CLI Docs](https://docs.praison.ai/docs/cli/compaction)
+- [💻 Example](examples/compaction/basic_compaction.py)
+
+---
+
+### 16. Field Names Reference (A-I-G-S)
 
 PraisonAI accepts both old (agents.yaml) and new (workflow.yaml) field names. Use the **canonical names** for new projects:
 
@@ -1008,7 +1251,7 @@ steps:                         # Define steps (not 'tasks')
 
 > **Note:** The parser accepts both old and new names. Run `praisonai workflow validate <file.yaml>` to see suggestions for canonical names.
 
-### 11. Extended agents.yaml with Workflow Patterns
+### 12. Extended agents.yaml with Workflow Patterns
 
 **Feature Parity:** Both `agents.yaml` and `workflow.yaml` now support the same features:
 - All workflow patterns (route, parallel, loop, repeat)
@@ -2578,6 +2821,103 @@ PraisonAI provides zero-dependency persistent memory for agents. For detailed ex
 
 ---
 
+## 💾 Persistence (Databases)
+
+Enable automatic conversation persistence with 2 lines of code:
+
+```python
+from praisonaiagents import Agent, db
+
+agent = Agent(
+    name="Assistant",
+    db=db(database_url="postgresql://localhost/mydb"),  # db(...) shortcut
+    session_id="my-session"  # Optional: defaults to per-hour ID (YYYYMMDDHH)
+)
+agent.chat("Hello!")  # Auto-persists messages, runs, traces
+```
+
+### Persistence CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `praisonai persistence doctor` | Validate DB connectivity |
+| `praisonai persistence run` | Run agent with persistence |
+| `praisonai persistence resume` | Resume existing session |
+| `praisonai persistence export` | Export session to JSONL |
+| `praisonai persistence import` | Import session from JSONL |
+| `praisonai persistence migrate` | Apply schema migrations |
+| `praisonai persistence status` | Show schema status |
+
+### Databases Table
+
+| Database | Store Type | Install | Example | Docs |
+|----------|------------|---------|---------|------|
+| PostgreSQL | Conversation | `pip install "praisonai[tools]"` | [simple_db_agent.py](examples/persistence/simple_db_agent.py) | [docs](https://docs.praison.ai/docs/databases/postgres) |
+| MySQL | Conversation | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
+| SQLite | Conversation | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
+| SingleStore | Conversation | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
+| Supabase | Conversation | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
+| SurrealDB | Conversation | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
+| Qdrant | Knowledge | `pip install "praisonai[tools]"` | [knowledge_qdrant.py](examples/persistence/knowledge_qdrant.py) | [docs](https://docs.praison.ai/docs/databases/qdrant) |
+| ChromaDB | Knowledge | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
+| Pinecone | Knowledge | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
+| Weaviate | Knowledge | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
+| LanceDB | Knowledge | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
+| Milvus | Knowledge | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
+| PGVector | Knowledge | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
+| Redis Vector | Knowledge | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
+| Cassandra | Knowledge | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
+| ClickHouse | Knowledge | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
+| Redis | State | `pip install "praisonai[tools]"` | [state_redis.py](examples/persistence/state_redis.py) | [docs](https://docs.praison.ai/docs/databases/redis) |
+| MongoDB | State | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
+| DynamoDB | State | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
+| Firestore | State | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
+| Upstash | State | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
+| Memory | State | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
+
+---
+
+## 🔧 Tools Table
+
+Install all tools with: `pip install "praisonai[tools]"`
+
+| Tool | Category | Import | Docs |
+|------|----------|--------|------|
+| Tavily | Web Search | `from praisonai_tools import TavilyTool` | [docs](https://docs.praison.ai/docs/tools/external/tavily) |
+| DuckDuckGo | Web Search | `from praisonai_tools import DuckDuckGoTool` | [docs](https://docs.praison.ai/docs/tools/external/duckduckgo) |
+| Exa | Web Search | `from praisonai_tools import ExaTool` | [docs](https://docs.praison.ai/docs/tools/external/exa) |
+| Serper | Web Search | `from praisonai_tools import SerperTool` | [docs](https://docs.praison.ai/docs/tools/external/serper) |
+| Jina | Web Reader | `from praisonai_tools import JinaTool` | [docs](https://docs.praison.ai/docs/tools/external/jina) |
+| Firecrawl | Web Scraping | `from praisonai_tools import FirecrawlTool` | [docs](https://docs.praison.ai/docs/tools/external/firecrawl) |
+| Crawl4AI | Web Scraping | `from praisonai_tools import Crawl4AITool` | [docs](https://docs.praison.ai/docs/tools/external/crawl4ai) |
+| Wikipedia | Knowledge | `from praisonai_tools import WikipediaTool` | [docs](https://docs.praison.ai/docs/tools/external/wikipedia) |
+| ArXiv | Research | `from praisonai_tools import ArxivTool` | [docs](https://docs.praison.ai/docs/tools/external/arxiv) |
+| HackerNews | News | `from praisonai_tools import HackerNewsTool` | [docs](https://docs.praison.ai/docs/tools/external/hackernews) |
+| YouTube | Media | `from praisonai_tools import YouTubeTool` | [docs](https://docs.praison.ai/docs/tools/external/youtube) |
+| Weather | Data | `from praisonai_tools import WeatherTool` | [docs](https://docs.praison.ai/docs/tools/external/weather) |
+| PostgreSQL | Database | `from praisonai_tools import PostgresTool` | [docs](https://docs.praison.ai/docs/tools/external/postgres) |
+| MySQL | Database | `from praisonai_tools import MySQLTool` | [docs](https://docs.praison.ai/docs/tools/external/mysql) |
+| SQLite | Database | `from praisonai_tools import SQLiteTool` | [docs](https://docs.praison.ai/docs/tools/external/sqlite) |
+| MongoDB | Database | `from praisonai_tools import MongoDBTool` | [docs](https://docs.praison.ai/docs/tools/external/mongodb) |
+| Redis | Database | `from praisonai_tools import RedisTool` | [docs](https://docs.praison.ai/docs/tools/external/redis) |
+| Qdrant | Vector DB | `from praisonai_tools import QdrantTool` | [docs](https://docs.praison.ai/docs/tools/external/qdrant) |
+| GitHub | DevOps | `from praisonai_tools import GitHubTool` | [docs](https://docs.praison.ai/docs/tools/external/github) |
+| Slack | Communication | `from praisonai_tools import SlackTool` | [docs](https://docs.praison.ai/docs/tools/external/slack) |
+| Discord | Communication | `from praisonai_tools import DiscordTool` | [docs](https://docs.praison.ai/docs/tools/external/discord) |
+| Telegram | Communication | `from praisonai_tools import TelegramTool` | [docs](https://docs.praison.ai/docs/tools/external/telegram) |
+| Email | Communication | `from praisonai_tools import EmailTool` | [docs](https://docs.praison.ai/docs/tools/external/email) |
+| Notion | Productivity | `from praisonai_tools import NotionTool` | [docs](https://docs.praison.ai/docs/tools/external/notion) |
+| File | File System | `from praisonai_tools import FileTool` | [docs](https://docs.praison.ai/docs/tools/external/file) |
+| Shell | System | `from praisonai_tools import ShellTool` | [docs](https://docs.praison.ai/docs/tools/external/shell) |
+| Python | Code | `from praisonai_tools import PythonTool` | [docs](https://docs.praison.ai/docs/tools/external/python) |
+| JSON | Data | `from praisonai_tools import JSONTool` | [docs](https://docs.praison.ai/docs/tools/external/json) |
+| CSV | Data | `from praisonai_tools import CSVTool` | [docs](https://docs.praison.ai/docs/tools/external/csv) |
+| Calculator | Math | `from praisonai_tools import CalculatorTool` | [docs](https://docs.praison.ai/docs/tools/external/calculator) |
+
+> See [full tools documentation](https://docs.praison.ai/docs/tools/tools) for all 100+ available tools.
+
+---
+
 ## 🎓 Video Tutorials
 
 Learn PraisonAI through our comprehensive video series: