instantneo 0.3.0

Framework para construir agentes con LLMs, con control granular y composición simple.

InstantNeo

Build instant agents to compose intelligent systems

"I know kung fu." - Neo

What is InstantNeo?

InstantNeo is a Python library that lets you create LLM-based agents quickly and concisely, designed as components for intelligent systems. It offers a clean, direct interface for granular control over agent behavior, abstracting away provider complexity. Like Neo in The Matrix downloading skills instantly, InstantNeo lets you build agents with instant capabilities, simple to start and powerful when composed. Unlike rigid or overly-elaborated frameworks, InstantNeo draws from Marvin Minsky's 'Society of Mind' to deliver modular building blocks, letting you craft multi-agent systems your way.

Features

• Unified Provider Interface: Switch seamlessly between models providers with consistent syntax. The library handles different API requirements behind the scenes.
• Quick and powerful Tool Management: Define agent capabilities using simple Python decorators that transform functions into tools with metadata, descriptions, and parameter validation. Add, remove, and list tools dynamically as your agent's needs evolve.
• Flexible Execution Modes: Control exactly how tools are executed with three modes: wait for results, fire tools in the background, or just extract arguments without execution for planning purposes.
• Text and Image Support: Process both text and images through a single consistent API. Send images alongside prompts to vision-capable models and control the level of image analysis detail as needed.
• Customizable Agent Settings: Modify agent behavior on-the-fly by overriding temperature, max tokens, role setup, and other parameters for specific interactions without recreating the entire agent.

Installation

pip install instantneo

That's it. Works with OpenAI, Anthropic, Groq, Gemini, and Vertex AI out of the box.

Quickstart

Wake Neo Up

from instantneo import InstantNeo

neo = InstantNeo(
    provider="openai",
    api_key="your-api-key",
    model="gpt-4o",
    role_setup="You are Neo, the chosen one. Ready to learn anything."
)

print(neo.run("What's the Matrix?"))

Teach Him Kung Fu

from instantneo import InstantNeo, tool

@tool(description="Execute a kung fu move", parameters={"move": "e.g., dragon punch", "intensity": "1-10"})
def kung_fu(move: str, intensity: int = 5) -> str:
    return f"Hit {move} at intensity {intensity}. I know kung fu!"

neo = InstantNeo(
    provider="anthropic",
    api_key="your-api-key",
    model="claude-3-7-sonnet-20250219",
    role_setup="You are Neo, martial arts downloaded.",
    skills=[kung_fu]
)

print(neo.run("Three agents ahead. What move?"))

Use Vertex AI

from instantneo import InstantNeo

neo = InstantNeo(
    provider="vertexai",
    model="gemini-2.5-flash",
    role_setup="You are Neo, the chosen one.",
    location="us-central1",
    service_account_file="path/to/service-account.json"
)

print(neo.run("I need an exit."))

v2 — Event-sourced Orchestration (InstantLoop)

InstantNeo v2 introduces an event-sourced stack on top of single-agent runs:

• History: append-only immutable log of entries (Entry has id, author, type, content, refs).
• Monitor: standalone rule engine that reacts to History changes (add_rule(when, do)).
• InstantLoop: multi-turn orchestrator that composes agent + history + monitor + bridge.
• RunLog (opt-in via debug=True): forensic per-run log persisted to disk separately from the lean History.

from instantneo import InstantNeo, InstantLoop, tool

@tool(description="Finalize when done",
      parameters={"summary": {"description": "Resumen", "type": "str"}})
def finalize(summary: str) -> dict:
    return {"summary": summary, "done": True}

agent = InstantNeo(
    provider="openai", model="gpt-5-mini", api_key="sk-...",
    role_setup="Be a helpful assistant. Call finalize when done.",
    tools=[finalize],
)
loop = InstantLoop(agent=agent, name="my_loop",
                    stop_tool="finalize", debug=True)
result = loop.run("Explain photosynthesis briefly, then finalize.")
print(result.terminated_reason)  # "stop_signal"
print(result.stop_reason)         # "agent called finalize"
print(result.log.turns)            # list of TurnLog (with messages_sent, usage, etc.)

Full design in docs/design/:

• loop-design.md — InstantLoop
• history-design.md — History layer
• monitor-design.md — Monitor rule engine
• runinfo-to-entries.md — bridge from RunInfo to Entrys
• log-design.md — RunLog (Capa 1 generic + Capa 2 Loop-specific)

The legacy instantneo.experimental.instant_loop is deprecated in v2 and emits a DeprecationWarning. Use from instantneo import InstantLoop instead.

API Reference

• InstantNeo Class: Set provider, api_key, model, role_setup, plus tools and tuning params (temperature, max_tokens, etc.).
• run() Method: Feed it a prompt, pick an execution_mode (WAIT_RESPONSE, EXECUTION_ONLY, GET_ARGS), override settings as needed.

Details in the docs.

Architecture and Philosophy

InstantNeo leans on Minsky's "Society of Mind": small, specialized agents you connect to make something bigger. Each agent's a tool—give it a role, add skills, and weave them together. The smarts come from your coordination, not ours.

Documentation

Full scoop at /docs, including tutorials on multi-agent setups and advanced skills.

Contributing

Fork, branch, commit, push, PR. Update tests and docs if you're adding something.

License

MIT License—check LICENSE.

"I'm trying to free your mind, Neo. But I can only show you the door. You're the one that has to walk through it." - Morpheus