phoson-engine-minimal

Minimal Python runtime for the Phoson autonomous-agent platform

🔥 Open Source — Built for developers who want full control over their AI agents.

---

📋 Table of Contents

• What this project is
• Why Phoson?
• Features
• High-level architecture
• Repository map
• Core modules
  • phoson_llm — LLM normalization layer
  • phoson_agent — Agent orchestration
  • phoson_agent.sessions — Conversation persistence
  • phoson_cli — Interactive REPL
• 🚀 Quick Start
• Installation
• Development setup
• Run checks locally
• Environment variables
• Usage examples
  • Minimal agent usage
  • Define a tool
  • Interactive CLI
• CI and security workflows
• Commit message format
• Roadmap
• Contributing
• License
• Support

---

🤔 What this project is

phoson-engine-minimal is the core runtime behind the Phoson autonomous-agent platform. It's a lightweight, framework-free Python implementation that gives you complete control over your AI agents without the bloat of heavy frameworks.

Unlike other agent frameworks (LangChain, LangGraph, etc.), Phoson is built from scratch using provider SDKs directly, with a custom ReAct loop designed for:

• 🔄 Streaming behavior — Token-by-token events for real-time UIs
• 🔧 Tool-call orchestration — Full control over tool execution
• 💰 Cost accounting — Track spend per run with built-in pricing
• 👁️ Observability — RunStep events and typed event streams
• 🌳 Session trees — Branchable conversation history (not linear!)
• ⌨️ Interactive REPL — Debug and iterate on agents interactively

---

🎯 Why Phoson?

Traditional Frameworks	Phoson
Heavy dependencies	Zero external agent frameworks
Linear conversations	Branchable conversation trees
Black-box streaming	Full event visibility
Fixed patterns	Custom ReAct loop
Enterprise pricing	MIT licensed

---

✨ Features

Feature	Description
Framework-free	Pure Python + provider SDKs; no LangChain/LangGraph
Multi-provider	OpenAI, Anthropic, OpenRouter, Ollama support
Typed events	Normalized LLMEvent stream for all providers
Tool execution	@tool decorator with JSON Schema definitions
Middleware hooks	Pre/post processing for LLM calls and tool execution
Branching sessions	ConversationTree for non-linear conversation history
Interactive REPL	CLI with streaming, branching, and model switching
Cost tracking	Built-in pricing module for USD usage calculation
Thinking support	Native reasoning/thinking token handling (Anthropic & OpenAI o1)

---

🏗️ High-level architecture

flowchart LR
    U[App / CLI / API] --> AE[AgentEngine\nphoson_agent]
    AE --> MW[Middleware Hooks]
    AE --> T[Registered Tools]
    AE --> S[ConversationTree + Storage]
    AE --> C[BaseLLMChat Contract]
    C --> OA[OpenAIChat]
    C --> AN[AnthropicChat]
    OA --> P1[OpenAI / OpenRouter / Ollama]
    AN --> P2[Anthropic]
    OA --> E[Typed LLM Events]
    AN --> E
    E --> AE
    AE --> R[Agent Events + RunResult]

Runtime loop (tool call cycle)

sequenceDiagram
    participant Client
    participant Engine as AgentEngine
    participant LLM as LLM Adapter
    participant Tool as Tool Handler

    Client->>Engine: run(messages, config)
    Engine->>LLM: stream(history, config, tools)
    LLM-->>Engine: TokenEvent / ReasoningTokenEvent
    LLM-->>Engine: ToolCallEvent
    Engine->>Tool: execute(args)
    Tool-->>Engine: result/error
    Engine->>LLM: continue with ToolResultBlock
    LLM-->>Engine: UsageEvent + LLMDoneEvent
    Engine-->>Client: AgentRunResult

---

🗺️ Repository map

phoson-engine-minimal/
├── phoson_llm/           # LLM normalization layer (adapters + schemas + pricing)
├── phoson_agent/         # ReAct agent loop, tools, middleware, sessions
├── phoson_cli/           # Interactive CLI (REPL) for agent sessions
├── tests/                # Unit/integration tests for llm and agent layers
├── .github/workflows/    # CI and security automation
├── PROJECT.md            # Deep architecture notes and roadmap
└── pyproject.toml        # Project metadata, dependencies, tooling config

---

📦 Core modules

phoson_llm — LLM normalization layer

Provider adapters return a single typed event stream (LLMEvent subclasses):

Event	Description
LLMStartEvent	Call start (model, message count)
TokenEvent	Text fragment token-by-token
ReasoningStartEvent	Model started reasoning (Anthropic thinking / OpenAI o1)
ReasoningTokenEvent	Reasoning fragment
ReasoningDoneEvent	Complete reasoning block
ToolCallDeltaEvent	Partial tool args chunk (for real-time UI)
ToolCallEvent	Complete tool call with parsed args
UsageEvent	Tokens + cost in USD
LLMDoneEvent	Full assembled text (always last)
ErrorEvent	Error with code, message, retryable flag

Supported providers:

• Anthropic — AnthropicChat (thinking, tool use, prompt caching)
• OpenAI — OpenAIChat (tool use, reasoning_effort for o1/o3)
• OpenRouter — OpenAIChat(base_url=..., api_key=...)
• Ollama — OpenAIChat(base_url="http://localhost:11434/v1", api_key="ollama")

Pricing module (phoson_llm.pricing) provides calculate_cost() for provider-level USD usage.

phoson_agent — Agent orchestration

Stateless-by-run orchestration over message history with tool execution:

• AgentEngine — Main entry point for running agents (async and sync)
• @tool decorator — Transform Python functions into AgentTool definitions with JSON Schema
• AgentMiddleware — Hooks for pre/post processing (LLM calls, tool execution)
• AgentContext — Shared state across middleware and tools

phoson_agent.sessions — Conversation persistence

• ConversationTree — Branchable conversation structure (not linear)
• ConversationNode — Individual node with messages, children, label
• JsonlStorage — JSONL-backed session storage (local file)
• SessionMeta — Session metadata (id, message_count, created_at, updated_at)

phoson_cli — Interactive REPL

Command-line interface for interactive agent sessions:

• PhosonRepl — Interactive read-eval-print loop
• Commands: /exit, /quit, /clear, /new, /model, /tree, /sessions, /branch, /label, /help
• Real-time streaming responses
• Session branching and labeling
• Multiple model switching

---

🚀 Quick Start

from phoson_agent import AgentEngine
from phoson_llm.chats.openai import OpenAIChat
from phoson_llm.schemas import Message, ModelConfig

engine = AgentEngine(
    chat=OpenAIChat(),
    tools=[],
    phoson_weight=1.2,
)

result = engine.run_sync(
    messages=[Message(role="user", content="Summarize this project in one line")],
    config=ModelConfig(model="openai/gpt-4o-mini", max_tokens=128),
)

print(result.final_content)
print(result.total_cost_usd, result.total_credits)

Or run the interactive CLI:

uv run phoson-cli

Run the setup wizard to configure provider credentials and defaults:

uv run phoson-cli --setup

---

📥 Installation

# Clone the repository
git clone https://github.com/phoson-lat/phoson-engine-minimal.git
cd phoson-engine-minimal

# Install dependencies
uv sync --dev --locked

# Install git hooks
uv run pre-commit install --install-hooks
uv run pre-commit install --hook-type commit-msg
uv run pre-commit install --hook-type pre-push

---

🛠️ Development setup

Install dependencies

uv sync --dev --locked

Install git hooks

uv run pre-commit install --install-hooks
uv run pre-commit install --hook-type commit-msg
uv run pre-commit install --hook-type pre-push

---

✅ Run checks locally

uv run ruff format --check .
uv run ruff check .
uv run python -m compileall phoson_llm phoson_agent phoson_cli
uv run pytest -q

---

🔐 Environment variables

ANTHROPIC_API_KEY=
OPENAI_API_KEY=
OPENROUTER_API_KEY=

Note: Use OPENROUTER_API_KEY when initializing OpenAIChat with an OpenRouter base_url.

---

💻 Usage examples

Minimal agent usage

from phoson_agent import AgentEngine
from phoson_llm.chats.openai import OpenAIChat
from phoson_llm.schemas import Message, ModelConfig

engine = AgentEngine(
    chat=OpenAIChat(),
    tools=[],
    phoson_weight=1.2,
)

result = engine.run_sync(
    messages=[Message(role="user", content="Summarize this project in one line")],
    config=ModelConfig(model="openai/gpt-4o-mini", max_tokens=128),
)

print(result.final_content)
print(result.total_cost_usd, result.total_credits)

Define a tool

from phoson_agent import tool

@tool
def calculate(expression: str) -> str:
    """Evaluate a mathematical expression."""
    return str(eval(expression))

Interactive CLI

uv run phoson-cli

Available commands:

• /new — Start a new session
• /model <name> — Switch model
• /tree — Show conversation tree
• /sessions — List saved sessions
• /branch — Branch from current node
• /label <text> — Label current node
• /help — Show all commands

---

🔒 CI and security workflows

• .github/workflows/ci.yml: Format check, lint, smoke compile, and tests on PRs and pushes to main.
• .github/workflows/security.yml: Dependency audit and secret scan on PRs, pushes to main, and weekly schedule.

---

📝 Commit message format

Conventional Commits are enforced through a commit-msg hook.

Examples:

feat: add streaming chat abstraction
fix: handle unknown model pricing fallback
chore: update pre-commit hook versions

Common types: feat, fix, docs, refactor, test, chore, ci

---

🗓️ Roadmap

For detailed architecture notes and future plans, see PROJECT.md.

---

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'feat: add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

Please read CONTRIBUTING.md for details on our code of conduct and development process.

Ideas for contributions

• 🆕 Add new LLM providers (Google Gemini, Azure OpenAI, etc.)
• 🔧 Improve tool execution (batching, retries, caching)
• 📊 Add observability integrations (OpenTelemetry, Langfuse)
• 🖥️ Build a web-based REPL or playground
• 📚 Improve documentation and examples

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

MIT License

Copyright (c) 2024 Phoson

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

---

💬 Support

• Issues: GitHub Issues for bug reports
• Discussions: GitHub Discussions for questions
• Documentation: See PROJECT.md for deep architecture notes
• Website: https://phoson.lat
• SDK Docs: https://phoson.lat/docs

---

⭐ Show your support

Give us a ⭐️ if this project helped you build better AI agents!

---

Built with 🔥 by phoson.lat