cave-agent 0.5.0__tar.gz

cave_agent-0.5.0/.gitignore

@@ -0,0 +1,210 @@
+# Created by https://www.toptal.com/developers/gitignore/api/macos,python
+# Edit at https://www.toptal.com/developers/gitignore?templates=macos,python
+
+### macOS ###
+# General
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+### macOS Patch ###
+# iCloud generated files
+*.icloud
+
+### Python ###
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.env.*
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+### Python Patch ###
+# Poetry local configuration file - https://python-poetry.org/docs/configuration/#local-configuration
+poetry.toml
+
+# ruff
+.ruff_cache/
+
+# LSP config files
+pyrightconfig.json
+
+# End of https://www.toptal.com/developers/gitignore/api/macos,python

cave_agent-0.5.0/CONTRIBUTING.md

@@ -0,0 +1,21 @@
+## Contribute to CaveAgent
+
+We welcome contributions to CaveAgent! Here's how you can help:
+
+### Types of Contributions
+
+- Bug fixes
+- Feature additions
+- Documentation improvements
+- Test coverage improvements
+
+### Development Process
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Run tests to ensure everything works
+5. Commit your changes (`git commit -m 'Add amazing feature'`)
+6. Push to your branch (`git push origin feature/amazing-feature`)
+7. Open a Pull Request
+

cave_agent-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ram, Copper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cave_agent-0.5.0/PKG-INFO

@@ -0,0 +1,346 @@
+Metadata-Version: 2.4
+Name: cave-agent
+Version: 0.5.0
+Summary: A Python agent framework that enables function-calling through LLM code generation
+Project-URL: Homepage, https://github.com/acodercat/cave-agent
+Project-URL: Repository, https://github.com/acodercat/cave-agent
+Author-email: Ram <codermao@gmail.com>, Cooper <cooperimmaculate@gmail.com>
+License-File: LICENSE
+Keywords: agent,function-calling,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: ipython>=9.0.2
+Requires-Dist: rich>=13.9.4
+Provides-Extra: all
+Requires-Dist: litellm>=1.73.0; extra == 'all'
+Requires-Dist: openai>=1.91.0; extra == 'all'
+Provides-Extra: litellm
+Requires-Dist: litellm>=1.73.0; extra == 'litellm'
+Provides-Extra: openai
+Requires-Dist: openai>=1.91.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# 🤖 CaveAgent
+**🚀 AI that executes, not just generates!**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![PyPI version](https://img.shields.io/badge/pypi-0.4.4-blue.svg)](https://pypi.org/project/cave-agent)
+
+CaveAgent is a tool-augmented agent framework that enables function-calling through LLM code generation and provides runtime state management. Unlike traditional JSON-schema approaches, it leverages LLM's inherent coding capabilities to interact with tools through a Python runtime environment, allowing direct access to execution results and runtime state.
+
+> *"When your AI needs to run code, not just write it"*
+
+## Why CaveAgent?
+
+**Traditional function calling is broken.** JSON schemas are rigid, error-prone, and limit what your AI can do. CaveAgent unleashes your LLM's natural coding abilities:
+
+- 🧠 **Native Code Generation** - LLMs excel at writing code, not parsing JSON
+- ⚡ **Fewer Iterations** - Execute complex multi-step workflows in a single turn
+- 🔄 **Persistent State** - Maintain variables and objects across conversations  
+- 🎯 **Maximum Flexibility** - Handle dynamic workflows that JSON schemas can't express
+- 🛡️ **Secure by Design** - AST validation prevents dangerous code execution
+- 📡 **Real-time Streaming** - Watch your AI think and execute in real-time
+- 🌐 **Universal LLM Support** - Works with OpenAI, Anthropic, Google, and 100+ providers
+
+## Quick Start
+
+```bash
+pip install 'cave-agent[all]'
+```
+
+Choose your installation:
+
+```bash
+# OpenAI support
+pip install 'cave-agent[openai]'
+
+# 100+ LLM providers via LiteLLM 
+pip install 'cave-agent[litellm]'
+```
+
+### Simple Function Calling
+
+```python
+import asyncio
+from cave_agent import CaveAgent
+from cave_agent.models import OpenAIServerModel
+from cave_agent.python_runtime import PythonRuntime, Function, Variable
+
+async def main():
+    # Initialize LLM model
+    model = OpenAIServerModel(
+        model_id="your-model",
+        api_key="your-api-key",
+        base_url="your-base-url"
+    )
+
+    # Define tool functions
+    def add_task(task_name: str) -> str:
+        """Add a new task to the task list"""
+        tasks.append({"name": task_name, "done": False})
+        return f"Added task: {task_name}"
+
+    def complete_task(task_name: str) -> str:
+        """Mark a task as completed"""
+        for task in tasks:
+            if task_name.lower() in task["name"].lower():
+                task["done"] = True
+                return f"Completed: {task['name']}"
+        return f"Task '{task_name}' not found"
+
+    def send_reminder(message: str) -> str:
+        """Send a reminder notification"""
+        return f"Reminder: {message}"
+
+    # Initialize data
+    tasks = []
+
+    # Setup Runtime
+    runtime = PythonRuntime(
+        variables=[
+            Variable("tasks", tasks, "List of user's tasks. Example: [{'name': 'walk the dog', 'done': False}]")
+        ],
+        functions=[
+            Function(add_task),
+            Function(complete_task), 
+            Function(send_reminder)
+        ]
+    )
+
+    agent = CaveAgent(model, runtime=runtime)
+
+    await agent.run("Add buy groceries and call mom to my tasks")
+    print(f"Current tasks: {runtime.get_variable_value('tasks')}")
+
+    await agent.run("Mark groceries done and remind me about mom")
+    print(f"Final state: {runtime.get_variable_value('tasks')}")
+
+    response = await agent.run("What's my progress?")
+    print(response.content)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Advanced: Stateful Object Interactions
+
+```python
+import asyncio
+from cave_agent import CaveAgent
+from cave_agent.models import LiteLLMModel
+from cave_agent.python_runtime import PythonRuntime, Function, Variable
+
+async def main():
+    # Initialize LLM model
+    model = LiteLLMModel(
+        model_id="your-model",
+        api_key="your-api-key",
+        base_url="your-base-url"
+    )
+
+    # Define a class with methods
+    class DataProcessor:
+        """A utility class for processing and filtering data collections.
+        
+        This class provides methods for basic data processing operations such as
+        sorting, removing duplicates, and filtering based on thresholds.
+        
+        Example:
+            >>> processor = DataProcessor()
+            >>> processor.process_list([3, 1, 2, 1, 3])
+            [1, 2, 3]
+            >>> processor.filter_numbers([1, 5, 3, 8, 2], 4)
+            [5, 8]
+        """
+        def process_list(self, data: list) -> list:
+            """Sort a list and remove duplicates"""
+            return sorted(set(data))
+        
+        def filter_numbers(self, data: list, threshold: int) -> list:
+            """Filter numbers greater than threshold"""
+            return [x for x in data if x > threshold]
+
+    # Prepare context
+    processor = DataProcessor()
+    numbers = [3, 1, 4, 1, 5, 9, 2, 6, 5]
+
+    # Create runtime with variables and functions
+    runtime = PythonRuntime(
+        variables=[
+            Variable(
+                name="processor",
+                value=processor,
+                description="Data processing tool with various methods"
+            ),
+            Variable(
+                name="numbers",
+                value=numbers,
+                description="Input list of numbers"
+            ),
+            Variable(
+                name="processed_data",
+                description="Store processed data in this variable"
+            ),
+            Variable(
+                name="filtered_data",
+                description="Store filtered data in this variable"
+            )
+        ]
+    )
+
+    # Create agent
+    agent = CaveAgent(model, runtime=runtime)
+
+    # Process data
+    await agent.run("Use processor to sort and deduplicate numbers")
+    processed_data = agent.runtime.get_variable_value('processed_data')
+    print("Processed data:", processed_data)
+
+    # Filter data
+    await agent.run("Filter numbers greater than 4")
+    filtered_data = agent.runtime.get_variable_value('filtered_data')
+    print("Filtered data:", filtered_data)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Real-time Streaming
+
+Watch your AI think and execute code in real-time:
+
+```python
+async for event in agent.stream_events("Analyze this data and create a summary"):
+    if event.type.value == 'CODE':
+        print(f"🔧 Executing: {event.content}")
+    elif event.type.value == 'EXECUTION_RESULT':
+        print(f"✅ Result: {event.content}")
+    elif event.type.value == 'TEXT':
+        print(event.content, end="", flush=True)
+```
+
+### Security Features
+
+CaveAgent includes rule-based security to prevent dangerous code execution:
+
+```python
+import asyncio
+from cave_agent import CaveAgent
+from cave_agent.models import OpenAIServerModel
+from cave_agent.python_runtime import PythonRuntime
+from cave_agent.security_checker import (
+    SecurityChecker, ImportRule, FunctionRule, AttributeRule, RegexRule
+)
+
+async def main():
+    model = OpenAIServerModel(
+        model_id="gpt-4",
+        api_key="your-api-key",
+        base_url="https://api.openai.com/v1"
+    )
+
+    # Configure security with specific rules
+    rules = [
+        ImportRule({"os", "subprocess", "sys", "socket"}),  # Block dangerous imports
+        FunctionRule({"eval", "exec", "compile", "open"}),  # Block dangerous functions
+        AttributeRule({"__globals__", "__builtins__"}),     # Block attribute access
+        RegexRule("no_print", "Block print statements", r"print\s*\(")  # Custom regex
+    ]
+    
+    checker = SecurityChecker(rules)
+    runtime = PythonRuntime(security_checker=checker)
+    
+    agent = CaveAgent(model, runtime=runtime)
+    
+    # This will be blocked by security
+    try:
+        await agent.run("import os and list files")
+    except Exception as e:
+        print(f"Blocked: {e}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Key Features
+
+- **🤖 Code-Based Function Calling**: Leverages LLM's natural coding abilities instead of rigid JSON schemas
+- **🛡️ Secure Runtime Environment**: 
+  - Inject Python objects, variables, and functions as tools
+  - Rule-based security validation prevents dangerous code execution
+  - Flexible security rules: ImportRule, FunctionRule, AttributeRule, RegexRule
+  - Customizable security policies for different use cases
+  - Access execution results and maintain state across interactions
+- **💬 Multi-Turn Conversations**: Persistent context and runtime state across multiple interactions
+- **⚡ Streaming & Async**: Real-time event streaming and full async/await support for optimal performance
+- **🛡️ Execution Control**: Configurable step limits and error handling to prevent infinite loops
+- **🎯 Unmatched Flexibility**: JSON schemas break with dynamic workflows. Python code adapts to any situation - conditional logic, loops, and complex data transformations.
+- **🌐 Flexible LLM Support**: Works with any LLM provider via OpenAI-compatible APIs or LiteLLM
+
+## Real-World Examples
+
+For more examples, check out the [examples](examples) directory:
+
+- [Basic Usage](examples/basic_usage.py): Simple function calling and object processing
+- [Runtime State](examples/runtime_state.py): Managing runtime state across interactions
+- [Object Methods](examples/object_methods.py): Using class methods and complex objects
+- [Multi-Turn](examples/multi_turn.py): Complex analysis conversations with state persistence
+- [Stream](examples/stream.py): Streaming responses and execution events
+
+## LLM Provider Support
+
+CaveAgent supports multiple LLM providers:
+
+### OpenAI-Compatible Models
+```python
+from cave_agent.models import OpenAIServerModel
+
+model = OpenAIServerModel(
+    model_id="gpt-4",
+    api_key="your-api-key",
+    base_url="https://api.openai.com/v1"  # or your custom endpoint
+)
+```
+
+### LiteLLM Models (Recommended)
+LiteLLM provides unified access to hundreds of LLM providers:
+
+```python
+from cave_agent.models import LiteLLMModel
+
+# OpenAI
+model = LiteLLMModel(
+    model_id="gpt-4",
+    api_key="your-api-key"，
+    custom_llm_provider='openai'
+)
+
+# Anthropic Claude
+model = LiteLLMModel(
+    model_id="claude-3-sonnet-20240229",
+    api_key="your-api-key",
+    custom_llm_provider='anthropic' 
+)
+
+# Google Gemini
+model = LiteLLMModel(
+    model_id="gemini/gemini-pro",
+    api_key="your-api-key"
+)
+```
+
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a PR.
+For more details, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.