quantalogic 0.2.26__py3-none-any.whl → 0.2.29__py3-none-any.whl

quantalogic/tools/sql_query_tool.py

@@ -0,0 +1,167 @@
+"""Tool for executing SQL queries and returning paginated results in markdown format."""
+
+from typing import Any, Dict, List
+
+from pydantic import Field, ValidationError
+from sqlalchemy import create_engine, text
+from sqlalchemy.exc import SQLAlchemyError
+
+from quantalogic.tools.tool import Tool, ToolArgument
+
+
+class SQLQueryTool(Tool):
+    """Tool for executing SQL queries and returning paginated results in markdown format."""
+
+    name: str = "sql_query_tool"
+    description: str = (
+        "Executes a SQL query and returns results in markdown table format "
+        "with pagination support. Results are truncated based on start/end row numbers."
+    )
+    arguments: list = [
+        ToolArgument(
+            name="query",
+            arg_type="string",
+            description="The SQL query to execute",
+            required=True,
+            example="SELECT * FROM customers WHERE country = 'France'"
+        ),
+        ToolArgument(
+            name="start_row",
+            arg_type="int",
+            description="1-based starting row number for results",
+            required=True,
+            example="1"
+        ),
+        ToolArgument(
+            name="end_row",
+            arg_type="int",
+            description="1-based ending row number for results",
+            required=True,
+            example="100"
+        ),
+    ]
+    connection_string: str = Field(
+        ...,
+        description="SQLAlchemy-compatible database connection string",
+        example="postgresql://user:password@localhost/mydb"
+    )
+
+    def execute(self, query: str, start_row: Any, end_row: Any) -> str:
+        """
+        Executes a SQL query and returns formatted results.
+        
+        Args:
+            query: SQL query to execute
+            start_row: 1-based starting row number (supports various numeric types)
+            end_row: 1-based ending row number (supports various numeric types)
+            
+        Returns:
+            str: Markdown-formatted results with pagination metadata
+            
+        Raises:
+            ValueError: For invalid parameters or query errors
+            RuntimeError: For database connection issues
+        """
+        try:
+            # Convert and validate row numbers
+            start = self._convert_row_number(start_row, "start_row")
+            end = self._convert_row_number(end_row, "end_row")
+            
+            if start > end:
+                raise ValueError(f"start_row ({start}) must be <= end_row ({end})")
+
+            # Execute query
+            engine = create_engine(self.connection_string)
+            with engine.connect() as conn:
+                result = conn.execute(text(query))
+                columns: List[str] = result.keys()
+                all_rows: List[Dict] = [dict(row._mapping) for row in result]
+
+            # Apply pagination
+            total_rows = len(all_rows)
+            actual_start = max(1, start)
+            actual_end = min(end, total_rows)
+            
+            if actual_start > total_rows:
+                return f"No results found (total rows: {total_rows})"
+
+            # Slice results (convert to 0-based index)
+            displayed_rows = all_rows[actual_start-1:actual_end]
+
+            # Format results
+            markdown = [
+                f"**Query Results:** `{actual_start}-{actual_end}` of `{total_rows}` rows",
+                self._format_table(columns, displayed_rows)
+            ]
+
+            # Add pagination notice
+            if actual_end < total_rows:
+                remaining = total_rows - actual_end
+                markdown.append(f"\n*Showing first {actual_end} rows - {remaining} more row{'s' if remaining > 1 else ''} available*")
+
+            return "\n".join(markdown)
+
+        except SQLAlchemyError as e:
+            raise ValueError(f"SQL Error: {str(e)}") from e
+        except ValidationError as e:
+            raise ValueError(f"Validation Error: {str(e)}") from e
+        except Exception as e:
+            raise RuntimeError(f"Database Error: {str(e)}") from e
+
+    def _convert_row_number(self, value: Any, field_name: str) -> int:
+        """Convert and validate row number input."""
+        try:
+            # Handle numeric strings and floats
+            if isinstance(value, str):
+                if "." in value:
+                    num = float(value)
+                else:
+                    num = int(value)
+            else:
+                num = value
+
+            converted = int(num)
+            if converted != num:  # Check if float had decimal part
+                raise ValueError("Decimal values are not allowed for row numbers")
+                
+            if converted <= 0:
+                raise ValueError(f"{field_name} must be a positive integer")
+                
+            return converted
+        except (ValueError, TypeError) as e:
+            raise ValueError(f"Invalid value for {field_name}: {repr(value)}") from e
+
+    def _format_table(self, columns: List[str], rows: List[Dict]) -> str:
+        """Format results as markdown table with truncation."""
+        if not rows:
+            return "No results found"
+
+        # Create header
+        header = "| " + " | ".join(columns) + " |"
+        separator = "| " + " | ".join(["---"] * len(columns)) + " |"
+        
+        # Create rows with truncation
+        body = []
+        for row in rows:
+            values = []
+            for col in columns:
+                val = str(row.get(col, ""))
+                # Truncate long values
+                values.append(val[:50] + "..." if len(val) > 50 else val)
+            body.append("| " + " | ".join(values) + " |")
+
+        return "\n".join([header, separator] + body)
+
+
+
+if __name__ == "__main__":
+    from quantalogic.tools.utils.create_sample_database import create_sample_database
+
+    # Create and document sample database
+    create_sample_database("sample.db")
+    tool = SQLQueryTool(connection_string="sqlite:///sample.db")
+    print(tool.execute("select * from customers", 1, 10))
+    print(tool.execute("select * from customers", 11, 20))
+     
+    
+    

quantalogic/tools/utils/__init__.py

@@ -0,0 +1,13 @@
+"""
+Utility functions and classes for quantalogic tools.
+
+This module provides common utility functions used across the quantalogic package.
+"""
+
+from .create_sample_database import create_sample_database
+from .generate_database_report import generate_database_report
+
+__all__ = [
+    'create_sample_database',
+    'generate_database_report'
+]

quantalogic/tools/utils/create_sample_database.py

@@ -0,0 +1,124 @@
+import random
+from datetime import datetime, timedelta
+
+from faker import Faker
+from sqlalchemy import Column, Date, Float, ForeignKey, Integer, String, create_engine
+from sqlalchemy.orm import declarative_base, relationship, sessionmaker
+
+Base = declarative_base()
+fake = Faker()
+
+def create_sample_database(db_path: str) -> None:
+    """
+    Creates a sample SQLite database with 5 tables and 10 rows each.
+    
+    Args:
+        db_path: Path to the SQLite database file (e.g., 'sample.db')
+    """
+    # Define database schema
+    class Customer(Base):
+        __tablename__ = 'customers'
+        id = Column(Integer, primary_key=True)
+        name = Column(String)
+        email = Column(String)
+        addresses = relationship("Address", back_populates="customer")
+        orders = relationship("Order", back_populates="customer")
+
+    class Address(Base):
+        __tablename__ = 'addresses'
+        id = Column(Integer, primary_key=True)
+        street = Column(String)
+        city = Column(String)
+        customer_id = Column(Integer, ForeignKey('customers.id'))
+        customer = relationship("Customer", back_populates="addresses")
+
+    class Product(Base):
+        __tablename__ = 'products'
+        id = Column(Integer, primary_key=True)
+        name = Column(String)
+        price = Column(Float)
+
+    class Order(Base):
+        __tablename__ = 'orders'
+        id = Column(Integer, primary_key=True)
+        order_date = Column(Date)
+        customer_id = Column(Integer, ForeignKey('customers.id'))
+        customer = relationship("Customer", back_populates="orders")
+        items = relationship("OrderItem", back_populates="order")
+
+    class OrderItem(Base):
+        __tablename__ = 'order_items'
+        id = Column(Integer, primary_key=True)
+        quantity = Column(Integer)
+        order_id = Column(Integer, ForeignKey('orders.id'))
+        product_id = Column(Integer, ForeignKey('products.id'))
+        order = relationship("Order", back_populates="items")
+        product = relationship("Product")
+
+    # Create database and tables
+    engine = create_engine(f'sqlite:///{db_path}')
+    Base.metadata.create_all(engine)
+    Session = sessionmaker(bind=engine)  # noqa: N806
+    session = Session()
+
+    # Generate sample data
+    try:
+        # Create 10 customers
+        customers = []
+        for _ in range(10):
+            customer = Customer(
+                name=fake.name(),
+                email=fake.email()
+            )
+            customers.append(customer)
+            session.add(customer)
+        
+        session.commit()
+
+        # Create 10 addresses (1 per customer)
+        for customer in customers:
+            address = Address(
+                street=fake.street_address(),
+                city=fake.city(),
+                customer=customer
+            )
+            session.add(address)
+        
+        # Create 10 products
+        products = []
+        for _ in range(10):
+            product = Product(
+                name=fake.word().capitalize(),
+                price=round(random.uniform(10, 1000), 2)
+            )
+            products.append(product)
+            session.add(product)
+        
+        # Create 10 orders (1 per customer)
+        orders = []
+        start_date = datetime.now() - timedelta(days=365)
+        for customer in customers:
+            order = Order(
+                order_date=fake.date_between(start_date=start_date),
+                customer=customer
+            )
+            orders.append(order)
+            session.add(order)
+        
+        # Create 10 order items (1 per order)
+        for order in orders:
+            order_item = OrderItem(
+                quantity=random.randint(1, 5),
+                order=order,
+                product=random.choice(products)
+            )
+            session.add(order_item)
+
+        session.commit()
+    finally:
+        session.close()
+
+# Example usage
+if __name__ == "__main__":
+    create_sample_database("sample.db")
+    print("Sample database created successfully!")

quantalogic/tools/utils/generate_database_report.py

@@ -0,0 +1,289 @@
+from datetime import UTC, datetime
+from typing import Dict, List
+
+import networkx as nx
+from sqlalchemy import create_engine, inspect, text
+from sqlalchemy.engine import Inspector
+
+
+def generate_database_report(connection_string: str) -> str:
+    """
+    Generates a comprehensive Markdown database documentation report with ER diagram.
+    
+    Args:
+        connection_string: SQLAlchemy-compatible database connection string
+        
+    Returns:
+        Markdown-formatted report as a string
+    """
+    # Setup database connection and inspection
+    engine = create_engine(connection_string)
+    inspector = inspect(engine)
+    
+    # Collect database metadata
+    db_metadata = {
+        'name': engine.url.database,
+        'dialect': engine.dialect.name,
+        'tables': inspector.get_table_names()
+    }
+    
+    # Initialize data structures
+    graph = nx.DiGraph()
+    table_metadata: Dict[str, dict] = {}
+    fk_relationships: List[dict] = []
+    sampled_ids: Dict[str, list] = {}
+    sample_data: Dict[str, list] = {}
+
+    # Collect schema metadata and relationships
+    for table in db_metadata['tables']:
+        columns = inspector.get_columns(table)
+        pk = inspector.get_pk_constraint(table).get('constrained_columns', [])
+        indexes = inspector.get_indexes(table)
+        fks = inspector.get_foreign_keys(table)
+        
+        # Process foreign keys
+        for fk in fks:
+            process_foreign_key(table, fk, inspector, graph, fk_relationships)
+        
+        table_metadata[table] = {
+            'columns': columns,
+            'primary_keys': pk,
+            'indexes': indexes,
+            'foreign_keys': fks
+        }
+
+    # Process tables in dependency order
+    sorted_tables = get_sorted_tables(graph, db_metadata['tables'])
+    
+    # Collect sample data with parent-child relationships
+    collect_sample_data(engine, sorted_tables, table_metadata, sample_data, sampled_ids)
+    
+    # Generate Markdown report
+    return generate_markdown_report(db_metadata, sorted_tables, table_metadata, 
+                                  fk_relationships, sample_data)
+
+
+def process_foreign_key(
+    table: str,
+    fk: dict,
+    inspector: Inspector,
+    graph: nx.DiGraph,
+    fk_relationships: List[dict]
+) -> None:
+    """Process and record foreign key relationships with cardinality information."""
+    src_col = fk['constrained_columns'][0]
+    tgt_table = fk['referred_table']
+    tgt_col = fk['referred_columns'][0]
+    
+    # Check uniqueness and nullability in source column
+    src_columns = inspector.get_columns(table)
+    src_col_meta = next(c for c in src_columns if c['name'] == src_col)
+    is_unique = src_col_meta.get('unique', False) or src_col in inspector.get_pk_constraint(table).get('constrained_columns', [])
+    is_nullable = src_col_meta['nullable']
+
+    fk_relationships.append({
+        'source_table': table,
+        'source_column': src_col,
+        'target_table': tgt_table,
+        'target_column': tgt_col,
+        'constraint_name': fk['name'],
+        'is_unique': is_unique,
+        'is_nullable': is_nullable
+    })
+    graph.add_edge(table, tgt_table)
+
+
+def get_sorted_tables(graph: nx.DiGraph, tables: List[str]) -> List[str]:
+    """Return tables sorted topologically with fallback to original order."""
+    try:
+        return list(nx.topological_sort(graph))
+    except nx.NetworkXUnfeasible:
+        return tables
+
+
+def collect_sample_data(
+    engine,
+    tables: List[str],
+    table_metadata: Dict[str, dict],
+    sample_data: Dict[str, list],
+    sampled_ids: Dict[str, list]
+) -> None:
+    """Collect sample data while maintaining referential integrity."""
+    for table in tables:
+        with engine.connect() as conn:
+            # Get parent samples
+            result = conn.execute(text(f"SELECT * FROM {table} LIMIT 5"))
+            samples = [dict(row._mapping) for row in result]
+            sample_data[table] = samples
+            
+            # Store IDs for child sampling
+            if samples and table_metadata[table]['primary_keys']:
+                pk_col = table_metadata[table]['primary_keys'][0]
+                sampled_ids[table] = [row[pk_col] for row in samples]
+
+
+def generate_markdown_report(
+    db_metadata: dict,
+    tables: List[str],
+    table_metadata: Dict[str, dict],
+    fk_relationships: List[dict],
+    sample_data: Dict[str, list]
+) -> str:
+    """Generate the complete Markdown report."""
+    md = []
+    
+    # Database Summary
+    md.append("# Database Documentation Report\n")
+    md.append(f"**Database Type**: {db_metadata['dialect'].capitalize()}\n")
+    md.append(f"**Database Name**: {db_metadata['name']}\n")
+    md.append(f"**Total Tables**: {len(db_metadata['tables'])}\n")
+    md.append(f"**Generated At**: {datetime.now(UTC).strftime('%Y-%m-%d %H:%M:%S UTC')}\n\n")
+    
+    # ERD Section
+    md.append("## Entity Relationship Diagram\n")
+    md.append("```mermaid\nerDiagram\n")
+    generate_erd_section(md, tables, table_metadata, fk_relationships)
+    md.append("```\n\n")
+    
+    # Schema Details
+    md.append("## Schema Details\n")
+    for table in tables:
+        meta = table_metadata[table]
+        md.append(f"### {table}\n")
+        generate_columns_section(md, meta)
+        generate_indexes_section(md, meta)
+    
+    # Relationships
+    generate_relationships_section(md, fk_relationships)
+    
+    # Cardinality Report
+    generate_cardinality_section(md, fk_relationships)
+    
+    # Data Samples
+    md.append("## Data Samples\n")
+    for table in tables:
+        samples = sample_data[table]
+        md.append(f"### {table}\n")
+        generate_sample_table(md, samples)
+    
+    return '\n'.join(md)
+
+
+def generate_erd_section(md: List[str], tables: List[str], table_metadata: Dict[str, dict], fk_relationships: List[dict]) -> None:
+    """Generate Mermaid ER diagram section."""
+    # Define tables with their columns
+    for table in tables:
+        table_upper = table.upper()
+        md.append(f"    {table_upper} {{\n")
+        for col in table_metadata[table]['columns']:
+            col_type = str(col['type']).split('(')[0].upper()  # Simplify type names
+            annotations = []
+            if col['name'] in table_metadata[table]['primary_keys']:
+                annotations.append("PK")
+            # Check if column is a foreign key
+            for fk in fk_relationships:
+                if fk['source_table'] == table and fk['source_column'] == col['name']:
+                    annotations.append("FK")
+                    break
+            annotation_str = " ".join(annotations)
+            md.append(f"        {col_type} {col['name']} {annotation_str}\n")
+        md.append("    }\n")
+    
+    # Define relationships with cardinality
+    for fk in fk_relationships:
+        target_table = fk['target_table'].upper()
+        source_table = fk['source_table'].upper()
+        source_cardinality = get_source_cardinality(fk['is_unique'], fk['is_nullable'])
+        md.append(f"    {target_table} ||--{source_cardinality} {source_table} : \"{fk['constraint_name']}\"\n")
+
+
+def get_source_cardinality(is_unique: bool, is_nullable: bool) -> str:
+    """Determine Mermaid cardinality symbol for source side of relationship."""
+    if is_unique:
+        return "|o" if is_nullable else "||"
+    else:
+        return "o{" if is_nullable else "|{"
+
+
+def generate_relationships_section(md: List[str], fk_relationships: List[dict]) -> None:
+    """Generate foreign key relationships section."""
+    if fk_relationships:
+        md.append("## Relationships\n")
+        for fk in fk_relationships:
+            src = f"{fk['source_table']}.{fk['source_column']}"
+            tgt = f"{fk['target_table']}.{fk['target_column']}"
+            md.append(f"- `{src}` → `{tgt}` (Constraint: `{fk['constraint_name']}`)\n")
+        md.append("\n")
+
+
+def generate_cardinality_section(md: List[str], fk_relationships: List[dict]) -> None:
+    """Generate cardinality report section."""
+    cardinalities = {}
+    for fk in fk_relationships:
+        key = (fk['target_table'], fk['source_table'])
+        if key in cardinalities:
+            continue
+            
+        if fk['is_unique']:
+            cardinality = "(1) → (1)"
+        else:
+            cardinality = "(1) → (N)"
+            
+        cardinalities[key] = f"{fk['target_table']} {cardinality} {fk['source_table']}"
+    
+    if cardinalities:
+        md.append("## Cardinality Report\n")
+        for entry in cardinalities.values():
+            md.append(f"- {entry}\n")
+        md.append("\n")
+
+
+def generate_columns_section(md: List[str], meta: dict) -> None:
+    """Generate columns table section."""
+    md.append("#### Columns\n")
+    md.append("| Column Name | Data Type | Nullable? | Primary Key? |\n")
+    md.append("|-------------|-----------|-----------|--------------|\n")
+    for col in meta['columns']:
+        pk = "Yes" if col['name'] in meta['primary_keys'] else "No"
+        md.append(f"| `{col['name']}` | {col['type']} | {'Yes' if col['nullable'] else 'No'} | {pk} |\n")
+    md.append("\n")
+
+
+def generate_indexes_section(md: List[str], meta: dict) -> None:
+    """Generate indexes section."""
+    if meta['indexes']:
+        md.append("#### Indexes\n")
+        for idx in meta['indexes']:
+            columns = ", ".join(idx['column_names'])
+            md.append(f"- `{idx['name']}` ({idx['type'] or 'INDEX'}) → {columns}\n")
+        md.append("\n")
+
+
+def generate_sample_table(md: List[str], samples: list) -> None:
+    """Generate sample data table section."""
+    if not samples:
+        md.append("No records found.\n\n")
+        return
+        
+    headers = samples[0].keys()
+    md.append("| " + " | ".join(headers) + " |\n")
+    md.append("|" + "|".join(["---"] * len(headers)) + "|\n")
+    
+    for row in samples:
+        values = []
+        for val in row.values():
+            if isinstance(val, str) and len(val) > 50:
+                values.append(f"{val[:47]}...")
+            else:
+                values.append(str(val))
+        md.append("| " + " | ".join(values) + " |\n")
+    md.append("\n")
+
+
+if __name__ == "__main__":
+    from quantalogic.tools.utils.create_sample_database import create_sample_database
+    
+    # Create and document sample database
+    create_sample_database("sample.db")
+    report = generate_database_report("sqlite:///sample.db")
+    print(report)

{quantalogic-0.2.26.dist-info → quantalogic-0.2.29.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: quantalogic
-Version: 0.2.26
+Version: 0.2.29
 Summary: QuantaLogic ReAct Agents
 Author: Raphaël MANSUY
 Author-email: raphael.mansuy@gmail.com
@@ -12,6 +12,7 @@ Requires-Dist: beautifulsoup4 (>=4.12.3,<5.0.0)
 Requires-Dist: boto3 (>=1.35.86,<2.0.0)
 Requires-Dist: click (>=8.1.8,<9.0.0)
 Requires-Dist: duckduckgo-search (>=7.2.1,<8.0.0)
+Requires-Dist: faker (>=33.3.1,<34.0.0)
 Requires-Dist: fastapi (>=0.115.6,<0.116.0)
 Requires-Dist: google-auth (>=2.20.0,<3.0.0)
 Requires-Dist: google-search-results (>=2.4.2,<3.0.0)
@@ -28,13 +29,16 @@ Requires-Dist: mkdocs-mermaid2-plugin (>=1.1.1,<2.0.0)
 Requires-Dist: mkdocs-minify-plugin (>=0.7.1,<0.8.0)
 Requires-Dist: mkdocstrings (>=0.24.0,<0.25.0)
 Requires-Dist: mkdocstrings-python (>=1.7.0,<2.0.0)
+Requires-Dist: networkx (>=3.4.2,<4.0.0)
 Requires-Dist: pathspec (>=0.12.1,<0.13.0)
 Requires-Dist: prompt-toolkit (>=3.0.48,<4.0.0)
 Requires-Dist: pydantic (>=2.10.4,<3.0.0)
 Requires-Dist: pymdown-extensions (>=10.3.1,<11.0.0)
+Requires-Dist: python-dotenv (>=1.0.1,<2.0.0)
 Requires-Dist: requests (>=2.32.3,<3.0.0)
 Requires-Dist: rich (>=13.9.4,<14.0.0)
 Requires-Dist: serpapi (>=0.1.5,<0.2.0)
+Requires-Dist: sqlalchemy (>=2.0.37,<3.0.0)
 Requires-Dist: tenacity (>=9.0.0,<10.0.0)
 Requires-Dist: toml (>=0.10.2,<0.11.0)
 Requires-Dist: tree-sitter (>=0.23.2,<0.24.0)
@@ -59,8 +63,10 @@ Description-Content-Type: text/markdown
 [![Documentation](https://img.shields.io/badge/docs-latest-brightgreen.svg)](https://quantalogic.github.io/quantalogic/)
 
 
+
 QuantaLogic is a  ReAct (Reasoning & Action) framework for building advanced AI agents. 
 
+
 It seamlessly integrates large language models (LLMs) with a robust tool system, enabling agents to understand, reason about, and execute complex tasks through natural language interaction.
 
 The `cli` version include coding capabilities comparable to Aider.
@@ -82,7 +88,7 @@ We created [QuantaLogic](https://www.quantalogic.app) because we saw a significa
 ## 🌟 Highlights
 
 - **ReAct Framework**: Advanced implementation combining LLM reasoning with concrete actions
-- **Universal LLM Support**: Integration with OpenAI, Anthropic, LM Studio, Bedrock, Ollama, DeepSeek V3, via LiteLLM
+- **Universal LLM Support**: Integration with OpenAI, Anthropic, LM Studio, Bedrock, Ollama, DeepSeek V3, DeepSeek R1, via LiteLLM. Example usage: `quantalogic --model-name deepseek/deepseek-reasoner` or `quantalogic --model-name openrouter/deepseek/deepseek-r1`
 - **Secure Tool System**: Docker-based code execution and file manipulation tools
 - **Real-time Monitoring**: Web interface with SSE-based event visualization
 - **Memory Management**: Intelligent context handling and optimization