docs
API Reference
Agentic OS API

Agentic OS API

The Agentic OS is a framework that allows you to build, tune, and work with AI agents specialized for financial reasoning and analysis.

Overview

Our Agentic OS provides:

  • Scenario Simulation: Model complex market scenarios and their cascading effects
  • Portfolio Analysis: Understand how events impact your holdings
  • Causal Reasoning: Trace cause-and-effect chains through financial markets
  • Real-Time Context: Ground agent reasoning in current market data and knowledge graph

Core Concepts

Agents

Agents are autonomous AI systems that can:

  • Query the Knowledge Graph for context
  • Reason about financial relationships
  • Simulate market scenarios
  • Generate actionable insights

Workflows

Workflows orchestrate multiple agents to solve complex problems:

  • Research workflows
  • Portfolio analysis workflows
  • Risk assessment workflows
  • Event impact workflows

Quick Start

Create a Basic Agent

from zomma import Agent
 
agent = Agent(
    name="portfolio-analyst",
    capabilities=["scenario-simulation", "causal-reasoning"],
    knowledge_graph=True
)
 
result = agent.ask(
    "What happens to tech stocks if the Fed raises rates by 50bps?"
)
 
print(result.analysis)

Portfolio Impact Analysis

from zomma import PortfolioAgent
 
portfolio_agent = PortfolioAgent()
 
# Define your portfolio
portfolio = {
    "AAPL": {"shares": 100, "weight": 0.30},
    "MSFT": {"shares": 50, "weight": 0.25},
    "GOOGL": {"shares": 25, "weight": 0.25},
    "NVDA": {"shares": 20, "weight": 0.20}
}
 
# Simulate a scenario
impact = portfolio_agent.simulate_scenario(
    scenario="Fed raises rates by 100bps",
    portfolio=portfolio,
    time_horizon="3 months"
)
 
print(f"Expected portfolio impact: {impact.total_return}%")
print(f"Volatility change: {impact.volatility_delta}%")
 
for holding, analysis in impact.holdings.items():
    print(f"{holding}: {analysis.expected_return}%")

Causal Chain Analysis

from zomma import CausalAgent
 
causal_agent = CausalAgent()
 
# Trace causal chains
chains = causal_agent.trace(
    event="Strait of Hormuz closure",
    depth=3,  # Follow chains 3 levels deep
    min_probability=0.3  # Only show likely effects
)
 
for chain in chains:
    print(f"Chain probability: {chain.probability}")
    for step in chain.steps:
        print(f"  → {step.event} (p={step.probability})")

Agent Configuration

Customizing Agent Behavior

agent = Agent(
    name="risk-analyst",
    model="gpt-4",
    temperature=0.2,  # More deterministic
    max_tokens=2000,
    capabilities=[
        "scenario-simulation",
        "causal-reasoning",
        "risk-assessment"
    ],
    knowledge_graph=True,
    real_time_data=True,
    tools=[
        "portfolio-optimizer",
        "monte-carlo-simulator",
        "correlation-analyzer"
    ]
)

Setting System Prompts

agent.set_system_prompt("""
You are a quantitative analyst specializing in macro-economic events.
Always ground your analysis in factual data from the knowledge graph.
Provide probabilistic estimates with confidence intervals.
""")

Workflows

Multi-Agent Research Workflow

from zomma import Workflow
 
workflow = Workflow()
 
# Define a research workflow
workflow.add_agent("researcher", capabilities=["knowledge-graph-query"])
workflow.add_agent("analyst", capabilities=["causal-reasoning"])
workflow.add_agent("synthesizer", capabilities=["report-generation"])
 
# Configure the flow
workflow.connect("researcher", "analyst")
workflow.connect("analyst", "synthesizer")
 
# Run the workflow
report = workflow.run(
    query="What are the second-order effects of China's real estate crisis?",
    output_format="markdown"
)
 
print(report.content)

Advanced Features

Real-Time Data Integration

agent = Agent(real_time_data=True)
 
# Agent automatically pulls latest market data
analysis = agent.analyze(
    "What's the current risk profile of the energy sector?",
    include_latest_data=True
)

Custom Tools

Add custom tools to extend agent capabilities:

from zomma import Tool
 
@Tool.register
def custom_valuation_model(company: str, assumptions: dict) -> dict:
    """Custom DCF valuation model"""
    # Your valuation logic here
    return {
        "fair_value": 150.25,
        "upside": "12%",
        "assumptions": assumptions
    }
 
agent = Agent(tools=["custom_valuation_model"])

Memory and Context

Agents maintain conversation history and context:

agent = Agent(memory=True)
 
# First question
agent.ask("What are the risks in my tech-heavy portfolio?")
 
# Follow-up question (agent remembers context)
agent.ask("How can I hedge those risks?")
 
# Access conversation history
history = agent.get_history()

API Reference

Agent Class

class Agent:
    def __init__(
        self,
        name: str,
        model: str = "gpt-4",
        capabilities: List[str] = [],
        knowledge_graph: bool = False,
        real_time_data: bool = False,
        tools: List[str] = []
    )
 
    def ask(self, question: str) -> AgentResponse
    def simulate_scenario(self, scenario: str, **kwargs) -> SimulationResult
    def set_system_prompt(self, prompt: str) -> None
    def get_history(self) -> List[Message]

Workflow Class

class Workflow:
    def add_agent(self, name: str, **config) -> None
    def connect(self, from_agent: str, to_agent: str) -> None
    def run(self, query: str, **kwargs) -> WorkflowResult

Authentication

import zomma
 
zomma.api_key = "your-api-key-here"

Rate Limits

  • Free Tier: 100 agent requests/day
  • Pro Tier: 10,000 agent requests/day
  • Enterprise: Unlimited

Coming Soon

Features currently in development:

  • Backtesting Framework: Test agent strategies on historical data
  • Multi-Agent Collaboration: Agents that debate and refine analysis
  • Custom Model Support: Use your own fine-tuned models
  • Advanced Risk Models: VaR, CVaR, and stress testing

Next Steps

Support

For questions or custom agent development: