<div align="center">
<img src="https://raw.githubusercontent.com/jacksongrove/impossibly/main/impossibly.png" alt="Impossibly Logo" width="600">
<p><strong>Build, orchestrate and scale agents impossibly fast</strong></p>
</div>
# Impossibly
Impossibly is an agentic orchestration framework for rapidly building agentic architectures in Python. It accelerates agentic development, empowering developers to craft architectures that enable LLMs to excel in higher-order tasks like idea generation and critical thinking.
This library is designed to be used as a backend for AI apps and automations, providing support for all major LLM providers and locally-hosted model endpoints.
# Getting Started
## Installation
Install the base package:
```bash
pip install impossibly
```
Or install with specific integrations:
```bash
# Minimal installations with specific providers
pip install "impossibly[openai]" # Only OpenAI support
pip install "impossibly[anthropic]" # Only Anthropic support
pip install "impossibly[all]" # All LLM integrations
# For testing and development
pip install "impossibly[test]" # All LLM integrations + testing tools
pip install "impossibly[dev]" # All LLM integrations + testing + dev tools
```
## Imports
Import the components you need:
```python
from impossibly import Agent, Graph, START, END
```
## Setting Up Environment Variables
1. Copy the `.env.template` file to a new file named `.env`:
```bash
cp .env.template .env
```
2. Fill in your API keys and configurations in the `.env` file:
```
OPENAI_API_KEY=your_actual_api_key_here
ANTHROPIC_API_KEY=your_anthropic_api_key_here
```
3. The library will automatically load these variables when needed. At minimum, you'll need the API key for your preferred LLM provider.
## Initalize Clients for LLM APIs
Done in the format standard to your API.
## Create Agents
Initalize the agents you'd like to call with a simple schema:
```
agent = Agent(
client=client,
model="gpt-4o",
name="Agent",
system_prompt="You are a friendly assistant.",
description="This agent is an example agent."
)
```
## Define how agents are executed with a Graph
Graphs connect agents together using nodes and edges, routing the execution flow and all needed information through the graph. Each node represents an agent and each edge represents a conditional under which that agent is called. This conditional can be defined in natural language for each agent, within its `system_prompt`.
In the case of multiple edges branching from one node, agents can understand their routing options using the `description` field of connecting nodes.
Every graph accepts user input at the `START` and returns a response to the user at the `END`.
With this basic understanding, a graph can be created in just a few lines.
```
graph = Graph()
graph.add_node(agent)
graph.add_node(summarizer_agent)
graph.add_edge(START, agent)
graph.add_edge(agent, summarizer_agent)
graph.add_edge(summarizer_agent, END)
```
## Run your Graph
You're done! Prompt your agentic architecture.
```
graph.invoke("Hello there!")
```
# Development
## Running Tests
To run the tests, first install the package with test dependencies:
```bash
# Install with test dependencies
pip install -e ".[test]"
```
Then run the tests using the CLI command that gets installed with the package:
```bash
# Run all tests
impossibly run
# Run just feature tests
impossibly run --path features/
# Run tests in Docker
impossibly run --docker
# Get help
impossibly run --help
```
See [tests/README.md](tests/README.md) for more details on the testing framework and available options.
## Local Development and Running Examples
If you want to develop locally and test the examples, follow these steps:
### Building the Package Locally
1. Clone the repository:
```bash
git clone https://github.com/jacksongrove/impossibly.git
cd impossibly
```
2. Create and activate a virtual environment (optional but recommended):
```bash
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
```
3. Install development dependencies:
```bash
pip install -e ".[dev]"
```
4. Build the package locally:
```bash
python -m build
```
This will create distributions in the `dist/` directory.
### Installing the Local Build to Run Examples
There are two approaches to use your local build:
#### Option 1: Install in Development Mode (Recommended)
This allows changes to the source code to be immediately reflected without reinstalling:
```bash
pip install -e .
```
#### Option 2: Install the Built Wheel
If you want to test the exact distribution that would be uploaded to PyPI:
```bash
pip install dist/impossibly-0.1.0-py3-none-any.whl
```
### Running Examples
Once you've installed the package using either method, you can run the examples:
```bash
# Set up your environment variables first
cp .env.template .env
# Edit .env to add your API keys
# Run an example
python examples/image_agent/image_agent.py
# Or try another example
python examples/web_search_agent/web_search_agent.py
```
Make sure the required dependencies for each example are installed and the necessary API keys are in your `.env` file.
Raw data
{
"_id": null,
"home_page": null,
"name": "impossibly",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "ai, agents, llm, orchestration, tools, agentic, architecture",
"author": "Jackson Grove",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/cf/6e/d7707392fc89d7bf31bcc88e32825954a875045fb3f9839203b7411ec418/impossibly-0.1.2.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n <img src=\"https://raw.githubusercontent.com/jacksongrove/impossibly/main/impossibly.png\" alt=\"Impossibly Logo\" width=\"600\">\n \n <p><strong>Build, orchestrate and scale agents impossibly fast</strong></p>\n</div>\n\n# Impossibly\nImpossibly is an agentic orchestration framework for rapidly building agentic architectures in Python. It accelerates agentic development, empowering developers to craft architectures that enable LLMs to excel in higher-order tasks like idea generation and critical thinking.\n\nThis library is designed to be used as a backend for AI apps and automations, providing support for all major LLM providers and locally-hosted model endpoints.\n\n# Getting Started\n## Installation\n\nInstall the base package:\n```bash\npip install impossibly\n```\n\nOr install with specific integrations:\n```bash\n# Minimal installations with specific providers\npip install \"impossibly[openai]\" # Only OpenAI support\npip install \"impossibly[anthropic]\" # Only Anthropic support\npip install \"impossibly[all]\" # All LLM integrations\n\n# For testing and development\npip install \"impossibly[test]\" # All LLM integrations + testing tools\npip install \"impossibly[dev]\" # All LLM integrations + testing + dev tools\n```\n\n## Imports\nImport the components you need:\n```python\nfrom impossibly import Agent, Graph, START, END\n```\n\n## Setting Up Environment Variables\n1. Copy the `.env.template` file to a new file named `.env`:\n ```bash\n cp .env.template .env\n ```\n\n2. Fill in your API keys and configurations in the `.env` file:\n ```\n OPENAI_API_KEY=your_actual_api_key_here\n ANTHROPIC_API_KEY=your_anthropic_api_key_here\n ```\n\n3. The library will automatically load these variables when needed. At minimum, you'll need the API key for your preferred LLM provider.\n\n## Initalize Clients for LLM APIs\nDone in the format standard to your API.\n\n## Create Agents\nInitalize the agents you'd like to call with a simple schema:\n```\nagent = Agent(\n client=client, \n model=\"gpt-4o\", \n name=\"Agent\", \n system_prompt=\"You are a friendly assistant.\",\n description=\"This agent is an example agent.\"\n )\n```\n\n## Define how agents are executed with a Graph\nGraphs connect agents together using nodes and edges, routing the execution flow and all needed information through the graph. Each node represents an agent and each edge represents a conditional under which that agent is called. This conditional can be defined in natural language for each agent, within its `system_prompt`. \n\nIn the case of multiple edges branching from one node, agents can understand their routing options using the `description` field of connecting nodes.\n\nEvery graph accepts user input at the `START` and returns a response to the user at the `END`.\n\nWith this basic understanding, a graph can be created in just a few lines.\n```\ngraph = Graph()\n\ngraph.add_node(agent)\ngraph.add_node(summarizer_agent)\n\ngraph.add_edge(START, agent)\ngraph.add_edge(agent, summarizer_agent)\ngraph.add_edge(summarizer_agent, END)\n```\n\n## Run your Graph\nYou're done! Prompt your agentic architecture.\n```\ngraph.invoke(\"Hello there!\")\n```\n\n# Development\n## Running Tests\n\nTo run the tests, first install the package with test dependencies:\n\n```bash\n# Install with test dependencies\npip install -e \".[test]\"\n```\n\nThen run the tests using the CLI command that gets installed with the package:\n\n```bash\n# Run all tests\nimpossibly run\n\n# Run just feature tests\nimpossibly run --path features/\n\n# Run tests in Docker\nimpossibly run --docker\n\n# Get help\nimpossibly run --help\n```\n\nSee [tests/README.md](tests/README.md) for more details on the testing framework and available options.\n\n## Local Development and Running Examples\n\nIf you want to develop locally and test the examples, follow these steps:\n\n### Building the Package Locally\n\n1. Clone the repository:\n ```bash\n git clone https://github.com/jacksongrove/impossibly.git\n cd impossibly\n ```\n\n2. Create and activate a virtual environment (optional but recommended):\n ```bash\n python -m venv .venv\n source .venv/bin/activate # On Windows: .venv\\Scripts\\activate\n ```\n\n3. Install development dependencies:\n ```bash\n pip install -e \".[dev]\"\n ```\n\n4. Build the package locally:\n ```bash\n python -m build\n ```\n This will create distributions in the `dist/` directory.\n\n### Installing the Local Build to Run Examples\n\nThere are two approaches to use your local build:\n\n#### Option 1: Install in Development Mode (Recommended)\n\nThis allows changes to the source code to be immediately reflected without reinstalling:\n\n```bash\npip install -e .\n```\n\n#### Option 2: Install the Built Wheel\n\nIf you want to test the exact distribution that would be uploaded to PyPI:\n\n```bash\npip install dist/impossibly-0.1.0-py3-none-any.whl\n```\n\n### Running Examples\n\nOnce you've installed the package using either method, you can run the examples:\n\n```bash\n# Set up your environment variables first\ncp .env.template .env\n# Edit .env to add your API keys\n\n# Run an example\npython examples/image_agent/image_agent.py\n\n# Or try another example\npython examples/web_search_agent/web_search_agent.py\n```\n\nMake sure the required dependencies for each example are installed and the necessary API keys are in your `.env` file.\n",
"bugtrack_url": null,
"license": null,
"summary": "An agentic architecture for idea generation & critical thinking",
"version": "0.1.2",
"project_urls": {
"Bug Reports": "https://github.com/jacksongrove/impossibly/issues",
"Documentation": "https://github.com/jacksongrove/impossibly/blob/main/README.md",
"Homepage": "https://github.com/jacksongrove/impossibly"
},
"split_keywords": [
"ai",
" agents",
" llm",
" orchestration",
" tools",
" agentic",
" architecture"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1989109cf44f6071b9e7ff80900973f67458bfd8dc4c8d4924db0f6f162d8c50",
"md5": "fa69aa700f04b85e712d9763d57e8ff0",
"sha256": "f46c923261136cbab516931e6195faac6f48b2cae35c334b6c04a00ade1a166e"
},
"downloads": -1,
"filename": "impossibly-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fa69aa700f04b85e712d9763d57e8ff0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 21681,
"upload_time": "2025-07-28T19:24:28",
"upload_time_iso_8601": "2025-07-28T19:24:28.915089Z",
"url": "https://files.pythonhosted.org/packages/19/89/109cf44f6071b9e7ff80900973f67458bfd8dc4c8d4924db0f6f162d8c50/impossibly-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cf6ed7707392fc89d7bf31bcc88e32825954a875045fb3f9839203b7411ec418",
"md5": "162c44c4bac53d3868455eb197331f73",
"sha256": "517136173bfe913d32129f46c39946b2282192a3619f22921deb3b165f3676e9"
},
"downloads": -1,
"filename": "impossibly-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "162c44c4bac53d3868455eb197331f73",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 36128,
"upload_time": "2025-07-28T19:24:30",
"upload_time_iso_8601": "2025-07-28T19:24:30.471329Z",
"url": "https://files.pythonhosted.org/packages/cf/6e/d7707392fc89d7bf31bcc88e32825954a875045fb3f9839203b7411ec418/impossibly-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-28 19:24:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jacksongrove",
"github_project": "impossibly",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "annotated-types",
"specs": [
[
"==",
"0.7.0"
]
]
},
{
"name": "anthropic",
"specs": [
[
"==",
"0.45.2"
]
]
},
{
"name": "anyio",
"specs": [
[
"==",
"4.5.2"
]
]
},
{
"name": "certifi",
"specs": [
[
"==",
"2025.1.31"
]
]
},
{
"name": "distro",
"specs": [
[
"==",
"1.9.0"
]
]
},
{
"name": "exceptiongroup",
"specs": [
[
"==",
"1.2.2"
]
]
},
{
"name": "h11",
"specs": [
[
"==",
"0.14.0"
]
]
},
{
"name": "httpcore",
"specs": [
[
"==",
"1.0.7"
]
]
},
{
"name": "httpx",
"specs": [
[
"==",
"0.28.1"
]
]
},
{
"name": "idna",
"specs": [
[
"==",
"3.10"
]
]
},
{
"name": "jiter",
"specs": [
[
"==",
"0.8.2"
]
]
},
{
"name": "openai",
"specs": [
[
"==",
"1.61.1"
]
]
},
{
"name": "pydantic",
"specs": [
[
"==",
"2.10.6"
]
]
},
{
"name": "pydantic-core",
"specs": [
[
"==",
"2.27.2"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
"==",
"1.0.1"
]
]
},
{
"name": "sniffio",
"specs": [
[
"==",
"1.3.1"
]
]
},
{
"name": "tqdm",
"specs": [
[
"==",
"4.67.1"
]
]
},
{
"name": "typing-extensions",
"specs": [
[
"==",
"4.12.2"
]
]
}
],
"lcname": "impossibly"
}
JSON
