Building Intelligence from First Principles

Welcome to the comprehensive documentation for the Nyra Framework. If you are tired of debugging black-box wrappers and want absolute deterministic control over your AI systems, you are in the right place.

The 0 to 1 Philosophy

The generative AI ecosystem is currently built on a house of cards. Most frameworks obscure the prompt injection layer, making it impossible to debug *why* an agent failed to execute a task.

Nyra was engineered at Ananta Labs from first principles. It has zero external dependencies. It does not hide prompts from you. It enforces a rigorous Cognitive Loop.

The Golden Rule of Nyra

Every step of execution must be traceable. If the system fails, you must be able to see exactly which module (Planner, Reasoner, Orchestrator, or Critic) dropped the ball.

Installation

Nyra is available on PyPI. It requires Python 3.10+.

pip install nyra

Quickstart: Your First Global Agent

Let's build an agent that can research the web and return structured data. Notice how we explicitly connect the LLM to each cognitive module—no magic.

from nyra.agent import Agent
from nyra.providers.openai import OpenAILLM

# Initialize the LLM Interface
llm = OpenAILLM(api_key="your-api-key", model="gpt-4o")

# 1. Boot up the Agent
agent = Agent()
agent.llm = llm

# 2. Wire the cognitive modules explicitly
agent.planner.llm = llm
agent.reasoner.llm = llm
agent.critic.llm = llm
agent.orchestrator.llm = llm

# 3. Register a specialized sub-agent
agent.register_sub_agent(
    name="ResearchBot", 
    role="Web Researcher", 
    tools=["search_google"]
)

# 4. Run the deterministic loop
agent.run("Find the top 3 AI frameworks in 2026.")
        

The Master Agent

The Agent() class is the orchestrator of the entire cognitive loop. It does not perform reasoning itself; it relies on the Planner, Orchestrator, Reasoner, and Critic to step through an objective.

The Planner Module

When an objective is received, the Planner is the first to act. It breaks the objective down into atomic, highly specific steps.

The Reasoner Module

The Reasoner is the execution engine. It receives a specific, atomic step from the Planner (via the Orchestrator) and decides which tool or sub-agent to invoke to solve it. It manages the prompt context window and ensures the LLM stays focused on the immediate task.

The Orchestrator

The Orchestrator acts as the traffic controller. It takes the array of steps from the Planner, hands the first step to the Reasoner, waits for the result, passes the result to the Critic for validation, and if approved, moves on to the next step. It handles all error routing and retry limits.

The Critic

The Critic is the most vital component of Nyra. Once a Sub-Agent completes a step, the Critic evaluates the output against the Planner's original intent. If the output is hallucinated or incomplete, the Critic rejects it and forces the Reasoner to retry with updated instructions.

Registering Sub-Agents

Nyra's true power comes from dynamically routing tasks to specialized agents. Instead of giving one master agent 50 tools, you create smaller, highly-focused sub-agents.

agent.register_sub_agent(
    name="FinancialAnalyst", 
    role="Expert in reading balance sheets.", 
    tools=["fetch_sec_filing", "calculate_cagr"]
)
        

Writing Custom Tools

Tools in Nyra are just standard Python functions. You simply pass them in a list when registering a sub-agent. Nyra automatically parses the function signature and docstring to teach the LLM how to use it.