Promptulate
A lightweight Python framework for building LLM agents with just a few lines of code.
- Source repo
- Undertone0809/promptulate
- Stars
- ★ 513
- Last updated
- 3mo ago
- License
- Apache-2.0
- Primary language
- Python
- FA score
- 41/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A Python developer who wants one call to reach cloud models and a local ollama instance without rewriting provider code
- Not a fit if
- Users who want a no-code, ready-made chat interface
- Teams needing a mature, long-supported ecosystem
- Anyone unwilling to obtain third-party LLM or Tavily API keys
- Source review
- 41/100 · Major gaps 2 safety controls not found
What does this agent do, and when should you use it?
Promptulate (nicknamed pne) is an AI Agent application development framework from Cogit Lab that aims to make agent building feel like ordinary Python. Its centerpiece is pne.chat(): pass messages and a model string to get a response, or pass a Pydantic model as output_schema to get validated structured data back. Model access is handled through litellm, so roughly thirty providers — from GPT-4o to local ollama models — are reachable via a provider/model_name prefix. Setting enable_plan=True turns the call into a planning loop where an agent decomposes the goal, drives a tool-using agent through Thought/Action/Observation steps, and revises its plan. It ships as an importable library, so you host it yourself and supply your own model and search API keys.
After installing the pne package, developers import promptulate and call pne.chat() with messages (role/content dicts, including gpt-4o image_url multimodal content), a model string such as ollama/llama2 or openai/deepseek-chat, and optionally an output_schema. With enable_plan=True the framework first emits a plan of goals and numbered tasks, then spins up a Tool Agent that reasons, calls a tool such as LangChain's TavilySearchResults, records the observation, and returns an Execute Result; the plan is revised between tasks until an Agent Result is produced. Lower-level pieces are exposed too: pne.LLMFactory.build() creates a model instance and pne.Planner runs planning standalone. The framework also advertises lifecycle Hooks, prompt caching, an OpenAI SDK replacement path, and Streamlit component integration.
- A Python developer who wants one call to reach cloud models and a local ollama instance without rewriting provider code
- A backend engineer who needs typed, validated output (e.g. a list of provinces) instead of parsing free text from the model
- A researcher exploring multi-step question answering who wants an agent to plan, search and reflect using Tavily
- A team already holding LangChain tools that wants to reuse TavilySearchResults with minimal new integration work
- A prototyper who wants a quick Streamlit or Gradio chatbot demo on top of the same pne.chat call
- A developer who only needs task decomposition and wants to use pne.Planner as a standalone component
How do you install or deploy this agent?
Requires Python 3.8 or higher. Install the published package, which is named pne on PyPI:
pip install -U pneThen export the credentials for whichever providers you use:
export OPENAI_API_KEY="your_openai_api_key"
export TAVILY_API_KEY="your_tavily_api_key"How do you use this agent?
The smallest working call is a single pne.chat:
import promptulate as pne
messages = [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Who are you?"},
]
response: str = pne.chat(messages=messages, model="gpt-4-turbo")
print(response)Select a provider with the provider/model_name prefix, for example a local ollama model:
import promptulate as pne
resp: str = pne.chat(model="ollama/llama2", messages=[{"content": "Hello, how are you?", "role": "user"}])Get structured output by passing a Pydantic model:
from typing import List
import promptulate as pne
from pydantic import BaseModel, Field
class LLMResponse(BaseModel):
provinces: List[str] = Field(description="List of provinces' names")
resp: LLMResponse = pne.chat("Please tell me all provinces in China.", output_schema=LLMResponse)
print(resp)Turn on planning and attach a LangChain search tool:
import promptulate as pne
from langchain_community.tools.tavily_search import TavilySearchResults
tools = [TavilySearchResults(max_results=5)]
pne.chat("what is the hometown of the 2024 Australia open winner?", model="gpt-4-1106-preview", enable_plan=True)Or use the planner component on its own:
import promptulate as pne
model = pne.LLMFactory.build("gpt-4-turbo")
planner = pne.Planner(model, system_prompt="You are a planner")
plans = planner.run("Plan a trip to Paris")
print(plans)What are this agent's strengths and limitations?
- One function, pne.chat(), covers chat, structured output and planning, so a first working call takes minutes
- litellm integration exposes about thirty providers under a single provider/model_name convention, including local ollama
- output_schema plus Pydantic gives validated objects back instead of text that needs parsing
- Agent internals are atomized — pne.Planner and pne.LLMFactory can be used without the full agent loop
- Existing LangChain tools plug in directly, and any Python function can be turned into an agent tool
- Apache-2.0 licensed and self-hosted, with Streamlit and Gradio sample apps for quick validation
- Not a ready-made product: you must write Python and bring your own model and search credentials before anything runs
- The feature surface is broad (agents, RAG, hooks, caching, terminal, Streamlit), so capability details often require leaving the README for external docs
- Planning and tool loops depend on the chosen model's quality; the documented example runs several searches, making token spend hard to predict
- No release history or API stability commitment is included in the source, so production compatibility must be judged yourself
- Tavily examples require a separate Tavily account and key, and the LangChain community tool pulls in extra dependencies
How does this agent compare with similar options?
The README references LangChain (reusing its TavilySearchResults tool), AutoGen and litellm (the model-access layer), positioning pne as a lighter alternative that borrows strengths from community frameworks. It also states that pne.chat can replace the OpenAI SDK, letting third-party OpenAI-compatible providers be called through an openai/ prefix.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Promptulate This agent | 41 · Major gaps | Library / SDKFree + model costs | ★ 513 | 3mo ago | Python | OpenAI API |
| CaveAgent | 62 · Some gaps | Library / SDKFree + model costs | ★ 219 | 1mo ago | Python | OpenAI API · Claude API |
| AG2: Open-Source AgentOS | 55 · Major gaps | Library / SDKFree + model costs | ★ 5k | 1d ago | Python | OpenAI API |
| AI SDK | 50 · Major gaps | Library / SDKFree + model costs | ★ 28k | today | TypeScript | OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows the framework calls 100+ models via litellm, with API keys passed through environment variables or model_config, and README/chat_usage give basic guidance. However, there is no documentation or code evidence for least-privilege scoping, user confirmation before tool execution, data-flow disclosure, sensitive-data redaction, or rollback. The dependency set includes litellm, openai, requests and many transitive packages with no vulnerability audit or lockfile policy described. External side effects (tool execution, web search) have no confirmation or undo path. Hence least_privilege, user_confirmation and rollback score 0-1; data_flow_transparency, sensitive_data_handling, dependency_security and external_effects score 1 for scattered mentions only; source_attribution scores 2 because README credits Cogit Lab, litellm, LangChain and Tavily.
README and chat_usage are broadly consistent on pne.chat usage, but examples contain inconsistencies (the Deepseek example sets OPENAI_API_KEY while using a deepseek/ prefix; model-name notation differs slightly between README and chat_usage). Dependency versions drift between pyproject and requirements.txt (litellm ^1.39.6 vs 1.72.0), and niche pinned packages such as broadcast-service 1.3.2 have no availability discussion. Failure messaging is limited to an FAQ note on SSLError and proxy configuration; no systematic error-code or exception-handling documentation. All three score 1.
README clearly targets Python developers and covers chat, structured output, tools, agents and Streamlit scenarios, so audience_and_scenarios scores 2. Capability boundaries (what tasks are unsuitable, how agents behave on planning failure) are only implicit in sample output, not systematically documented, so capability_boundaries scores 1. Trigger precision for parameters like enable_plan and tools has examples but no precise contract, scoring 1. environment_fit scores 2 given declared Python 3.8+ support, a multi-OS CI matrix, and litellm multi-provider coverage.
README is well structured with bilingual entry points, docs-site links, install command and examples, so information_architecture and install_notes score 2; examples_and_faq scores 2 for multiple use cases and an FAQ; LICENSE is the full Apache-2.0 text, scoring 3. Naming stability scores 1 because pne/promptulate dual naming and beta module paths (promptulate.beta) signal unstable APIs. known_limitations scores 1 for only two FAQ items. versioning_changelog scores 1: only the pyproject version 1.18.4, no CHANGELOG file. maintenance_responsibility scores 1: only an author email and Telegram, no governance or maintenance commitment, and the publisher is unverified.
output_usability scores 2 for structured output via Pydantic schemas, streaming, and raw-response metadata. marginal_value scores 1 because the framework overlaps with LangChain and similar tools, and README itself says it borrows from community wisdom, leaving limited differentiation evidence. cost_benefit scores 1 given a heavy dependency footprint (litellm, openai, tiktoken, etc.) with no performance or cost comparison data.
claim_traceability scores 1: the model-support table links to litellm docs, but claims like 'supports nearly all models' are not verified within this repository. cross_source_corroboration scores 1: README, chat_usage and tests partially corroborate pne.chat and ToolAgent descriptions, but tests only cover initialization and schema parsing, not core call paths. fact_inference_separation scores 1: sample outputs (weather, tennis winner) are demonstrative and not marked as illustrative rather than measured.
- Not found in source: confirmation before actingTurn on (or add) a confirmation step before it acts, and try it in a sandbox or test environment before real data.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- The framework calls external models via litellm, passing API keys in plaintext through environment variables or model_config; no key-management or redaction mechanism is shown, so production use needs its own wrapper.
- Tool and agent execution (e.g., Tavily search, custom functions) has no user confirmation or rollback; external side effects are irreversible and require application-level guardrails.
- Dependency versions differ between pyproject.toml and requirements.txt (e.g., litellm ^1.39.6 vs 1.72.0), leaving it unclear which is authoritative for reproduction.
- Beta module paths (promptulate.beta) and dual pne/promptulate naming raise API-stability concerns; pin versions before upgrading.
- Publisher identity is unverified; maintenance responsibility and update path are limited to an author email and Telegram, so assess supply-chain risk before enterprise adoption.
- Sample outputs in README are demonstrative and cannot serve as measured evidence of correctness or performance.