felix-agent-sdk 0.1.0__tar.gz

felix_agent_sdk-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,17 @@
+# Felix Agent SDK — Code Ownership
+# https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
+
+# Core Felix modules — ported from Caleb's Felix framework
+/src/felix_agent_sdk/core/           @CalebisGross @jkbennitt
+/src/felix_agent_sdk/agents/         @CalebisGross @jkbennitt
+/src/felix_agent_sdk/communication/  @CalebisGross @jkbennitt
+/src/felix_agent_sdk/memory/         @CalebisGross @jkbennitt
+/src/felix_agent_sdk/spawning/       @CalebisGross @jkbennitt
+/src/felix_agent_sdk/workflows/      @CalebisGross @jkbennitt
+
+# Provider layer
+/src/felix_agent_sdk/providers/      @jkbennitt
+
+# Package infrastructure
+pyproject.toml                        @jkbennitt
+.github/                              @jkbennitt

felix_agent_sdk-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check src/
+
+      - name: Test
+        run: pytest tests/ -v --tb=short
+
+  build:
+    name: Verify package builds
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: "pip"
+
+      - name: Install build
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check wheel contents
+        run: unzip -l dist/*.whl

felix_agent_sdk-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,83 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: "pip"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check src/
+
+      - name: Test
+        run: pytest tests/ -v --tb=short
+
+      - name: Install build
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: package-distributions
+          path: dist/
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write  # Required for trusted publishing via OIDC
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: package-distributions
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: publish-testpypi
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # Required for trusted publishing via OIDC
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

felix_agent_sdk-0.1.0/.gitignore

@@ -0,0 +1,50 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+.env
+
+# IDE
+.vscode/
+.idea/
+*.iml
+
+# mypy
+.mypy_cache/
+.dmypy.json
+
+# pytest
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Docs
+site/
+docs/_build/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Databases
+*.db
+
+# Internal design docs (not for public repo)
+felix-agent-sdk-structure.md
+
+# Original monolith (split into src/felix_agent_sdk/providers/)
+felix_providers.py

felix_agent_sdk-0.1.0/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+All notable changes to Felix Agent SDK will be documented in this file.
+
+## [0.1.0] — 2026-03-19
+
+Initial public release of the Felix Agent SDK.
+
+### Core Geometry
+- `HelixGeometry` — 3D parametric helix with `get_position(t)`, `get_radius(z)`, `get_angle_at_t(t)`, `get_tangent_vector(t)`, `approximate_arc_length()`
+- `HelixConfig` — named presets: `default()`, `research_heavy()`, `fast_convergence()`
+- `HelixPosition` — phase-aware wrapper with exploration/analysis/synthesis boundaries
+
+### Agents
+- `Agent` base class with helix-aware positioning, temperature, and lifecycle
+- `LLMAgent` with provider integration, position-aware prompting, meta-cognitive evaluation
+- `ResearchAgent`, `AnalysisAgent`, `CriticAgent` specialized agents
+- `AgentFactory` with `create_agent()`, `create_specialized_team()`, custom type registration
+
+### Communication
+- `CentralPost` hub with O(N) message routing, phase-aware delivery, performance tracking
+- `AgentRegistry` with capacity management, role indexing, performance history
+- `Spoke` + `SpokeManager` with per-type handler registration, lazy async support
+- `Message` and `MessageType` enums for structured inter-agent communication
+
+### Memory
+- `KnowledgeStore` with confidence-tagged entries, domain filtering, relationship graph
+- `TaskMemory` with pattern recognition, strategy recommendations, execution history
+- `ContextCompressor` with hierarchical summarization strategies
+- Pluggable backend interface with `SQLiteBackend` as default
+
+### Providers
+- `BaseProvider` abstract interface: `complete()`, `stream()`, `count_tokens()`
+- `AnthropicProvider` — Claude models
+- `OpenAIProvider` — GPT models and OpenAI-compatible APIs
+- `LocalProvider` — LM Studio, Ollama via OpenAI-compatible endpoint
+- `auto_detect_provider()` — environment-based provider selection
+
+### Workflows
+- `FelixWorkflow` orchestrator: team spawn → rounds → convergence check → synthesis
+- `WorkflowConfig` with helix config, team composition, confidence threshold, synthesis strategy
+- `CollaborativeContextBuilder` with relevance scoring and deduplication
+- `WorkflowSynthesizer` with BEST_RESULT, COMPRESSED_MERGE, ROUND_ROBIN strategies
+- Pre-built templates: `research_config()`, `analysis_config()`, `review_config()`
+
+### Tokens
+- `TokenBudget` with position-aware allocation (exploration vs synthesis split)
+
+### Infrastructure
+- Pip-installable package with optional provider dependencies
+- 659 tests (unit + integration)
+- Python 3.10+ support
+- MIT license

felix_agent_sdk-0.1.0/CLAUDE.md

@@ -0,0 +1,114 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Hard Rules
+
+1. Use a venv at `.venv` for all development, testing, and execution.
+2. When porting code from the original Felix framework (`https://github.com/CalebisGross/felix`), Caleb's architecture decisions take precedence. Core algorithms stay identical; only the interface layer changes.
+3. Git attribution for ported/refactored code:
+   - **Ported code** (Caleb's algorithms, unchanged): `git commit --author="Caleb Gross <209704970+CalebisGross@users.noreply.github.com>"`
+   - **Refactored code** (Caleb's logic, new interfaces): add `Co-authored-by: Caleb Gross <209704970+CalebisGross@users.noreply.github.com>` trailer
+   - **New code** (provider layer, configs, tests, docs): normal commits
+4. Never commit `.env`, credentials, `*.db` files, or `felix-agent-sdk-structure.md` (internal design doc).
+5. All PRs require review from `@CalebisGross` (enforced via CODEOWNERS).
+
+## Project Overview
+
+`felix-agent-sdk` is a pip-installable Python SDK that extracts and repackages the internal Felix Framework into a provider-agnostic, open-source package for external developers.
+
+- **GitHub org:** [AppSprout-dev](https://github.com/AppSprout-dev)
+- **Public SDK repo:** `AppSprout-dev/felix-agent-sdk`
+- **Private Felix source:** `AppSprout-dev/felix` (original by Caleb Gross)
+- **Team:** Jason Bennett (@jkbennitt) — SDK lead. Caleb Gross (@CalebisGross) — original Felix author, required reviewer.
+
+## Build & Run Commands
+
+```bash
+# Setup
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+
+# Install with specific provider
+pip install -e ".[anthropic]"   # Claude models
+pip install -e ".[openai]"      # OpenAI models
+pip install -e ".[local]"       # LM Studio / Ollama
+pip install -e ".[all]"         # Everything
+
+# Testing
+pytest tests/
+pytest tests/unit/
+pytest tests/ -v --cov=src
+
+# Linting & type checking
+ruff check src/
+ruff format src/
+mypy src/
+```
+
+## Architecture
+
+### Package Layout
+
+```
+src/felix_agent_sdk/
+├── __init__.py          # Public API surface + version
+├── _version.py          # Single source of truth for version
+├── core/                # HelixGeometry, HelixConfig, HelixPosition
+├── agents/              # Agent, LLMAgent, specialized agents, AgentFactory
+├── communication/       # CentralPost, Spoke, messages, AgentRegistry
+├── memory/              # KnowledgeStore, TaskMemory, compression, pluggable backends
+├── providers/           # BaseProvider, Anthropic, OpenAI, Local (IMPLEMENTED)
+├── spawning/            # DynamicSpawning, ConfidenceMonitor, ContentAnalyzer
+├── workflows/           # Felix workflow runner + templates
+├── tokens/              # TokenBudgetManager, provider-aware counting
+├── streaming/           # StreamEvent types, StreamHandler
+└── utils/               # Logging, config loading, common types
+```
+
+### Key Design Decisions
+
+- **Provider abstraction** is the critical layer. Every provider implements `BaseProvider` with `complete()`, `stream()`, `count_tokens()`. This decouples all agent logic from specific LLM APIs.
+- **`openai_provider.py`** (not `openai.py`) avoids shadowing the `openai` package import.
+- **Helix model:** agents traverse `t ∈ [0,1]` along a 3D spiral. Top (t=0) = exploration, high temperature, broad search. Bottom (t=1) = synthesis, low temperature, focused output. Default: top_radius=3.0, bottom_radius=0.5, height=8.0, turns=2.0.
+- **Hub-spoke O(N)** communication via CentralPost. All messages route through the hub, never direct agent-to-agent mesh (O(N²)).
+- **Memory** uses pluggable backends with SQLite as default.
+- **Dynamic spawning** is confidence-driven. If team confidence drops below threshold, new agents spawn automatically.
+
+### Porting Reference
+
+The original Felix source is at `https://github.com/CalebisGross/felix`. Key files to port:
+
+| Felix source | SDK target | Notes |
+|---|---|---|
+| `src/core/helix_geometry.py` (186 lines) | `core/helix.py` | Add HelixConfig presets, HelixPosition |
+| `src/agents/agent.py` (372 lines) | `agents/base.py` | Extract AgentState, clean interface |
+| `src/agents/llm_agent.py` (2130 lines) | `agents/llm_agent.py` | Wire to BaseProvider (biggest refactor) |
+| `src/agents/specialized_agents.py` (578 lines) | `agents/specialized.py` | Keep Research, Analysis, Critic |
+| `src/agents/dynamic_spawning.py` (1204 lines) | `spawning/` | Split into focused modules |
+| `src/communication/central_post.py` (3210 lines) | `communication/` | Extract AgentRegistry, decouple memory |
+| `src/communication/spoke.py` (514 lines) | `communication/spoke.py` | Minimal changes |
+| `src/memory/knowledge_store.py` (2953 lines) | `memory/` | Add pluggable backend interface |
+| `src/memory/task_memory.py` (705 lines) | `memory/` | Pattern recognition |
+| `src/memory/context_compression.py` (564 lines) | `memory/` | Compression strategies |
+| `src/llm/token_budget.py` (331 lines) | `tokens/budget.py` | Provider-aware counting |
+| `src/workflows/felix_workflow.py` | `workflows/` | Add template system |
+
+### What NOT to Port
+
+- Tkinter/PySide6 GUI code
+- `exp/` benchmarking scripts (write new ones)
+- `linear_pipeline.py` (research baseline)
+- `lm_studio_client.py` / `multi_server_client.py` (replaced by provider layer)
+- CLI, API, execution/trust system, knowledge daemon
+
+## Phased Implementation
+
+- **Phase 1** (current): Package skeleton + provider layer
+- **Phase 2** `feat/core-geometry`: Port HelixGeometry, add HelixConfig/HelixPosition
+- **Phase 3** `feat/providers`: Tests for provider layer
+- **Phase 4** `feat/agents`: Port agent classes, wire to BaseProvider
+- **Phase 5** `feat/communication`: Port CentralPost, Spoke, messages
+- **Phase 6** `feat/memory`: Port KnowledgeStore, TaskMemory, ContextCompressor
+- **Phase 7** `feat/workflows`: Port workflow runner + templates

felix_agent_sdk-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing to Felix Agent SDK
+
+Thank you for contributing! This document covers setting up your development environment.
+
+## Development Setup
+
+```bash
+git clone https://github.com/AppSprout-dev/felix-agent-sdk.git
+cd felix-agent-sdk
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+```
+
+## Running Tests
+
+```bash
+pytest tests/
+pytest tests/ -v --cov=src
+```
+
+## Code Style
+
+We use `ruff` for linting and formatting:
+
+```bash
+ruff check src/
+ruff format src/
+mypy src/
+```
+
+## Submitting Changes
+
+1. Fork the repo and create a feature branch from `main`
+2. Write tests for new functionality
+3. Ensure `pytest` and `ruff` pass
+4. Open a pull request — `@CalebisGross` will review core modules
+
+## Branch Protection
+
+The `main` branch requires at least one approving review before merge.
+Direct pushes to `main` are not permitted after initial setup.
+
+## Git Attribution
+
+When porting code from the original Felix framework:
+
+- **Unchanged algorithms**: Use `git commit --author="Caleb Gross <209704970+CalebisGross@users.noreply.github.com>"`
+- **Refactored code**: Add `Co-authored-by: Caleb Gross <209704970+CalebisGross@users.noreply.github.com>` trailer
+- **New code**: Normal commits

felix_agent_sdk-0.1.0/LICENSE

@@ -0,0 +1,29 @@
+MIT License
+
+Copyright (c) 2026 Felix Framework
+
+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.
+
+---
+
+NOTICE: This is the Community Edition license. For commercial deployments,
+enterprise features, or air-gapped certifications, contact the maintainers
+about commercial licensing options.
+
+For commercial licensing inquiries, contact: [caleb@appsprout.dev]