{"id":17381841,"url":"https://github.com/jgravelle/pocketgroq","last_synced_at":"2026-01-16T08:07:16.223Z","repository":{"id":254865912,"uuid":"847751831","full_name":"jgravelle/pocketgroq","owner":"jgravelle","description":"PocketGroq is a powerful Python library that simplifies integration with the Groq API, offering advanced features for natural language processing, web scraping, and autonomous agent capabilities. Key Features  Seamless integration with Groq API for text generation and completion Chain of Thought (CoT) reasoning for complex problem-solving and more.","archived":false,"fork":false,"pushed_at":"2025-02-11T21:15:42.000Z","size":634,"stargazers_count":209,"open_issues_count":3,"forks_count":58,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-11-27T19:15:16.852Z","etag":null,"topics":["ai","api","autonomous-agent","chatbot","google","groq","inference","llm","web-scraping","web-search","wrapper"],"latest_commit_sha":null,"homepage":"https://j.gravelle","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jgravelle.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-26T13:32:30.000Z","updated_at":"2025-11-18T02:50:18.000Z","dependencies_parsed_at":"2024-09-14T11:20:21.253Z","dependency_job_id":"036664e9-a825-41d9-bd26-0a443e93764a","html_url":"https://github.com/jgravelle/pocketgroq","commit_stats":null,"previous_names":["jgravelle/pocketgroq"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/jgravelle/pocketgroq","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgravelle%2Fpocketgroq","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgravelle%2Fpocketgroq/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgravelle%2Fpocketgroq/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgravelle%2Fpocketgroq/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jgravelle","download_url":"https://codeload.github.com/jgravelle/pocketgroq/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgravelle%2Fpocketgroq/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28478047,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T06:30:42.265Z","status":"ssl_error","status_checked_at":"2026-01-16T06:30:16.248Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","api","autonomous-agent","chatbot","google","groq","inference","llm","web-scraping","web-search","wrapper"],"created_at":"2024-10-16T07:02:01.673Z","updated_at":"2026-01-16T08:07:16.076Z","avatar_url":"https://github.com/jgravelle.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# PocketGroq v0.5.6: Vision and Speech Processing Meets Autonomous Agents!\n![PocketGroq Logo](https://github.com/user-attachments/assets/d06b6aaf-400e-40db-bdaf-626aaa1040ef)\n\n## What's New in v0.5.6\n\n## Vision Capabilities\n\nPocketGroq now includes powerful vision analysis capabilities, allowing you to process both images and screen content:\n\n```python\nfrom pocketgroq import GroqProvider\n\ngroq = GroqProvider()\n\n# Analyze an image from URL\nimage_url = \"https://example.com/image.jpg\"\nresponse = groq.process_image(\n    prompt=\"What do you see in this image?\",\n    image_source=image_url\n)\n\nprint(f\"Analysis: {response}\")\n\n# Analyze your screen\nscreen_analysis = groq.process_image_desktop(\n    prompt=\"What applications are open on my screen?\"\n)\n\nprint(f\"Screen analysis: {screen_analysis}\")\n\n# Analyze specific screen region\nregion_analysis = groq.process_image_desktop_region(\n    prompt=\"What's in this part of the screen?\",\n    x1=0,    # Top-left corner\n    y1=0,    # Top-left corner\n    x2=400,  # Width\n    y2=300   # Height\n)\n\nprint(f\"Region analysis: {region_analysis}\")\n```\n\nYou can also have multi-turn conversations about images:\n\n```python\n# Start a conversation about an image\nmessages = [\n    {\n        \"role\": \"user\",\n        \"content\": [\n            {\n                \"type\": \"text\",\n                \"text\": \"What do you see in this image?\"\n            },\n            {\n                \"type\": \"image_url\",\n                \"image_url\": {\"url\": \"https://example.com/image.jpg\"}\n            }\n        ]\n    }\n]\n\nresponse1 = groq.process_image_conversation(messages=messages)\nprint(f\"First response: {response1}\")\n\n# Add follow-up question\nmessages.append({\n    \"role\": \"assistant\",\n    \"content\": response1\n})\nmessages.append({\n    \"role\": \"user\",\n    \"content\": \"What colors are most prominent?\"\n})\n\nresponse2 = groq.process_image_conversation(messages=messages)\nprint(f\"Second response: {response2}\")\n```\n\n## Speech Processing\n\nPocketGroq now supports advanced speech processing with transcription and translation capabilities:\n\n```python\nfrom pocketgroq import GroqProvider\n\ngroq = GroqProvider()\n\n# Transcribe audio\nresponse = groq.transcribe_audio(\n    audio_file=\"recording.wav\",\n    language=\"en\",\n    model=\"distil-whisper-large-v3-en\"  # Fastest for English\n)\n\nprint(f\"Transcription: {response}\")\n\n# Translate audio to English\ntranslation = groq.translate_audio(\n    audio_file=\"french_speech.wav\",\n    model=\"whisper-large-v3\",  # Required for translation\n    prompt=\"This is a French conversation about cooking.\"\n)\n\nprint(f\"Translation: {translation}\")\n```\n\n### Speech Model Selection\n\nPocketGroq offers three Whisper models with different capabilities:\n\n* `whisper-large-v3`: Best for multilingual tasks and translation ($0.111/hour)\n* `whisper-large-v3-turbo`: Fast multilingual transcription without translation ($0.04/hour)\n* `distil-whisper-large-v3-en`: Fastest English-only transcription ($0.02/hour)\n\nChoose your model based on your needs:\n- For translation: Use `whisper-large-v3`\n- For fast multilingual transcription: Use `whisper-large-v3-turbo`\n- For English-only transcription: Use `distil-whisper-large-v3-en`\n\n### Additional Speech Settings\n\nFine-tune your speech processing:\n\n```python\n# Transcription with advanced options\nresponse = groq.transcribe_audio(\n    audio_file=\"recording.wav\",\n    language=\"en\",              # Specify language\n    prompt=\"Technical terms\",   # Context for better accuracy\n    response_format=\"json\",     # 'json' or 'text'\n    temperature=0.3            # Control variation\n)\n\n# Translation with custom settings\ntranslation = groq.translate_audio(\n    audio_file=\"speech.wav\",\n    prompt=\"Medical terminology\",  # Context for accuracy\n    response_format=\"json\",        # Structured output\n    temperature=0              # Maximum accuracy\n)\n```\n\n## What's NEW in v0.5.4!\n\n## Autonomous Agent\n\nPocketGroq now includes an AutonomousAgent class that can autonomously research and answer questions:\n\n```python\nfrom pocketgroq import GroqProvider\nfrom pocketgroq.autonomous_agent import AutonomousAgent\n\ngroq = GroqProvider()\nagent = AutonomousAgent(groq)\n\nrequest = \"What is the current temperature in Sheboygan, Wisconsin?\"\nresponse = agent.process_request(request)\n\nprint(f\"Final response: {response}\")\n```\n\nThe AutonomousAgent:\n- Attempts to answer the question using its initial knowledge.\n- If unsuccessful, it uses web search tools to find relevant information.\n- Evaluates each potential response for accuracy and completeness.\n- Keeps the user informed of its progress throughout the process.\n- Handles rate limiting and errors gracefully.\n\nYou can customize the agent's behavior:\n\n```python\n# Set a custom maximum number of sources to check\nagent = AutonomousAgent(groq, max_sources=10)\n\n# Or specify it for a single request\nresponse = agent.process_request(request, max_sources=8)\n```\n\nThe agent will search up to the specified number of sources, waiting at least 2 seconds between requests to avoid overwhelming the search services.\n\n### ALSO: get_available_models()\n\n(It does what you think it does.)\n\n## What's New in v0.4.9\n\n## Response Evaluation\n\nPocketGroq now includes a method to evaluate whether a response satisfies a given request using AI:\n\n```python\nfrom pocketgroq import GroqProvider\n\ngroq = GroqProvider()\n\nrequest = \"What is the current temperature in Sheboygan?\"\nresponse1 = \"58 degrees\"\nresponse2 = \"As a large language model, I do not have access to current temperature data\"\n\nis_satisfactory1 = groq.evaluate_response(request, response1)\nis_satisfactory2 = groq.evaluate_response(request, response2)\n\nprint(f\"Response 1 is satisfactory: {is_satisfactory1}\")  # Expected: True\nprint(f\"Response 2 is satisfactory: {is_satisfactory2}\")  # Expected: False\n```\n\nThis method uses an AI LLM to analyze the request-response pair and determine if the response is satisfactory based on informativeness, correctness, and lack of uncertainty.\n\n## What's New in v0.4.8\n\nPocketGroq v0.4.8 brings significant enhancements to web-related functionalities and improves the flexibility of Ollama integration:\n\n- **Advanced Web Scraping**: Improved capabilities for crawling websites and extracting content.\n- **Flexible Ollama Integration**: PocketGroq now operates more flexibly with or without an active Ollama server.\n- **Enhanced Web Search**: Upgraded web search functionality with more robust result parsing.\n- **Improved Error Handling**: Better management of web-related errors and Ollama server status.\n- **Updated Test Suite**: Comprehensive tests for new web capabilities and Ollama integration.\n\n## Web Capabilities\n\n### Web Crawling\n\nPocketGroq now offers advanced web crawling capabilities:\n\n```python\nfrom pocketgroq import GroqProvider\n\ngroq = GroqProvider()\n\n# Crawl a website\nresults = groq.crawl_website(\n    \"https://example.com\",\n    formats=[\"markdown\", \"html\"],\n    max_depth=2,\n    max_pages=5\n)\n\nfor page in results:\n    print(f\"URL: {page['url']}\")\n    print(f\"Title: {page['metadata']['title']}\")\n    print(f\"Markdown content: {page['markdown'][:100]}...\")  # First 100 characters\n    print(\"---\")\n```\n\n### URL Scraping\n\nExtract content from a single URL in various formats:\n\n```python\nurl = \"https://example.com\"\nresult = groq.scrape_url(url, formats=[\"markdown\", \"html\", \"structured_data\"])\n\nprint(f\"Markdown content length: {len(result['markdown'])}\")\nprint(f\"HTML content length: {len(result['html'])}\")\nif 'structured_data' in result:\n    print(\"Structured data:\", json.dumps(result['structured_data'], indent=2))\n```\n\n### Enhanced Web Search\n\nPerform web searches with improved result parsing:\n\n```python\nquery = \"Latest developments in AI\"\nsearch_results = groq.web_search(query)\n\nfor result in search_results:\n    print(f\"Title: {result['title']}\")\n    print(f\"URL: {result['url']}\")\n    print(f\"Description: {result['description']}\")\n    print(\"---\")\n```\n\n## Flexible Ollama Integration\n\nPocketGroq v0.4.8 introduces more flexible integration with Ollama:\n\n- **Optional Ollama**: Core features of PocketGroq now work without requiring an active Ollama server.\n- **Graceful Degradation**: When Ollama is not available, PocketGroq provides clear error messages for Ollama-dependent features.\n- **Persistent Features**: Ollama is still required for certain persistence features, including RAG functionality.\n\n### Initializing RAG with Flexible Ollama Integration\n\n```python\nfrom pocketgroq import GroqProvider\n\ngroq = GroqProvider()\n\ntry:\n    groq.initialize_rag()\n    print(\"RAG initialized successfully with Ollama.\")\nexcept OllamaServerNotRunningError:\n    print(\"Ollama server is not running. RAG features will be limited.\")\n    # Proceed with non-RAG features\n```\n\n## Error Handling\n\nPocketGroq v0.4.8 introduces a new exception for Ollama-related errors:\n\n```python\nfrom pocketgroq import GroqProvider, OllamaServerNotRunningError\n\ngroq = GroqProvider()\n\ntry:\n    groq.initialize_rag()\n    # Use RAG features\nexcept OllamaServerNotRunningError:\n    print(\"Ollama server is not running. Proceeding with limited functionality.\")\n    # Use non-RAG features\n```\n\n## Updated Test Suite\n\nThe test suite has been expanded to cover the new web capabilities and Ollama integration. To run the tests:\n\n1. Navigate to the PocketGroq directory.\n2. Run the test script:\n\n```bash\npython test.py\n```\n\n3. You will see an updated menu with options to run individual tests or groups of tests:\n\n```\nPocketGroq Test Menu:\n1. Basic Chat Completion\n2. Streaming Chat Completion\n3. Override Default Model\n4. Chat Completion with Stop Sequence\n5. Asynchronous Generation\n6. Streaming Async Chat Completion\n7. JSON Mode\n8. Tool Usage\n9. Vision\n10. Chain of Thought Problem Solving\n11. Chain of Thought Step Generation\n12. Chain of Thought Synthesis\n13. Test RAG Initialization\n14. Test Document Loading\n15. Test Document Querying\n16. Test RAG Error Handling\n17. Test Persistent Conversation\n18. Test Disposable Conversation\n19. Web Search\n20. Get Web Content\n21. Crawl Website\n22. Scrape URL\n23. Run All Web Tests\n24. Run All RAG Tests\n25. Run All Conversation Tests\n26. Run All Tests\n0. Exit\n```\n\n4. Select the desired option by entering the corresponding number.\n\n## Configuration\n\nPocketGroq uses environment variables for configuration. Set `GROQ_API_KEY` in your environment or in a `.env` file in your project root. This API key is essential for authenticating with the Groq API.\n\nAdditionally, you may need to set a `USER_AGENT` environment variable for certain web-related functionalities. Here are a couple of ways to set these variables:\n\n1. Using a `.env` file:\n\n```\nGROQ_API_KEY=your_api_key_here\nUSER_AGENT=Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36\n```\n\n2. Setting environment variables in your script:\n\n```python\nimport os\n\nos.environ['GROQ_API_KEY'] = 'your_api_key_here'\nos.environ['USER_AGENT'] = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36'\n```\n\nMake sure to keep your API key confidential and never commit it to version control.\n\n## Comprehensive List of PocketGroq Methods\n\nHere's a comprehensive list of all the methods/functions available in PocketGroq, grouped logically by function:\n\n### GroqProvider Class (Main Interface)\n\n#### Initialization and Configuration\n- `__init__(api_key: str = None, rag_persistent: bool = True, rag_index_path: str = \"faiss_index.pkl\")`: Initializes the GroqProvider with API key and RAG settings.\n- `set_api_key(api_key: str)`: Updates the API key and reinitializes the Groq clients.\n\n#### Text Generation\n- `generate(prompt: str, session_id: Optional[str] = None, **kwargs) -\u003e Union[str, AsyncIterator[str]]`: Generates text based on the given prompt.\n- `_create_completion(messages: List[Dict[str, str]], **kwargs) -\u003e Union[str, AsyncIterator[str]]`: Internal method for API call to Groq for text generation.\n- `_sync_create_completion(**kwargs) -\u003e Union[str, AsyncIterator[str]]`: Synchronous version of completion creation.\n- `_async_create_completion(**kwargs) -\u003e Union[str, AsyncIterator[str]]`: Asynchronous version of completion creation.\n\n#### Vision Processing\n- `process_image(prompt: str, image_source: str) -\u003e str`: Analyzes an image with given prompt.\n- `process_image_desktop(prompt: str, region=None) -\u003e str`: Analyzes screen content.\n- `process_image_desktop_region(prompt: str, x1: int, y1: int, x2: int, y2: int) -\u003e str`: Analyzes specific screen region.\n- `process_image_conversation(messages: List[Dict[str, Any]], model: str = None, **kwargs) -\u003e str`: Handles multi-turn conversations about images.\n\n#### Speech Processing\n- `transcribe_audio(audio_file: str, language: Optional[str] = None, model: str = \"distil-whisper-large-v3-en\", **kwargs) -\u003e str`: Transcribes audio to text.\n- `translate_audio(audio_file: str, model: str = \"whisper-large-v3\", **kwargs) -\u003e str`: Translates non-English audio to English text.\n\n#### Conversation Management\n- `start_conversation(session_id: str)`: Initializes a new conversation session.\n- `reset_conversation(session_id: str)`: Resets an existing conversation session.\n- `end_conversation(conversation_id: str)`: Ends and removes a conversation session.\n- `get_conversation_history(session_id: str) -\u003e List[Dict[str, str]]`: Retrieves conversation history.\n\n#### Web Tools\n- `web_search(query: str, num_results: int = 10) -\u003e List[Dict[str, Any]]`: Performs a web search.\n- `get_web_content(url: str) -\u003e str`: Retrieves content of a web page.\n- `is_url(text: str) -\u003e bool`: Checks if given text is a valid URL.\n- `crawl_website(url: str, formats: List[str] = [\"markdown\"], max_depth: int = 3, max_pages: int = 100) -\u003e List[Dict[str, Any]]`: Crawls a website.\n- `scrape_url(url: str, formats: List[str] = [\"markdown\"]) -\u003e Dict[str, Any]`: Scrapes a single URL.\n\n#### Chain of Thought Reasoning\n- `solve_problem_with_cot(problem: str, **kwargs) -\u003e str`: Solves a problem using Chain of Thought reasoning.\n- `generate_cot(problem: str, **kwargs) -\u003e List[str]`: Generates Chain of Thought steps.\n- `synthesize_cot(cot_steps: List[str], **kwargs) -\u003e str`: Synthesizes a final answer from CoT steps.\n\n#### RAG (Retrieval-Augmented Generation)\n- `initialize_rag(ollama_base_url: str = \"http://localhost:11434\", model_name: str = \"nomic-embed-text\", index_path: str = \"faiss_index.pkl\")`: Initializes the RAG system.\n- `load_documents(source: str, chunk_size: int = 1000, chunk_overlap: int = 200, progress_callback: Callable[[int, int], None] = None, timeout: int = 300, persistent: bool = None)`: Loads and processes documents for RAG.\n- `query_documents(query: str, session_id: Optional[str] = None, **kwargs) -\u003e str`: Queries loaded documents using RAG.\n\n#### Tool Management\n- `register_tool(name: str, func: callable)`: Registers a custom tool for use in text generation.\n\n#### Utility Methods\n- `is_ollama_server_running() -\u003e bool`: Checks if the Ollama server is running.\n- `ensure_ollama_server_running`: Decorator to ensure Ollama server is running for functions that require it.\n- `get_available_models() -\u003e List[Dict[str, Any]]`: Retrieves list of available models.\n- `evaluate_response(request: str, response: str) -\u003e bool`: Evaluates response quality.\n\n### WebTool Class\n- `search(query: str) -\u003e List[Dict[str, Any]]`: Performs a web search and returns filtered, deduplicated results.\n- `get_web_content(url: str) -\u003e str`: Retrieves and processes the content of a web page.\n- `is_url(text: str) -\u003e bool`: Checks if the given text is a valid URL.\n\n### EnhancedWebTool Class\n- `crawl(start_url: str, formats: List[str] = [\"markdown\"]) -\u003e List[Dict[str, Any]]`: Crawls a website and returns its content in specified formats.\n- `scrape_page(url: str, formats: List[str]) -\u003e Dict[str, Any]`: Scrapes a single page and returns its content in specified formats.\n\n### RAGManager Class\n- `load_and_process_documents(source: str, chunk_size: int = 1000, chunk_overlap: int = 200, progress_callback: Callable[[int, int], None] = None, timeout: int = 300)`: Loads, processes, and indexes documents for RAG.\n- `query_documents(llm, query: str) -\u003e Dict[str, Any]`: Queries the indexed documents using the provided language model.\n\n### ChainOfThoughtManager Class\n- `generate_cot(problem: str) -\u003e List[str]`: Generates Chain of Thought steps for a given problem.\n- `synthesize_response(cot_steps: List[str]) -\u003e str`: Synthesizes a final answer from Chain of Thought steps.\n- `solve_problem(problem: str) -\u003e str`: Completes the entire Chain of Thought process to solve a problem.\n\n### AutonomousAgent Class\n- `process_request(request: str, max_sources: int = None, verify: bool = False) -\u003e str`: Processes a request autonomously.\n- `_select_best_response(verified_sources: List[tuple], verify: bool) -\u003e str`: Selects the best response from verified sources.\n- `_generate_search_query(request: str) -\u003e str`: Generates an optimized search query.\n- `_evaluate_response(request: str, response: str) -\u003e bool`: Evaluates response quality.\n\n## License\n\nThis project is licensed under the MIT License. When using PocketGroq in your projects, please include a mention of J. Gravelle in your code and/or documentation.\n\n![J. Gravelle](https://github.com/user-attachments/assets/73c812cd-685e-4969-9497-639ae9312d6c)\n\n---\n\nThank you for using PocketGroq! We hope this tool enhances your development process and enables you to create amazing AI-powered applications with ease. If you have any questions or need further assistance, don't hesitate to reach out to the community or check the documentation. Happy coding!","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjgravelle%2Fpocketgroq","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjgravelle%2Fpocketgroq","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjgravelle%2Fpocketgroq/lists"}