forgebase 0.1.7

Cognitive Architecture Framework - Clean + Hexagonal Architecture with native observability. AI agent-friendly with programmatic API access.

ForgeBase

ForgeBase é o núcleo técnico do Forge Framework — a infraestrutura cognitiva onde o raciocínio do ForgeProcess se transforma em código observável, reflexivo e modular.

---

🤖 For AI Coding Agents

First time using ForgeBase? Access complete API documentation programmatically:

from forgebase.dev import get_agent_quickstart

# Get the full AI Agent Quick Start guide (embedded in package)
guide = get_agent_quickstart()
print(guide)  # Full markdown with examples and API reference

Available APIs for AI Agents:

from forgebase.dev.api import (
    QualityChecker,      # Code quality checks (ruff, mypy)
    ScaffoldGenerator,   # Generate boilerplate code
    ComponentDiscovery,  # Discover entities, usecases, ports
    TestRunner          # Run tests programmatically
)

# Example: Quality check before commit
checker = QualityChecker()
results = checker.run_all()

for tool, result in results.items():
    if not result.passed:
        for error in result.errors:
            # Each error has: file, line, column, code, message
            print(f"Fix {error['file']}:{error['line']} - {error['code']}")

Why this matters:

• ✅ Works offline (docs embedded in package)
• ✅ Structured, machine-readable results (not CLI text parsing)
• ✅ Auto-discovery of components and architecture
• ✅ Integrated quality checking and code generation

📚 Complete guide: See docs/agentes-ia/ for full documentation with error codes, data structures, and workflow examples.

---

⚡ Quick Start

Installation

# Install from GitHub
pip install git+https://github.com/symlabs-ai/forgebase.git

# Or clone for development
git clone https://github.com/symlabs-ai/forgebase.git
cd forgebase
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e ".[dev]"

For AI Agents (Programmatic Access)

# Documentation is embedded in the package - works offline!
from forgebase.dev import get_agent_quickstart

guide = get_agent_quickstart()  # Full API documentation
# Parse and use to discover available APIs

For Developers (CLI)

# Run quality checks
python devtool.py quality

# Generate boilerplate
python devtool.py scaffold usecase CreateOrder

# Run tests
python devtool.py test

---

🏗️ Estrutura do Repositório

forgebase/
├── docs/                 # Documentação completa (reorganizada)
│   ├── usuarios/         # Guias para desenvolvedores humanos
│   ├── agentes-ia/       # Documentação para AI agents
│   ├── referencia/       # Referência técnica e arquitetura
│   └── adr/              # Architecture Decision Records
├── examples/             # Exemplos de uso do framework
├── scripts/              # Scripts de desenvolvimento (scaffolding, discovery)
├── src/                  # Código-fonte do framework ForgeBase
│   └── forgebase/
│       ├── domain/           # Camada de Domínio
│       ├── application/      # Camada de Aplicação
│       ├── infrastructure/   # Camada de Infraestrutura
│       ├── integration/      # Adaptadores e integrações
│       └── observability/    # Sistema de observabilidade
├── tests/                # Testes (unit, integration, property-based, contract)
├── devtool.py           # CLI unificada para desenvolvimento
├── pyproject.toml       # Configuração do projeto (PEP 621)
├── setup.py             # Shim para backward compatibility
├── CHANGELOG.md         # Histórico de mudanças
├── CONTRIBUTING.md      # Guia de contribuição
├── VERSION.MD           # Versão atual do projeto
└── README.md            # Este arquivo

📂 Detalhamento das Pastas

docs/

Documentação completa do projeto, organizada por público-alvo:

• usuarios/ — Guias para desenvolvedores (início rápido, receitas, testes)
• agentes-ia/ — Documentação para AI agents (APIs, descoberta, ecossistema)
• referencia/ — Referência técnica (ForgeProcess, arquitetura, backlog)
• adr/ — Architecture Decision Records

examples/

Exemplos práticos de uso do framework:

• user_management/ — Sistema completo de gerenciamento de usuários
  • Demonstra Clean Architecture na prática
  • Inclui domínio (User, Email), aplicação (CreateUserUseCase) e infraestrutura (JSONUserRepository)

scripts/

Ferramentas de desenvolvimento:

• scaffold.py — Gerador de boilerplate (UseCases, Ports, Adapters)
• discover.py — Descoberta e catalogação de componentes
• mypy.ini — Configuração de type checking

src/forgebase/

Código-fonte seguindo Clean + Hexagonal Architecture:

domain/ — Camada de Domínio (núcleo do negócio)

• entity_base.py — Classe base para entidades com identidade imutável
• value_object_base.py — Classe base para value objects imutáveis
• exceptions.py — Exceções de negócio (BusinessRuleViolation, ValidationError)

application/ — Camada de Aplicação (orquestração)

• usecase_base.py — Classe base genérica para casos de uso
• port_base.py — Classe base para portas (abstrações de I/O)
• dto_base.py — Classe base para DTOs (Data Transfer Objects)

infrastructure/ — Camada de Infraestrutura (implementações)

• config/ — Gerenciamento de configurações (YAML, environment)
• repository/ — Implementações do padrão Repository
  • repository_base.py — Interface abstrata do Repository Pattern
  • json_repository.py — Repository com armazenamento em JSON (dev/testing)
  • sql_repository.py — Repository com SQLAlchemy (produção)

integration/ — Adaptadores externos

• Adaptadores para sistemas externos, APIs, etc.

observability/ — Sistema de observabilidade nativo

• Decoradores e utilitários para métricas, logging e tracing

tests/

Suíte de testes completa:

• unit/ — Testes unitários isolados
• integration/ — Testes de integração entre componentes
• property_based/ — Testes baseados em propriedades (Hypothesis)
• contract_tests/ — Testes de contratos entre camadas

devtool.py

CLI unificada para desenvolvimento:

python devtool.py scaffold      # Gerar boilerplate
python devtool.py discover      # Catalogar componentes
python devtool.py test          # Executar testes
python devtool.py lint          # Linters (Ruff, Mypy)
python devtool.py check-deps    # Validar dependências
python devtool.py check-arch    # Validar arquitetura
python devtool.py quality       # Suite completa de qualidade

📄 Arquivos de Configuração

pyproject.toml

Configuração moderna seguindo PEP 621:

• Metadados do projeto e dependências
• Configuração de ferramentas (pytest, mypy, ruff, coverage, deptry)
• Fonte única de verdade para todo o projeto

.import-linter

Validação de boundaries da Clean Architecture:

• Garante que camadas não violem dependências
• Domain não pode importar Application/Infrastructure
• Application não pode importar Infrastructure

VERSION.MD

Rastreamento da versão atual do projeto

CHANGELOG.md

Histórico detalhado de mudanças por versão

---

🧠 Filosofia

"Forjar é transformar pensamento em estrutura."

ForgeBase não é apenas um framework técnico — é uma arquitetura cognitiva que:

• Pensa: Cada componente carrega intenção e propósito
• Mede: Observabilidade nativa em todos os níveis
• Explica: Capacidade de auto-reflexão e documentação viva

Princípios Fundamentais

1. Reflexividade — O código entende e explica seu próprio funcionamento
2. Autonomia — Módulos independentes com contratos bem definidos
3. Coerência Cognitiva — Padrões consistentes em toda a arquitetura

---

🚀 Status do Projeto

Versão Atual: v0.1.7 (Production-Ready)

✅ Completo (FASE 1 - Foundation)

Domain Layer

• ✅ EntityBase com ID imutável (property-based)
• ✅ ValueObjectBase com igualdade estrutural
• ✅ Exceções de negócio (BusinessRuleViolation, ValidationError)

Application Layer

• ✅ UseCaseBase genérico (Generic[TInput, TOutput])
• ✅ PortBase para abstrações de I/O
• ✅ DTOBase para transferência de dados

Infrastructure Layer

• ✅ RepositoryBase (Repository Pattern do DDD)
• ✅ JSONRepository (thread-safe, development/testing)
• ✅ SQLRepository (SQLAlchemy, production-ready)
• ✅ ConfigLoader (YAML + environment variables)

Developer Tooling

• ✅ devtool.py (CLI unificada)
• ✅ Scaffolding (geração de boilerplate)
• ✅ Discovery (catalogação de componentes)
• ✅ Modern dependency management (pyproject.toml)
• ✅ Import standardization (100% absolute imports)
• ✅ Cross-platform support

Quality Assurance

• ✅ 84+ testes passing (unit + integration + property-based + contract)
• ✅ Mypy strict type checking
• ✅ Ruff linting + pre-commit hooks
• ✅ Import-linter (architecture boundary validation)
• ✅ Deptry (dependency hygiene)

🚧 Em Desenvolvimento (FASE 2)

Observability

• 🚧 Métricas nativas
• 🚧 Decoradores de observabilidade
• 🚧 Sistema de logging estruturado

Integration Layer

• 🚧 Adaptadores para sistemas externos
• 🚧 API adapters (REST, GraphQL)

📋 Backlog

Consulte o CHANGELOG.md para histórico detalhado de mudanças.

Consulte o docs/referencia/backlog.md para o roadmap completo com 54 componentes organizados em 8 fases.

---

📖 Documentação

Para entender a arquitetura completa, consulte:

Para Desenvolvedores

• ForgeBase Rules — Guia completo de regras e práticas
• Início Rápido — Instalação e primeiros passos
• Receitas — Exemplos práticos de uso
• Guia de Testes — Como executar e escrever testes
• CLI First — Filosofia de desenvolvimento CLI First
• Ambiente e Scripts — Setup de ambiente e ferramentas
• Extensão — Como estender ForgeBase

Para AI Agents

• Início Rápido — Quick start para agentes de IA
• Guia Completo — Referência completa de APIs
• Descoberta — Sistema de descoberta de APIs
• Ecossistema — Integração com ferramentas

Referência Técnica

• ForgeProcess — Ciclo cognitivo de desenvolvimento
• Arquitetura — Modularização do núcleo
• Backlog — Roadmap (8 fases, 54 componentes)
• Guia de Documentação — Padrões de docstrings

---

🛠️ AVISOS IMPORTANTES

• Nunca grave nada na raíz sem solitacao explicita do usuario
• Nunca de push no repositorio remoto sem solitacao explicita do usuario
• Nunca crie tags ou aumente versao do forgebase sem solitacao explicita do usuario
• A fonte da verdade sobre a versao atual, bem como historico sintetico pode ser encontrada em VERSION.md

🛠️ Tecnologias

• Python 3.11+
• Clean Architecture + Hexagonal Architecture
• Observabilidade Nativa (Logging, Métricas, Tracing)
• Test-Driven Development

---