State1 0.4

A unified framework for building AI agents with low-code.

state1

state1 is a unified, open-source Python framework for building powerful, extensible AI agents with minimal setup. It brings together LLMs, web search, RAG, chain-of-thought, multi-agent orchestration, persistent memory, authentication, and real-world actions—all in a single, low-code/no-code package.

---

🚀 Why state1?

• One package, all the tools: No more juggling multiple libraries for LLMs, RAG, web search, actions, and orchestration.
• Low-code/no-code: Build, run, and extend agents with just a few lines of Python or even from the CLI.
• Real-world ready: Agents can send emails, fetch APIs, search the web, and more—driven by LLM function calling.
• Multi-agent orchestration: Compose teams of agents for research, summarization, fact-checking, and more.
• Persistent, editable agents: Every agent is saved as a JSON file—edit configs, add tools, or share agents with others.
• Open-source and extensible: Add your own actions, agent types, workflows, and UI.

---

📦 Installation

pip install state1

---

🖥️ Quickstart: Terminal CLI (Install & Play!)

After installing, just run:

terminal-chat

• No need to copy scripts or set up anything extra!
• Create, list, and switch between agents interactively
• All agent configs are saved in the agents/ directory (edit them directly for advanced options)
• Works on any OS with Python 3.8+

Example session:

$ terminal-chat
Created default agent with ID: ...
Type /help for commands.
[Agent ...] You: /new
Agent name: ResearchBot
Provider (openai/openrouter) [openai]: openai
API key: ...
...

---

🧑‍💻 Quickstart: Your First Agent in Python

from state1 import Agent

agent = Agent(
    name="Demo Agent",
    description="An example AI agent",
    context="You are a helpful assistant.",
    provider="openai",  # or "openrouter"
    api_key="YOUR_OPENAI_API_KEY",
    model="gpt-3.5-turbo",
    websearch=True,   # Enable web search context
    rag=True,         # Enable document RAG
    cot=True          # Enable chain-of-thought reasoning
)

agent.chat_loop()  # Start an interactive chat in the terminal

---

🧩 Features

1. Unified Agent Creation

• LLMs: OpenAI, OpenRouter (Gemini, Claude, etc.)
• Web search: DuckDuckGo integration
• RAG: Ingest and retrieve from text, PDF, DOCX using ChromaDB and sentence-transformers
• Chain-of-thought: Step-by-step reasoning with custom instructions
• Memory: Persistent chat history per user/agent
• Authentication: Email/password login with local SQLite DB

2. Real-World Actions (Tool Use)

• SendEmailAction: Send emails via SMTP (Gmail, Outlook, etc.)
• FetchAPIAction: Fetch data from any API (weather, GitHub, etc.)
• LLM function calling: Actions are exposed as JSON schemas for natural invocation by the LLM

3. Multi-Agent Orchestration

• Orchestrator class supports:
  • Parallel, sequential, voting/consensus, and manager/worker workflows
  • Auto-creation of specialist agents (researcher, summarizer, fact checker, analyser, manager)
  • Chain-of-thought enabled for all agents

4. Extensible and Open

• Add your own actions by subclassing Action
• Register new tools, agent types, and workflows
• Edit agent JSON files to add new capabilities

---

🧪 Example Scripts

1. Actions Demo

from state1 import Agent
from state1.actions import SendEmailAction, FetchAPIAction

agent = Agent(
    name="ActionDemo Agent",
    provider="openai",
    api_key="YOUR_OPENAI_API_KEY",
    model="gpt-4o",
    smtp_config={
        "smtp_server": "smtp.gmail.com",
        "smtp_port": 465,
        "sender_email": "[e-mail]",
        "sender_password": "your_app_password"
    },
    apis={
        "github": {"url": "https://api.github.com"},
        "weather": {"url": "https://wttr.in"}
    }
)
agent.register_action(SendEmailAction())
agent.register_action(FetchAPIAction())
agent.chat_loop()

2. RAG Demo

from state1 import Agent

agent = Agent(
    name="RAG Agent",
    provider="openai",
    api_key="YOUR_OPENAI_API_KEY",
    model="gpt-3.5-turbo",
    rag=True
)
agent.add_document("example.pdf")
agent.chat_loop()

3. Orchestrator Demo

from state1.orchestrator import Orchestrator

orchestrator = Orchestrator(
    orchestra=True,
    api_key="YOUR_OPENAI_API_KEY",
    model="gpt-3.5-turbo",
    workflow_mode="manager"
)
orchestrator.chat_loop()

4. Auth & Memory Demo

from state1 import Agent

agent = Agent(
    name="AuthTest Agent",
    provider="openai",
    api_key="YOUR_OPENAI_API_KEY",
    model="gpt-3.5-turbo",
    auth=True,   # enables email/password authentication and DB
    memory=True  # enables persistent memory per user
)
agent.chat_loop()

---

🛠️ Advanced: Adding Your Own Actions

Create a new action by subclassing Action:

from state1.actions import Action

class MyCustomAction(Action):
    name = "my_action"
    description = "Describe what this action does."

    def run(self, **kwargs):
        # Your logic here
        return "Action result!"

# Register with your agent
agent.register_action(MyCustomAction())

---

📝 Agent JSON File Reference

You can edit any agent's JSON file in the agents/ directory to add or change fields:

• name, description, context
• provider, api_key, model
• websearch, rag, cot, auth, memory
• smtp_config (for email actions)
• apis (for API actions)
• ...and more!

---

🔒 Security & Credentials

• Never commit your API keys or passwords to public repos.
• For email actions, use app passwords (e.g., Gmail app password).
• Agent files are local and editable, but protect your agents/ directory if needed.

---

🧠 Philosophy

• Unify: All major agent features in one package.
• Extensible: Add new tools, actions, and workflows easily.
• No lock-in: All configs are plain JSON, easy to edit, export, or share.
• Open-source: MIT licensed, community contributions welcome!

---

📚 Roadmap

• More built-in actions (Slack, calendar, file management, etc.)
• LLM-driven tool selection and chaining
• Web UI and API endpoints
• Analytics, monitoring, and agent dashboards
• Community-contributed agent templates

---

🏁 Get Started

1. pip install state1
2. Run terminal-chat
3. Create, edit, and chat with agents—your AI team, your way!

---

📄 License

MIT

---

state1 — The unified, open-source AI agent framework for everyone.