foliorank 0.1.0
AI-assisted portfolio research and simulation toolkit
Requires Python: >=3.8

# Foliorank

## Project Overview

Foliorank is an AI-assisted portfolio research toolkit focused on simulation, comparison, and reproducible analysis. The toolkit enables the systematic exploration of portfolio construction methodologies through deterministic simulations, with a focus on transparency and behavioral constraints.

The toolkit processes natural language descriptions and converts them into structured portfolio specifications for simulation and analysis. All operations occur within a controlled simulation environment, with no connection to external financial systems or real-world execution.

## Core Principles

- **Simulation-based**: All operations are contained within a simulation environment
- **Deterministic & reproducible**: Analysis results can be consistently reproduced given the same inputs
- **Transparent decision processes**: Framework decisions and transformations are documented and auditable
- **Safety-first AI behavior**: AI components operate under strict behavioral constraints designed to prevent unintended actions

## What Foliorank Is

- Portfolio construction and comparison toolkit
- Research and learning tool for portfolio analysis
- Strategy simulation environment
- Open-source SDK for portfolio research

## What Foliorank Is NOT

- Not a trading platform
- Not an execution engine
- Not an investment advisor
- Not a broker or exchange
- Does not provide financial advice

## Research and Educational Use

Foliorank operates within simulation environments and does not execute any real-world transactions. The toolkit is designed for research, education, and analytical purposes. No recommendations, guarantees, or advice are provided. Users are responsible for their own decisions and actions.

## Scope of the Open-Source SDK

The open-source SDK provides simulation-based operations for portfolio construction, analysis, and comparison. All functionality operates within controlled simulation environments designed for educational and research use.

## High-Level Architecture

The toolkit consists of two main components:

- **SDK (open-source)**: Core simulation and analysis functionality
- **Cloud services (future, optional, separate)**: Extended capabilities for larger-scale simulations

The SDK provides the primary interface for portfolio research and maintains strict separation between simulation logic and any potential future services.

## Quickstart

### Installation
```bash
pip install foliorank
```

### CLI Example
```bash
# Plan a portfolio from text
foliorank plan "balanced portfolio for long-term simulation" --out portfolio.json

# Run deterministic simulation
foliorank simulate --in portfolio.json --out results.json

# Validate portfolio specification
foliorank validate --in portfolio.json
```

### Python Example
```python
from foliorank import ControlledAgent

agent = ControlledAgent()
portfolio = agent.plan("I want a balanced portfolio")
simulation = agent.simulate(portfolio)

print(f"Expected return: {simulation['expected_return']:.1f}%")
print(f"Volatility: {simulation['volatility']:.1f}%")
```

## Project Status

This is an early-stage project with a documentation-first approach. APIs and interfaces may evolve as the project develops. The current focus is on establishing robust simulation foundations and clear behavioral constraints.