Metadata-Version: 2.4
Name: openfin
Version: 0.1.0
Summary: Filesystem-based agent definition and runtime system
Author: Michael Karotsieris
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: anthropic>=0.7.0
Provides-Extra: bundling
Requires-Dist: pyinstaller>=5.0.0; extra == "bundling"

# OpenFin Agent System

A filesystem-based agent definition and runtime system for long-running AI agents with persistent memory, action logging, and reflection capabilities.

## Overview

OpenFin allows you to define agents through filesystem organization, enabling:
- **Long-running processes** that persist state across sessions
- **Temporal memory** of actions and context
- **Action logging** for understanding agent behavior over time
- **Reflection** on capabilities, tools, and skills
- **Filesystem-based definition** - define agents, skills, and tools through directory structure

## Filesystem Structure

```
agent/
├── PERSONALITY.md    # Agent personality definition
└── BEHAVIOUR.md      # Agent behavior definition

skills/
├── technical-writing/
├── coding/
├── marketing/
└── growth-hacking/

tools/
├── file-io/
├── network-io/
├── websearch/
├── sandbox/
├── docker/
├── code-running/
└── terminal-access/
```

Each directory can contain:
- **README.md** - Documentation describing the capability
- **prompt.md** - Versioned prompt definitions
- **tool.py** or **skill.py** - Executable Python modules

## Features

### Memory & State
- Persistent state across sessions
- Temporal memory with importance weighting
- Action logging with full context
- Memory retrieval by tags and importance

### Reflection
- Automatic capability discovery
- Tool and skill evaluation
- Self-awareness of available capabilities
- Reflection history

### Long-Running Agents
- Graceful shutdown handling
- Session management
- State persistence
- Context continuity

## Usage

### Running an Agent

```bash
python cli.py --base-path . --agent-id my-agent
```

### Viewing Logs

View action logs:
```bash
python utils/view_logs.py --agent-id my-agent --limit 100
```

View memories:
```bash
python utils/view_logs.py --agent-id my-agent --memories
```

Filter by tool:
```bash
python utils/view_logs.py --agent-id my-agent --filter-tool file-io
```

### Interactive Commands

- `help` - Show available commands
- `context` - Show full agent context
- `memory` - Show recent memories
- `capabilities` - Show available tools and skills
- `action <type> <description> [tool:<name>]` - Execute an action
- `memory <content> [importance:<0.0-1.0>] [tags:<tag1,tag2>]` - Add a memory
- `exit` - Shutdown the agent

### Example

```bash
# Start the agent
python cli.py

# In the agent shell:
> capabilities
> action read_file Read config file tool:file-io
> memory Important configuration loaded importance:0.8 tags:config,setup
> context
> exit
```

## Architecture

### Core Components

- **AgentRuntime** - Main runtime for executing agents
- **MemoryStore** - Manages persistent memory and state
- **ReflectionEngine** - Handles capability discovery and reflection
- **AgentDefinition** - Loads agent personality and behavior

### Memory Structure

Memory is stored in `memory/<agent-id>/`:
- `actions.jsonl` - Action log (append-only)
- `memory.json` - Important memories
- `state.json` - Agent state

## Development

### Adding a Tool

1. Create directory: `tools/my-tool/`
2. Add `README.md` with description and capabilities
3. Optionally add `tool.py` with `execute(input_data, context)` function

### Adding a Skill

1. Create directory: `skills/my-skill/`
2. Add `README.md` with description and capabilities
3. Optionally add `skill.py` with `execute(input_data, context)` function

### Versioning

Files can include version information in their content. The system will parse version numbers from markdown files.

## Requirements

- Python 3.8+
- No external dependencies (uses only standard library)

## License

MIT
