Merge pull request #304 from desi003/add-research-assistant-example

Add research assistant example using AgentQL tool

examples/research_assistant/.env.example

@@ -0,0 +1,6 @@
+#AGENTOPS_API_KEY=...
+#OPENAI_API_KEY=...
+
+# Tools
+#FIRECRAWL_API_KEY=""
+AGENTQL_API_KEY=...

examples/research_assistant/.gitignore

@@ -0,0 +1,166 @@
+# 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/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# 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
+.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/
+
+.agentops/
+agentstack.log
+.agentstack*

examples/research_assistant/LICENSE.md

@@ -0,0 +1,10 @@
+
+MIT License
+
+Copyright (c) 2025 Name <Email>
+
+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.

examples/research_assistant/README.md

@@ -0,0 +1,37 @@
+# research_assistant
+
+
+## How to build your Crew Agent
+### With the CLI
+Add an agent using AgentStack with the CLI:  
+`agentstack generate agent <agent_name>`  
+You can also shorten this to `agentstack g a <agent_name>`  
+For wizard support use `agentstack g a <agent_name> --wizard`  
+Finally for creation in the CLI alone, use `agentstack g a <agent_name> --role/-r <role> --goal/-g <goal> --backstory/-b <backstory> --model/-m <provider/model>`
+
+This will automatically create a new agent in the `agents.yaml` config as well as in your code. Either placeholder strings will be used, or data included in the wizard.
+
+Similarly, tasks can be created with `agentstack g t <tool_name>`
+
+Add tools with `agentstack tools add` and view tools available with `agentstack tools list`
+
+## How to use your Agent
+In this directory, run `uv pip install --requirements pyproject.toml`
+
+To run your project, use the following command:  
+`agentstack run`
+
+This will initialize your crew of AI agents and begin task execution as defined in your configuration in the main.py file.
+
+#### Replay Tasks from Latest Crew Kickoff:
+
+CrewAI now includes a replay feature that allows you to list the tasks from the last run and replay from a specific one. To use this feature, run:  
+`crewai replay <task_id>`  
+Replace <task_id> with the ID of the task you want to replay.
+
+#### Reset Crew Memory
+If you need to reset the memory of your crew before running it again, you can do so by calling the reset memory feature:  
+`crewai reset-memory`  
+This will clear the crew's memory, allowing for a fresh start.
+
+> 🪩 Project built with [AgentStack](https://github.com/AgentOps-AI/AgentStack)

examples/research_assistant/agentstack.json

@@ -0,0 +1,12 @@
+{
+    "framework": "crewai",
+    "tools": [
+        "firecrawl",
+        "agentql"
+    ],
+    "default_model": "openai/gpt-4o",
+    "agentstack_version": "0.3.4",
+    "template": "research_assistant",
+    "template_version": "4",
+    "use_git": true
+}

examples/research_assistant/pyproject.toml

@@ -0,0 +1,14 @@
+[project]
+name = "research_assistant"
+version = "0.0.1"
+description = ""
+authors = [
+    { name = "Name <Email>" }
+]
+license = { text = "MIT" }
+requires-python = ">=3.10"
+
+dependencies = [
+    "agentstack[crewai]>=0.3.4",
+    "firecrawl-py>=1.6.4",
+]

examples/research_assistant/src/config/agents.yaml

@@ -0,0 +1,28 @@
+web_scraper:
+  role: >-
+    web scraper
+  goal: >-
+    Access the website and extract all relevant data asked for in a structured format.
+  backstory: >-
+    You are an expert web scraper data extractor.
+  llm: openai/gpt-4o
+researcher:
+  role: >-
+    researcher
+  goal: >-
+    Use your knowledge and experience to find relevant websites for information to answer the query.
+  backstory: >-
+    You are an expert researcher. You are given a query and are tasked with finding
+    as many relevant resources as possible to answer the query.
+  llm: openai/gpt-4o
+analyst:
+  role: >-
+    research analyst
+  goal: >-
+    Analyze and consolidate the data gathered from scraping websites to adequately answer the
+    query provided in the task.
+  backstory: >-
+    You are an expert analyst. You are given a collection of research results and
+    should use your knowledge to make conclusions on the data without making any assumptions
+    that are not specifically supported by the data.
+  llm: openai/gpt-4o

examples/research_assistant/src/config/inputs.yaml

@@ -0,0 +1,2 @@
+query: >-
+  Tell me about black holes and what are the current research on it?

examples/research_assistant/src/config/tasks.yaml

@@ -0,0 +1,25 @@
+scrape_site:
+  description: >-
+    Access the website through the specific URL links provided by the researcher and extract all relevant data asked 
+    for in a structured format.
+  expected_output: >-
+    A json file.
+  agent: >-
+    web_scraper
+analyze:
+  description: >-
+    Using the data scraped by the web scraper, analyze the data gathered and form a conclusion
+    that reports key insights on the data gathered and accurately answering the query: {query}
+  expected_output: >-
+    A report in a structured format outlining the key insights of the research and accurately
+    answering the query.
+  agent: >-
+    analyst
+research:
+  description: >-
+    Use the tools at your disposal to thoroughly research the query: {query}
+  expected_output: >-
+    A list of URL links to the sources where information to answer the query is found with queries
+    for each URL link to find the relevant information.
+  agent: >-
+    researcher

examples/research_assistant/src/crew.py

@@ -0,0 +1,64 @@
+from crewai import Agent, Crew, Process, Task
+from crewai.project import CrewBase, agent, crew, task
+import agentstack
+
+
+@CrewBase
+class ResearchassistantCrew:
+    """research_assistant crew"""
+
+    @agent
+    def researcher(self) -> Agent:
+        return Agent(
+            config=self.agents_config["researcher"],
+            tools=[
+                *agentstack.tools["firecrawl"],
+            ],  # add tools here or use `agentstack tools add <tool_name>
+            verbose=True,
+        )
+
+    @agent
+    def web_scraper(self) -> Agent:
+        return Agent(
+            config=self.agents_config["web_scraper"],
+            tools=[
+                *agentstack.tools["agentql"],
+            ],  # add tools here or use `agentstack tools add <tool_name>
+            verbose=True,
+        )
+
+    @agent
+    def analyst(self) -> Agent:
+        return Agent(
+            config=self.agents_config["analyst"],
+            tools=[],  # add tools here or use `agentstack tools add <tool_name>
+            verbose=True,
+        )
+
+    @task
+    def research(self) -> Task:
+        return Task(
+            config=self.tasks_config["research"],
+        )
+
+    @task
+    def scrape_site(self) -> Task:
+        return Task(
+            config=self.tasks_config["scrape_site"],
+        )
+
+    @task
+    def analyze(self) -> Task:
+        return Task(
+            config=self.tasks_config["analyze"],
+        )
+
+    @crew
+    def crew(self) -> Crew:
+        """Creates the Test crew"""
+        return Crew(
+            agents=self.agents,  # Automatically created by the @agent decorator
+            tasks=self.tasks,  # Automatically created by the @task decorator
+            process=Process.sequential,
+            verbose=True,
+        )