diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..1fa7242 --- /dev/null +++ b/.env.example @@ -0,0 +1,2 @@ +DECODO_API_KEY= +OPENAI_API_KEY= \ No newline at end of file diff --git a/.gitignore b/.gitignore index 6745acb..6020474 100644 --- a/.gitignore +++ b/.gitignore @@ -35,3 +35,6 @@ htmlcov/ # OS .DS_Store + +# Example output +examples/**/report.md diff --git a/README.md b/README.md index 7559738..7d0f35c 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,7 @@ task = Task( ) crew = Crew(agents=[researcher], tasks=[task]) -print(crew.kickoff(inputs={"topic": "web scraping APIs"})) +print(crew.kickoff(inputs={"topic": "solid-state batteries"})) ``` The tools can also be called directly: @@ -68,6 +68,8 @@ print(DecodoWebScraperTool().run(url="https://ip.decodo.com")) print(DecodoSearchTool().run(query="mechanical keyboard", source="amazon")) ``` +For a complete multi-agent example, see the [research crew](examples/research_crew): a researcher, an analyst and a writer that turn any topic into a cited report. + ## Tools ### DecodoWebScraperTool diff --git a/examples/research_crew/README.md b/examples/research_crew/README.md new file mode 100644 index 0000000..84780bc --- /dev/null +++ b/examples/research_crew/README.md @@ -0,0 +1,95 @@ +# Research crew + +A three-agent [CrewAI](https://www.crewai.com) crew that researches any topic on the live web with Decodo and writes a cited report. + +| Agent | Tool | Job | +| --- | --- | --- | +| Web researcher | `DecodoSearchTool` | Searches Google and picks the 5 most relevant sources. | +| Research analyst | `DecodoWebScraperTool` | Reads each source and extracts the key facts. | +| Report writer | none | Turns the notes into a Markdown report with citations. | + +The agents run in sequence, each one working from the previous one's output. The final report is printed and saved to `report.md`. + +## Setup + +From the repository root: + +```bash +python3.12 -m venv .venv +source .venv/bin/activate +pip install -e . +``` + +Set your keys in a `.env` file, in this folder or the repository root, or export them in your shell: + +```bash +DECODO_API_KEY= +OPENAI_API_KEY= +``` + +Get the Decodo API key from your Web Scraping API subscription on the [Decodo dashboard](https://dashboard.decodo.com/web-data/playground). + +The crew uses CrewAI's default model, `gpt-4.1-mini`. To use another model, set `MODEL`, e.g. `MODEL=gpt-4.1`. Other providers need their CrewAI extra and key, e.g. `pip install "crewai[anthropic]"`, `ANTHROPIC_API_KEY` and `MODEL=anthropic/`. + +## Run + +```bash +cd examples/research_crew +python main.py "heat pumps in cold climates" +``` + +Without a topic, it researches "the state of solid-state batteries for electric cars". + +## Sample output + +`python main.py` with the default topic and `gpt-4.1-mini` made 1 search and 5 page scrapes and wrote this report (October 2026): + +
+report.md + +# The State of Solid-State Batteries for Electric Cars + +Solid-state batteries (SSBs) represent a promising evolution in electric vehicle (EV) energy storage technology, offering higher energy density, improved safety, and longer lifespan compared to conventional lithium-ion batteries. While significant technical progress has been made and multiple automakers target commercialization around 2027-2030, challenges in manufacturing scale-up and cost reduction mean widespread adoption remains several years away. + +## Energy Density and Performance Advantages + +SSBs replace the liquid electrolyte in lithium-ion batteries with a solid electrolyte, enabling theoretical energy densities exceeding 500 Wh/kg, compared to 250-300 Wh/kg typical of current lithium-ion batteries. This can translate into EV ranges of 600 to 750 miles and notably faster charging times, such as 10-minute fast charging targets set by Toyota and Samsung SDI for their all-solid-state battery (ASSB) development programs [1][2][4]. Safety is also improved due to the non-flammable nature of solid electrolytes and enhanced chemical stability [4][5]. + +## Industry Development and Timelines + +Automakers and battery companies including Toyota, Samsung SDI, Volkswagen, QuantumScape, Honda, and Factorial Energy are actively developing various solid-state and semi-solid-state battery technologies. Semi-solid-state batteries, offering an intermediate step with improved energy density and reduced risk, have already been produced in limited forms—such as the Nio WELION 150-kWh pack with 260 Wh/kg in 2024 [2]. + +Full mass production of all-solid-state batteries is broadly expected to begin around 2027-2030, initially targeting premium and luxury vehicle segments. Toyota and Samsung SDI have pilot production lines aimed at 2027, while Honda plans demonstration production lines in 2024. Factorial Energy has demonstrated semi-solid-state packs with exceptional range [2][4][5]. However, industry insiders caution that large-scale commercial production may extend beyond 2030 to achieve cost-competitiveness and manufacturing reliability [1][3]. + +## Manufacturing and Cost Challenges + +Despite promising performance, manufacturing SSBs at scale remains a major barrier. The production process requires advanced techniques to ensure dense, defect-free solid electrolyte and electrode interfaces, such as stamping and roll-pressing, which are still being refined [5]. Additional challenges include dendrite formation, raw material costs, and establishing consistent quality control [1][4]. + +Cost projections vary: optimistic scenarios predict $140 per kWh by 2028 with mass production, whereas pessimistic views suggest delays and prices near $175 per kWh around 2032-2033 [1]. These higher costs currently limit initial applications to premium vehicles, with broader market penetration likely delayed until mid-2030s [3]. + +## Market Impact and Outlook + +While SSBs have the potential to revolutionize EV range, charging speed, and safety, incremental improvements in existing lithium-ion battery technologies—such as LFP cells with already-fast charging and 300-mile ranges—moderate the urgency to transition immediately [3]. The market outlook thus anticipates a gradual integration, with lithium-ion batteries evolving in parallel as SSB technology matures. + +In summary, solid-state batteries are poised to become a critical technology milestone for EVs within this decade. Their successful commercialization depends on overcoming significant manufacturing and cost hurdles. Expected first adoption is in high-end vehicles by 2027-2030, followed by wider penetration in the 2030s. + +--- + +## Sources + +[1] Solid-state batteries, their future in the energy storage and electric vehicles market +https://www.sciencedirect.com/science/article/pii/S2772569324000902 + +[2] We Keep Hearing About Solid-State Batteries. Here's What'll Actually Reach the Road. +https://www.motortrend.com/features/solid-state-batteries-future-cars + +[3] Will Solid-state batteries be the EV game changer when they start appearing in 2027/2028? (Reddit r/electricvehicles discussion) +https://www.reddit.com/r/electricvehicles/comments/1vz26my/will_solidstate_batteries_be_the_ev_game_changer/ + +[4] Solid-State Battery News: Samsung & Toyota +https://www.monolithai.com/blog/solid-state-battery-news + +[5] All-solid-state battery technology (Honda official page) +https://global.honda/en/tech/All-solid-state_battery_technology/ + +
diff --git a/examples/research_crew/main.py b/examples/research_crew/main.py new file mode 100644 index 0000000..daa8a07 --- /dev/null +++ b/examples/research_crew/main.py @@ -0,0 +1,99 @@ +"""Multi-agent research crew powered by Decodo. + +A researcher finds sources with Google search, an analyst reads them, and a writer turns the notes +into a cited Markdown report, saved to report.md. + + python main.py "your research topic" +""" + +from __future__ import annotations + +import sys + +from crewai import Agent, Crew, Process, Task +from dotenv import load_dotenv + +from decodo_crewai import DecodoSearchTool, DecodoWebScraperTool + +load_dotenv() + +DEFAULT_TOPIC = "the state of solid-state batteries for electric cars" + + +def build_crew() -> Crew: + researcher = Agent( + role="Web researcher", + goal="Find the most relevant, credible and recent sources about {topic}", + backstory=( + "You are an experienced researcher. You search the web, skip ads and low-quality pages, " + "and pick sources that a careful reader would trust." + ), + tools=[DecodoSearchTool()], + ) + analyst = Agent( + role="Research analyst", + goal="Read the selected sources and extract the key facts about {topic}", + backstory=( + "You read primary sources closely and write down only what they actually say, " + "with figures and dates where they exist." + ), + # Five full pages at once would crowd the context; 15k characters keeps the substance of most articles. + tools=[DecodoWebScraperTool(max_chars=15_000)], + ) + writer = Agent( + role="Report writer", + goal="Write a clear, well-sourced report about {topic}", + backstory="You turn research notes into short reports that busy readers can trust and act on.", + ) + + find_sources = Task( + description=( + "Search Google for {topic}. From the results, pick the 5 most relevant and credible pages. " + "Prefer original sources and recent articles over listicles and ads." + ), + expected_output="A numbered list of 5 sources, each with its title, URL and one line on why it is relevant.", + agent=researcher, + ) + analyze_sources = Task( + description=( + "Read each source from the researcher's list with the web scraper and extract the key facts, " + "figures and claims about {topic}. If a page fails to load, note it and move on." + ), + expected_output=( + "One entry per source, numbered [1], [2] and so on in the researcher's order: the title and URL, " + "then 3 to 6 bullet points of key facts, or 'failed to load'." + ), + agent=analyst, + context=[find_sources], + ) + write_report = Task( + description=( + "Write a report on {topic} using only the analyst's notes. " + "Cite facts inline with the analyst's source numbers, e.g. [2]. " + "End with a Sources list that has every number you cited, with its title and URL, and nothing else." + ), + expected_output=( + "A Markdown report with a title, a 2 to 3 sentence summary, 3 to 5 short sections " + "and a numbered Sources list with URLs." + ), + agent=writer, + context=[analyze_sources], + output_file="report.md", + ) + + return Crew( + agents=[researcher, analyst, writer], + tasks=[find_sources, analyze_sources, write_report], + process=Process.sequential, + verbose=True, + ) + + +def main() -> None: + topic = " ".join(sys.argv[1:]) or DEFAULT_TOPIC + result = build_crew().kickoff(inputs={"topic": topic}) + print(result.raw) + + +if __name__ == "__main__": + main()